⏰ Schedules & Conditions

EventForge can start events automatically using schedules.

There are two scheduling systems in v1.0.3:

per-event schedules
scheduled event votes

Per-event schedules live inside individual event files and start one specific event.

Scheduled event votes live in schedule_config.yml and start a player vote between multiple events.

Both systems use EventForge's normal event start flow, so cooldowns, conditions, active event checks, voting behaviour and manual queue participation still apply.

Per-event schedules

Per-event schedules are configured inside each event file.

schedule:
  enabled: true
  type: INTERVAL
  every: 30m
  announce-before:
    - 5m
    - 1m
    - 30s

This starts the event every 30 minutes and announces it before it begins.

Disable a per-event schedule

If you want an event to be started manually only, disable its schedule.

schedule:
  enabled: false

The event can still be started by command, API, manual voting, scheduled voting or compatible addons.

Interval schedules

Interval schedules repeat every configured amount of time.

schedule:
  enabled: true
  type: INTERVAL
  every: 1h

Supported time examples:

30s
5m
1h
2d

Announce before start

Use announce-before to warn players before an event begins.

schedule:
  enabled: true
  type: INTERVAL
  every: 30m
  announce-before:
    - 5m
    - 1m
    - 30s

This is useful for larger events where players need time to prepare.

Manual queue events from schedules

If a scheduled event uses manual participation, EventForge opens its queue instead of starting the event instantly.

participation:
  mode: MANUAL
  queue-duration: 30s
  min-players: 2

Scheduled flow:

schedule triggers
→ EventForge checks cooldowns and conditions
→ manual queue opens
→ players join with /events join <event>
→ event starts if enough players joined

This keeps scheduled events compatible with the v1.0.3 hype phase system.

Event cooldowns

Cooldowns stop an event from being started again too quickly.

cooldown:
  enabled: true
  duration: 1h

When the event finishes naturally, EventForge starts the cooldown.

While the cooldown is active, the event cannot be started manually, by schedule, by voting, by API, or through compatible addons.

Cooldown behaviour

Cooldowns work like this:

natural event finish starts the cooldown
forced stop does not start the cooldown
reload/shutdown does not start the cooldown
manual starts respect cooldowns
scheduled starts respect cooldowns
voting winners respect cooldowns
scheduled voting winners respect cooldowns
API starts respect cooldowns
Skript addon starts respect cooldowns through the API

tip

Use cooldowns for events that should feel special, such as boss fights, relic hunts, supply drops or larger competitions.

Cooldown persistence

Cooldowns are saved to:

plugins/EventForge/cooldowns.yml

This means cooldowns can survive restarts.

info

You usually do not need to edit cooldowns.yml manually.

Cooldown example

id: relic_hunt
enabled: true
display-name: "&6Relic Hunt"
duration: 5m

cooldown:
  enabled: true
  duration: 1h

schedule:
  enabled: true
  type: INTERVAL
  every: 30m
  announce-before:
    - 1m
    - 30s

In this example, the schedule checks every 30 minutes, but the event cannot start if it is still on cooldown.

Conditions section

Conditions decide whether an event is allowed to start.

conditions:
  minimum-players: 2
  worlds:
    - world

  permissions: []
  blocked-permissions: []

  require-op: false
  require-non-op: false

  time:
    enabled: false
    min: 0
    max: 23999

  weather:
    allowed: []

Minimum players

Require a minimum number of online players.

conditions:
  minimum-players: 5

If fewer than 5 players are online, the event will not start.

World conditions

Limit an event to certain worlds.

conditions:
  worlds:
    - world
    - world_nether

If the condition is enabled in your event setup, EventForge checks the allowed worlds before starting.

Permission conditions

Require players to have certain permissions.

conditions:
  permissions:
    - eventforge.events.mining

You can also block events for players with specific permissions:

conditions:
  blocked-permissions:
    - eventforge.blocked

OP conditions

Require operators:

conditions:
  require-op: true

Or require non-operators:

