Events

An event is a named period of the in-game calendar, such as Christmas or a weekly market day. It changes no season, weather or temperature by itself: it is a hook for chat messages, console commands, MythicMobs skills and other plugins.

Event files

Each event is one .yml file in plugins/MythicSeasons/events/, named by the id inside it. events.yml, custom-events.yml and subfolders are skipped. /ms reload loads the folder again. Every key is on Event Options.

id: christmas
display-name: "<red>Christmas"
type: dated
schedule:
  start: 25/12
  stop: 28/12
commands:
  start:
  - "<red>Christmas <green>has started!"

A complete event, active from 25 to 28 December of every in-game year.

Event dates are in-game dates, unless sync-time-with-real-world is on. With the calendar off, events start and stop only on /ms setdate, /ms nextseason, a real midnight in synced mode, or by hand with /ms event.

Shipped events

example ships disabled, the other four are enabled.

The dates are fixed: to move an event, change its dates in the file. For a new event, copy example.yml to a new file name, give it a new id and set enabled to true.

Schedule types

The type key picks one of these. A day change is any change of a world's date, see When an event starts and ends.

dated

Both dates are active days, so the stop lines run the day after schedule.stop. A range may cross the end of the year. See Date forms for how to write dates.

weekly

schedule.day is a name from week-days in calendar.yml, such as Saturday.

daily

The calendar never stops a daily event. Only /ms event stop runs its stop lines, and the event then counts as inactive until the next day change, /ms reload or restart.

id: daily-note
display-event: false
type: daily
commands:
  start:
  - "/say A new day has begun in %world%: %weekday%, %month_asname% %day%."

display-event: false keeps the event out of /ms getinfo.

When an event starts and ends

Each world with a season checks its events whenever its date changes, see How the date advances.

When an event starts, MythicSeasons fires the Bukkit event SeasonEventStart and sends the MythicMobs signal startEvent_<id> to the mobs in the world, then marks the event active in that world and runs the commands.start lines. If another plugin cancels the event, the signal still goes out, but the event does not become active and its start lines do not run.

When it ends, MythicSeasons fires SeasonEventEnd (it cannot be cancelled) and sends endEvent_<id>, marks the event inactive and runs the commands.stop lines.

A server start or /ms reload marks the events of the current date active without running lines or sending Bukkit events or signals.

• An event you disable or remove while it is active disappears without running its stop lines.
• With sync-time-with-real-world, start and stop dates that pass while the server is offline run no lines. With calendar-is-real-life-days: true, the offline days count as one date change after start-up, so an event wholly inside them neither starts nor stops.
• A world's first date is not a date change. An event whose range already contains it stays inactive there until the next /ms reload or restart, and its start lines do not run. See The date.

Commands that run

commands.start and commands.stop are lists of lines:

These placeholders are filled in first:

The date placeholders take the new date (a stop line shows the first day without the event) and are filled in only while the calendar is on. PlaceholderAPI placeholders work too, except those that need a player.

Quote every line. A line that begins with % is not valid YAML unquoted.

Per-world control

Reacting to events

MythicMobs conditions

The isEvent condition (alias event) is true while one of the ids in its e or event attribute (comma-separated, compared in lower case) is active in the world, even for events with display-event: false.

ChristmasSnowMessage:
  Cooldown: 600
  Conditions:
  - isEvent{e=christmas} true
  Skills:
  - message{m="Snow falls softly on Christmas day."} @PlayersInWorld{targetself=true}

Runs only during Christmas in the caster's world, at most once every 10 minutes per caster.

skill-triggers:
  world-tick:
  - ChristmasSnowMessage

In a season file such as seasons/winter.yml, this casts the skill every performance.skill-trigger-interval ticks in each world of that season with players, with the world's first player as the caster. See Season Options.

MythicMobs signals

When an event starts or ends in a world, all active MythicMobs mobs there get the signal startEvent_<id> or endEvent_<id>, with the id in lower case. Mobs react with the ~onSignal trigger.

FestiveCow:
  Type: COW
  Skills:
  - message{m="The festival has begun!"} @PlayersInRadius{r=30} ~onSignal:startEvent_christmas
  - message{m="The festival is over."} @PlayersInRadius{r=30} ~onSignal:endEvent_christmas

Only FestiveCow mobs in the world where Christmas starts or ends react.

Bukkit events

Other plugins can listen to SeasonEventStart and SeasonEventEnd, see Events API. After a cancelled start, SeasonEventEnd and the stop lines still happen when the date leaves the range.

Placeholders

• Display names come exactly as written, MiniMessage tags included.
• Weekly events, daily events and dated events with a plain day number are never the next event.
• The next-event placeholders and the next-event line of /ms getinfo ignore years, so an event such as 20/12/3 to 5/1/4 is announced every in-game year while it is not active. Once a one-time event has run, set enabled: false and run /ms reload.
• PlaceholderAPI can name a world: %ms_active_events_<world>%, %ms_next_event_<world>% and %ms_days_until_next_event_<world>%. MythicMobs reads the world of the entity the skill runs on, or of the caster. See Placeholders and PlaceholderAPI.

Commands

Angle brackets mark required arguments, square brackets optional ones. Without [world] your own world is used, and the console has to name one.

/ms getinfo [world]
Season, date, time, active events and the next event of the world.

/ms event list [world]
Prints Running: and Not running: with the event ids of the world. - means none.

/ms event start <event> [world]
Starts the event (id in any letter case) with the steps of an event start. Replies Event <id>: on.

/ms event stop <event> [world]
Stops it the same way, with its stop lines. Replies Event <id>: off.

/ms setdate <date> [world]
Sets the world's date. Events whose range the new date enters or leaves start or stop.

/ms reload
Reloads the event files and the active events.

• /ms event start and /ms event stop both answer:
  • Seasons are off in this world in a world without a season.
  • Unknown event, pick one of: <ids> for an unknown id.
  • Already on: <id> or Already off: <id> when the event is already in that state.
• /ms event start also answers:
  • Off in this world: <id> in a world in worlds-without-events or in the event's disabled-worlds.
  • Another plugin cancelled <id> when another plugin cancels the start.
• A start or stop by hand lasts until /ms reload or a restart works out the running events from the date again. A new day does not undo it, since a date change starts or stops a dated or weekly event only where its schedule begins or ends. A daily event you stop starts again at the next day change.

To test a schedule, move the world's date with /ms setdate from outside the event's range into it. Reply texts are in the language file.