Systems

Seasonal Events

Seasonal events are yearly calendar windows (for example Halloween, 18 Oct - 14 Nov). Content opts in with an eventId and is only available while that event is active. When the window closes the framework runs a wrap-up: prizes for the top players, currency conversions and resets.


Event Definition

Any pack can add config/seasonalevents/*.json:

{
  "events": [
    {
      "id": "halloween",
      "from": "10-18",
      "to": "11-14",
      "langPrefix": "alegacyevents:halloween",
      "infoKeys": ["wisps", "quests", "leaderboard", "end"],
      "pointsCurrency": "alegacyevents:halloween-points",
      "leaderboardSize": 10,
      "prizes": [
        { "fromRank": 1, "toRank": 3,
          "commands": ["/pet unlock {player} ghostlantern"],
          "messageLangKey": "alegacyevents:halloween-prize-top" }
      ],
      "resetCurrencies": ["alegacyevents:halloween-points"]
    }
  ]
}
FieldDefaultDescription
idrequiredEvent id used by eventId fields everywhere
from, torequiredMM-dd, inclusive, every year. from later than to wraps over New Year (12-20 to 01-05). Invalid dates skip the event with a warning
enabledtruefalse keeps the event permanently inactive
langPrefixnoneLang prefix for the event info tab on the event NPC ({prefix}-info-about, -info-howitworks-{key}, -info-tab)
infoKeys[]Sections of the info tab
pointsCurrencynoneReputation currency that ranks the leaderboard
leaderboardSize10Entries shown on the leaderboard
prizes[]Rank-based prizes (below)
conversions[]{ "from": currency, "to": currency, "rate": 0.5 } - every player's from balance becomes floor(amount * rate) of to
resetCurrencies[]Currencies set to 0 for everyone at the end

A prize has fromRank/toRank (default 1/1), a list of server commands run as console ({player} and {uid} are replaced) and an optional messageLangKey (receives the rank as {0}). Prizes for offline players wait and are delivered on their next login.

Duplicate ids: the later file wins (warning in the log). Unknown event ids always count as inactive, so a typo hides content instead of leaking it.


Tying Content To An Event

Set "eventId": "<id>" on these:

Event NPCs: seasonalpresence

Entity behavior that keeps an NPC in the world only while its event is active. Outside the window the entity is stashed in the save with its full state and put back at the same spot when the event opens again.

{ "name": "seasonalpresence", "eventId": "halloween", "unique": true }

unique: true allows only one such NPC in the world - spawning it again somewhere else removes the older copy. Leave it off for crowds such as spawned wisps.


Commands

All need the controlserver privilege.

CommandDescription
/avq event listEvents with their window and current state
/avq event on <id>Force an event on (survives restarts; ends automatically when its calendar window closes)
/avq event off <id>Force an event off
/avq event auto <id>Return to the calendar
/avq event top <id>Leaderboard by pointsCurrency
/avq event finish <id>Run the wrap-up now (prizes, conversions, resets). Irreversible
/avq event npcsStashed event NPCs and the spot they return to

Real example: quests/albase/assets/alegacyevents/config/seasonalevents/halloween.json.

Press ESC to close