conditions:
  require-non-op: true

Most public events should leave both as false.

Time conditions

Minecraft time can be used as a start condition.

conditions:
  time:
    enabled: true
    min: 0
    max: 12000

Common time values:

= sunrise
= noon
= sunset
= midnight

Weather conditions

You can restrict events by weather.

conditions:
  weather:
    allowed:
      - CLEAR

Example with rain and thunder:

conditions:
  weather:
    allowed:
      - RAIN
      - THUNDER

Start checks

EventForge checks conditions before starting an event.

The API and compatible addons can read the start result and reason.

This is useful for:

custom GUIs
Discord bots
Skript menus
admin tools
start buttons

Example reason:

Event is currently on cooldown.

or:

Not enough players online.

Full per-event example

id: supply_drop
enabled: true
display-name: "&eSupply Drop"
duration: 10m

cooldown:
  enabled: true
  duration: 2h

schedule:
  enabled: true
  type: INTERVAL
  every: 1h
  announce-before:
    - 5m
    - 1m
    - 30s

conditions:
  minimum-players: 10
  worlds:
    - world

  permissions: []
  blocked-permissions: []

  require-op: false
  require-non-op: false

  time:
    enabled: false
    min: 0
    max: 23999

  weather:
    allowed: []

Scheduled event voting

EventForge v1.0.3 adds scheduled event votes.

Scheduled votes are different from per-event schedules. Instead of starting one fixed event, a scheduled vote starts a player vote between multiple configured event options.

Scheduled voting is configured in:

plugins/EventForge/schedule_config.yml

Scheduled voting is disabled by default so new installs keep the classic EventForge behaviour until you choose to enable it.

Enable scheduled voting

scheduled-voting:
  enabled: true

You can then enable individual scheduled votes under scheduled-voting.schedules.

Scheduled vote example

scheduled-voting:
  enabled: true

  schedules:
    hourly_vote:
      enabled: true
      type: INTERVAL

      every: 1h
      duration: 60s

      options:
        - mining_rush
        - mob_hunt
        - fishing_frenzy

      randomize-options: false
      randomize-amount: 3

      start-winner-automatically: true

      announce-before:
        - 5m
        - 1m

      require-no-active-events: true
      require-no-active-vote: true

This starts a vote every hour using the configured event options.

Players vote with:

/events vote <event>

The winning event starts through the normal EventForge start flow.

If the winner uses participation.mode: MANUAL, the event opens a manual queue first.

Scheduled vote options

Each scheduled vote can define:

ID
enabled state
schedule type
interval
vote duration
event options
random option selection
random option amount
automatic winner startup
pre-vote announcements
active-event skip rule
active-vote skip rule

Scheduled vote type

The first scheduled voting version supports:

INTERVAL

Example intervals:

1m
30m
1h
2h

Scheduled vote duration

duration controls how long the vote stays open once it starts.

duration: 60s

The duration must be at least 5s.

Scheduled vote options

options contains the event IDs that players can vote for.

options:
  - mining_rush
  - mob_hunt
  - fishing_frenzy

Each option must match a loaded EventForge event template ID.

Scheduled votes require at least 2 valid loaded event options.

Randomized scheduled votes

Scheduled votes can randomize their options each time they start.

randomize-options: true
randomize-amount: 2

With a larger option pool, EventForge randomly chooses 2 options for that vote.

randomize-amount must be at least 2 and cannot be higher than the amount of valid loaded options.

Scheduled vote announcements

Scheduled votes can broadcast countdown announcements before the vote starts.

announce-before:
  - 5m
  - 1m
  - 30s

The message text is controlled in messages.yml under:

scheduled-voting:
  announcement: "{prefix}&eA scheduled event vote &f{id} &ewill start in &f{time}&e."
  starting: "{prefix}&eStarting scheduled event vote: &f{id}&e."

Scheduled vote skip rules

Scheduled votes can skip if an event or vote is already active.

require-no-active-events: true
require-no-active-vote: true

