⏰ Schedules & Conditions

EventForge can start events automatically using schedules.

You can also control when events are allowed to start using conditions and cooldowns.

Schedule section

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 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, 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.

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 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
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 will check 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.

In v1.0.1, the API and compatible addons can also 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 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: []

Troubleshooting

Scheduled event does not start

Check:

schedule.enabled is true
the schedule type is correct
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

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