Countdown Types

EzCountdown supports four primary countdown modes. Each section below explains when to use a mode, the exact YAML keys the plugin reads, an example you can paste into countdowns.yml, and short troubleshooting notes.

Important keys used by the plugin

• type - one of FIXED_DATE, DURATION, MANUAL, RECURRING (case-insensitive).
• display.types - list of enabled displays (e.g. ACTION_BAR, BOSS_BAR).
• display.bossbar.color / display.bossbar.style - optional per-countdown boss bar appearance keys. If present, display.bossbar.color must be a BarColor name (e.g. BLUE, RED) and display.bossbar.style must be a BarStyle name (e.g. SOLID, SEGMENTED_10). On reload the plugin will log a warning and fall back to defaults (BLUE / SOLID) for unknown values.
• messages.*, commands.end, zone - per-countdown messages, end commands, and timezone.

Fixed Date

Use this when you have a specific calendar date/time to count down to.

• YAML keys: type: FIXED_DATE and target: "YYYY-MM-DD HH:mm" (resolved using the countdown’s zone).
• Example

countdowns:
  new_year:
    type: FIXED_DATE
    target: "2026-01-01 00:00"
    running: true

• Notes
  • Ensure target is in the future for the configured zone or the countdown will be created stopped.

Duration

Use this when you want a countdown that runs for a fixed length of time (e.g., maintenance windows).

• YAML keys: type: DURATION and duration: "1h30m". The duration parser accepts s, m, h, d tokens and combinations like 1d4h30m.
• Example (24 hours)

countdowns:
  maintenance:
    type: DURATION
    duration: "1d"   # can also be written as "86400s"
    running: true

• Notes
  • If running: true the plugin will compute a target at creation (now + duration) and start immediately.

Manual

Same format as DURATION but does not auto-start - useful when you want to prepare a timer and start it later.

• YAML keys: type: MANUAL and duration: "30m".
• Control: use /countdown start <name> and /countdown stop <name> to operate the timer.
• Example

countdowns:
  manual_event:
    type: MANUAL
    duration: "30m"
    running: false

Recurring (yearly)

Recurring countdowns are currently yearly: they repeat each year on the configured month/day/time.

• YAML keys: type: RECURRING, recurring.month (1–12), recurring.day (1–31), recurring.time (HH:mm).
• Example (New Year’s Eve yearly)

countdowns:
  festival:
    type: RECURRING
    recurring.month: 12
    recurring.day: 31
    recurring.time: "23:59"
    running: true

• Notes
  • RECURRING computes the next occurrence and, when it completes, advances the next target by one year.
  • If you need weekly or monthly recurrence, use a DURATION with 7d and an end command to restart it, or run an external scheduler.

Clock-aligned recurring schedules

EzCountdown now supports clock-aligned recurring schedules which fire on natural clock boundaries (for example: every 2 hours at 00:00, 02:00, 04:00…). These are useful for announcements that must occur on the wall-clock rather than relative to server uptime.

• New YAML keys (per-countdown):
  • align_to_clock - boolean, enable clock-aligned scheduling when true (default false).
  • align_interval - duration string like 2h, 1d, 30m describing the alignment interval.
  • timezone - IANA timezone used to compute aligned boundaries (falls back to plugin default zone if omitted).
  • missed_run_policy - how to handle missed occurrences while the server was down. Values: SKIP (default), RUN_SINGLE, RUN_ALL.

When align_to_clock: true and align_interval is set, the plugin computes the next occurrence relative to the start of the day in the configured timezone and snaps to the next multiple of the interval. DST transitions are handled using java.time so daily and hourly alignments follow local time semantics.

Example: announce every two hours on the UTC clock

countdowns:
  regular_announce:
    type: RECURRING
    align_to_clock: true
    align_interval: "2h"
    timezone: "UTC"
    running: true

Auto restart and start-on-end

Add these optional keys to have a countdown automatically restart when it ends or to start another countdown when this one finishes.

• YAML keys:
  • auto_restart - boolean, when true the countdown will be restarted after it ends (default false).
  • start_countdown - string, the key of another countdown to start when this countdown ends (optional).
  • restart_delay_seconds - integer seconds to wait before performing the restart/start action (default 0).
• Semantics:
  • If auto_restart: true the manager will restart the same countdown when it ends. If auto_restart is omitted it defaults to false.
  • If auto_restart: false and start_countdown is set, the configured countdown will be started when this countdown ends.
  • restart_delay_seconds lets you delay the restart/start by the given number of seconds.
• Example

countdowns:
  example_event:
    type: DURATION
    duration: "1d"
    auto_restart: true
    restart_delay_seconds: 10
  other_countdown:
    type: DURATION
    duration: "2h"

Tips & common workflows

• To implement weekly repetition, create a DURATION countdown of 7d and add an end command that restarts it (see commands.end), or use external tooling to trigger /countdown start weekly.
• Use zone: "Europe/Amsterdam" (or any IANA zone) to control how fixed and recurring times are resolved.

Troubleshooting

• If a FIXED_DATE countdown is stopped on startup, verify the target is in the future for the configured zone.
• If RECURRING appears to wait a year, that is expected: the plugin treats recurring as annual.