If an event is active, the scheduled vote is skipped and rescheduled.

If another vote is active, the scheduled vote is skipped and rescheduled.

This prevents overlapping events and overlapping votes.

Scheduled vote validation

Scheduled voting is checked by:

/eventforge validate

You can also check schedule_config.yml directly:

/eventforge validate schedule_config.yml

Validation checks include:

scheduled-voting.enabled with missing schedules
invalid schedule type
invalid interval duration
vote duration below 5 seconds
missing options
unknown event IDs
duplicate options
fewer than 2 valid options
invalid randomize amount
invalid announce-before values

Viewing schedules in-game

Use:

/eventforge schedules

This command shows:

normal per-event schedules
scheduled event votes

Scheduled votes show their ID, time until next vote and configured option IDs.

Example:

Scheduled Event Votes
hourly_vote - Next Vote: 43m 20s - Options: mining_rush, mob_hunt, fishing_frenzy

Scheduled vote placeholders

Scheduled votes also have PlaceholderAPI support.

%eventforge_scheduled_vote_enabled%
%eventforge_scheduled_vote_count%
%eventforge_next_scheduled_vote%
%eventforge_next_scheduled_vote_time_left%
%eventforge_next_scheduled_vote_options%
%eventforge_next_scheduled_vote_option_ids%
%eventforge_scheduled_vote_time_left_<id>%
%eventforge_scheduled_vote_options_<id>%
%eventforge_scheduled_vote_option_ids_<id>%

Examples:

%eventforge_next_scheduled_vote%
%eventforge_next_scheduled_vote_time_left%
%eventforge_scheduled_vote_time_left_hourly_vote%
%eventforge_scheduled_vote_options_hourly_vote%

Troubleshooting

Scheduled event does not start

Check:

schedule.enabled is true
the schedule type is INTERVAL
the time format is valid
the event is loaded
the event is not already active
the event is not on cooldown
the event conditions pass

Scheduled vote does not load

Check:

scheduled-voting.enabled is true
the scheduled vote entry is enabled
type is INTERVAL
every is valid
vote duration is at least 5s
there are at least 2 valid loaded options
all option IDs match event template IDs
randomize-amount is valid

Run:

/eventforge validate schedule_config.yml

Scheduled vote skips

Check:

require-no-active-events
require-no-active-vote
currently active events
currently active votes

If a scheduled vote is skipped, EventForge reschedules it for the next interval.

Event says it cannot start

Check:

minimum players
cooldown
world conditions
permission conditions
time conditions
weather conditions

Event starts once but not again

Check whether the event is on cooldown.

cooldown:
  enabled: true
  duration: 1h

The cooldown starts after the event finishes naturally.

Cooldown did not start

Cooldowns do not start after a forced stop, reload, or shutdown.

They start after a natural event finish.

Cooldown still exists after restart

This is expected.

Cooldowns are saved in:

plugins/EventForge/cooldowns.yml

Per-event schedules

Disable a per-event schedule

Interval schedules

Announce before start

Manual queue events from schedules

Event cooldowns

Cooldown behaviour

Cooldown persistence

Cooldown example

Conditions section

Minimum players

World conditions

Permission conditions

OP conditions

Time conditions

Weather conditions

Start checks

Full per-event example

Scheduled event voting

Enable scheduled voting

Scheduled vote example

Scheduled vote options

Scheduled vote type

Scheduled vote duration

Scheduled vote options

Randomized scheduled votes

Scheduled vote announcements

Scheduled vote skip rules

Scheduled vote validation

Viewing schedules in-game

Scheduled vote placeholders

Troubleshooting

Scheduled event does not start​

Scheduled vote does not load​

Scheduled vote skips​

Event says it cannot start​

Event starts once but not again​

Cooldown did not start​

Cooldown still exists after restart​

Scheduled event does not start

Scheduled vote does not load

Scheduled vote skips

Event says it cannot start

Event starts once but not again

Cooldown did not start

Cooldown still exists after restart