Seasons & Leaderboards

Seasons provide recurring competitive periods with server-wide leaderboards. When a season ends, top players are rewarded and a new season begins.

Enabling Seasons

Seasons are disabled by default. Enable them in config/reverie/seasons.conf:

enabled = true
mode = "duration"
duration = "30 days"
autoRoll = true

Season Modes

Mode	Description	Example
`duration`	Season lasts a fixed duration from start	`"30 days"`, `"2 weeks"`
`calendar`	Season ends on a specific date	`"2025-12-31"`
`cron`	Season ends on a cron schedule	`"0 0 1 * *"` (1st of each month)

Leaderboard

The leaderboard tracks every player’s contest performance during the active season:

Metric	Description
Wins	Total contest wins (primary sort)
Total Contests	Number of contests entered
Total Score	Cumulative appeal score
Best Score	Highest single-contest score
Category Wins	Win breakdown per category

Players are ranked by wins first, then by total score as tiebreaker.

Season End

When a season ends:

Final leaderboard is compiled (top N entries, default 100)
End-of-season rewards are distributed to qualifying players
Historical record is saved to config/reverie/seasons/season_history/
Broadcast message announces the season end to all online players
If autoRoll = true, the next season starts immediately

Pre-End Warnings

Players receive countdown warnings at these intervals before season end: 60 minutes, 30 minutes, 10 minutes, 5 minutes, 1 minute.

End-of-Season Rewards

Configure rewards by leaderboard placement:

endRewards {
  1 = ["minecraft:netherite_ingot 5", "minecraft:nether_star 1"]
  2 = ["minecraft:netherite_ingot 3"]
  3 = ["minecraft:diamond 10"]
  10 = ["minecraft:gold_ingot 5"]   # Top 10 all receive this
}

Settings Reference

Field	Type	Default	Description
`enabled`	Boolean	`false`	Enable seasonal system
`mode`	String	`"duration"`	End trigger mode
`duration`	String	`"30 days"`	Duration (when mode = duration)
`calendarEnd`	String	`""`	End date (when mode = calendar)
`cron`	String	`""`	Cron expression (when mode = cron)
`namingPattern`	String	`"Season {number}"`	Display name pattern
`autoRoll`	Boolean	`true`	Auto-start next season
`leaderboardSize`	Int	`100`	Max leaderboard entries
`historyRetention`	Int	`12`	Seasons kept in history

Data Storage

Season data is persisted at:

config/reverie/seasons/
  current_season.json         # Active season state
  season_history/             # Past season results
    season_001.json
  player_stats/               # Per-player stats by season
    {seasonId}/
      {playerId}.json

Next Steps

Tournaments — Competitive events that feed into seasonal rankings
Season Config — Full configuration reference