README.md

EzCountdown

EzCountdown provides configurable countdown timers for events, launches, and maintenance windows across your server.

Features

• Fixed date, duration, recurring, and manual countdown modes.
• Display options: action bar, boss bar (1.9+), chat, title, and scoreboard.
• PlaceholderAPI support for %ezcountdown_<name>_days%, _hours, _minutes, _seconds, and _formatted.
• Customizable messages (messages.yml), permissions, and update intervals.
• Run console commands when countdowns finish.

Commands

See docs/commands.md for the full command list and usage.

Countdown Types

• Fixed date: Runs toward a specific date/time (e.g. 2026-01-01 00:00).
• Duration: Runs for a set amount of time starting immediately (or on create if enabled).
• Manual: Uses a duration but stays stopped until /countdown start is run.
• Recurring: Repeats on the same month/day/time every year.

Permissions

See docs/permissions.md for permission details.

Configuration

See docs/configuration.md for configuration details and examples.

Clock-aligned recurring schedules

You can configure recurring countdowns to align to real-world clock boundaries and specify a timezone. Example keys in countdowns.yml:

# every 2 hours on the UTC clock: 00:00, 02:00, 04:00...
my_recurring_countdown:
	type: RECURRING
	align_to_clock: true
	align_interval: "2h"
	timezone: "UTC"
	missed_run_policy: SKIP

Behavior:

• align_to_clock (default: false) enables clock alignment.
• align_interval accepts duration strings like 2h, 1d, 30m.
• timezone is an IANA ZoneId (e.g. Europe/London). If omitted the plugin default zone is used.
• missed_run_policy controls what happens if the server was down for one or more scheduled occurrences (defaults to SKIP).

See the full timezone reference for recommended IANA identifiers: docs/feature/timezones.md

Documentation

Comprehensive documentation is available in the docs/ folder. Quick links:

• Commands & Configuration

  • Commands
  • Configuration
  • Permissions

• Features

  • Countdown types
  • Teleport integration
  • Placeholder support
  • Discord integration
  • GUI editor
  • Firework shows
  • Display-specific docs:
    • Action bar
    • Boss bar
    • Chat
    • Title
    • Scoreboard

• API

  • API overview
  • EzCountdown API
  • Model: Countdown
  • Model: CountdownType
  • Events: CountdownStartEvent
  • Events: CountdownTickEvent
  • Events: CountdownEndEvent

Example

/countdown create new_year 2026-01-01 00:00

Teleporting Players on Countdown Start/End

You can configure a countdown to teleport all online players to a named location at the start or end:

countdowns:
	my_event:
		...
		teleport:
			start: spawn
			end: arena