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"]
}
]
}| Field | Default | Description |
|---|---|---|
id | required | Event id used by eventId fields everywhere |
from, to | required | MM-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 |
enabled | true | false keeps the event permanently inactive |
langPrefix | none | Lang prefix for the event info tab on the event NPC ({prefix}-info-about, -info-howitworks-{key}, -info-tab) |
infoKeys | [] | Sections of the info tab |
pointsCurrency | none | Reputation currency that ranks the leaderboard |
leaderboardSize | 10 | Entries 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:
- quests (Quest Structure) - hidden and unavailable outside the event
- shops (Shops)
- Night Spawns, Kill Drops and Block-Break Spawns rules
- world events (World Events)
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.
| Command | Description |
|---|---|
/avq event list | Events 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 npcs | Stashed event NPCs and the spot they return to |
Real example: quests/albase/assets/alegacyevents/config/seasonalevents/halloween.json.