Seasons

File: config/frontier/seasons/<name>.conf

Each .conf file in the seasons/ directory defines one competitive season. The filename (without extension) becomes the season ID. Seasons control which ladders are active, define milestones and rewards, and handle rating resets.

Quick Example

displayName = "Season 1 2026"
description = "Ranked season from 2026-01-01 to 2026-03-31"
startDate = "2026-01-01T00:00:00"
endDate = "2026-03-31T23:59:59"

ladders {
    singles {
        mainLadder = "singles"
        perWinCommands = []
        milestoneRewards = [
            { name = "Great Ball Rank", minRating = 1200.0, commands = ["give {player} cobblemon:great_ball 5"] }
            { name = "Ultra Ball Rank", minRating = 1400.0, commands = ["give {player} cobblemon:ultra_ball 3"] }
            { name = "Master Ball Rank", minRating = 1600.0, commands = ["give {player} cobblemon:master_ball 1"] }
            { name = "Beast Ball Rank", minRating = 1800.0, commands = ["give {player} cobblemon:beast_ball 1"] }
        ]
        seasonRewards = [
            { name = "Season Champion", topRank = 1, commands = ["give {player} cobblemon:master_ball 3"] }
            { name = "Top 10 Finish", topRank = 10, commands = ["give {player} cobblemon:ultra_ball 5"] }
            { name = "10 Win Milestone", minWins = 10, commands = ["give {player} cobblemon:rare_candy 3"] }
        ]
    }
}

Season Fields

Field	Type	Default	Description
displayName	String	"Season 1"	Human-readable season name.
description	String	""	Season description.
startDate	String	""	Start date in ISO-8601 format (e.g., "2026-01-01T00:00:00").
endDate	String	""	End date in ISO-8601 format (e.g., "2026-06-30T23:59:59").
ladders	Map	{}	Ladder bindings active during this season, keyed by binding ID.
ratingReset	String	"HARD"	Rating reset mode at season end: "NONE", "HARD", or "SOFT".
softResetCarryover	Double	0.5	For SOFT reset: fraction of rating above start to keep.

Rating Reset Modes

Mode	What Happens
NONE	Ratings carry over unchanged. Win/loss counters still reset.
HARD	All players reset to the ladder’s startRating. Counters reset to 0.
SOFT	Players keep a fraction of their earned rating. Counters reset.

The SOFT reset formula: startRating + (currentRating - startRating) * softResetCarryover

For example, with softResetCarryover = 0.5 and startRating = 1500:

• A player at 1800 resets to 1650 (keeps half the 300 they earned)
• A player at 1300 resets to 1400 (keeps half the -200 they lost)

Tip

SOFT reset with a 0.5 carryover is the sweet spot for most servers. It rewards high-rated players without making the next season start feel pointless.

Ladder Bindings

Each entry in ladders binds a ladder from ladders.conf into the season. You can optionally override ladder settings for the season.

Field	Type	Default	Description
mainLadder	String	"singles"	Ladder ID from ladders.conf to bind.
displayName	String?	null	Override display name for this season. null = use ladder default.
format	String?	null	Override the format. null = use ladder default.
battleType	String?	null	Override battle type. null = use ladder default.
startDate	String?	null	Override start date for this specific ladder. null = use season dates.
endDate	String?	null	Override end date. null = use season dates.
rating	RatingConfig?	null	Override rating config. null = use ladder default.
perWinCommands	List<String>	[]	Commands run after every win.
milestoneRewards	List<Reward>	[]	One-time rewards during the season.
seasonRewards	List<Reward>	[]	Rewards at season end based on final standing.

Reward Types

Per-Win Commands

Run after every match win. Good for small participation rewards:

perWinCommands = [
    "give {player} minecraft:diamond 1"
]

Milestone Rewards

Triggered during the season when a player first reaches a threshold. Checked after each match. Each milestone fires once per player (tracked in storage) and plays a sound notification.

milestoneRewards = [
    { name = "First Victory", minWins = 1, commands = ["say {player} earned their first win!"] }
    { name = "Veteran", minWins = 10, commands = ["give {player} cobblemon:rare_candy 5"] }
    { name = "Great Ball Rank", minRating = 1200.0, commands = ["say {player} reached Great Ball!"] }
]

Season-End Rewards

Triggered at the end of the season based on final standings. If the player is online, rewards run immediately. If offline, they’re queued and delivered on next login.

seasonRewards = [
    { name = "Participant", minWins = 5, commands = ["give {player} minecraft:gold_ingot 10"] }
    { name = "Top 10", topRank = 10, commands = ["give {player} cobblemon:master_ball 3"] }
    { name = "Champion", topRank = 1, commands = ["say {player} is the champion!"] }
]

Reward Fields

Field	Type	Default	Description
name	String	""	Display name of the reward.
minRating	Double?	null	Minimum rating required.
maxRating	Double?	null	Maximum rating for this tier.
minWins	Int?	null	Minimum wins required.
maxWins	Int?	null	Maximum wins for this tier.
topRank	Int?	null	Top N rank required (e.g., 1 = first place only).
commands	List<String>	[]	Commands to run when granting the reward.

When multiple conditions are specified (e.g., minRating + minWins), all must be met (AND logic).

Command Placeholders

Available in perWinCommands and reward commands:

Placeholder	Description
{player}	Player name.
{rating}	Current or final rating (formatted as integer).
{tier}	Current tier name (e.g., “Ultra Ball”).
{wins}	Total wins.
{losses}	Total losses.
{rank}	Final rank (season rewards only).
{ladder}	Ladder ID.

Season Lifecycle

1. Active Detection — Frontier checks if the current time falls within any season’s startDate..endDate range. The first matching season is active.
2. During Season — Players queue, play matches, and earn milestone rewards. All matches are tagged with the season ID.
3. Season End — When endDate passes:
   • Season-end sound plays for all online players.
   • Final standings are archived to frontier_season_archives.
   • Season rewards are distributed to eligible players.
   • Ratings reset according to ratingReset mode.
   • Win/loss/streak counters reset to 0.

Full Season Example

displayName = "Season 2"
description = "Summer Championship"
startDate = "2026-07-01T00:00:00"
endDate = "2026-09-30T23:59:59"
ratingReset = SOFT
softResetCarryover = 0.5

ladders {
    singles {
        mainLadder = "singles"
        displayName = "Summer Singles"
        perWinCommands = [
            "give {player} minecraft:diamond 1"
        ]
        milestoneRewards = [
            { name = "First Victory", minWins = 1, commands = ["say {player} earned their first win!"] }
            { name = "Veteran", minWins = 10, commands = ["give {player} cobblemon:rare_candy 5"] }
            { name = "Great Ball Rank", minRating = 1200.0, commands = ["say {player} reached Great Ball!"] }
            { name = "Ultra Ball Rank", minRating = 1400.0, commands = ["give {player} cobblemon:ability_capsule 1"] }
            { name = "Master Ball Rank", minRating = 1600.0, commands = ["give {player} cobblemon:master_ball 1"] }
        ]
        seasonRewards = [
            { name = "Participant", minWins = 5, commands = ["give {player} minecraft:gold_ingot 10"] }
            {
                name = "Competitor"
                minWins = 15
                minRating = 1200.0
                commands = ["give {player} cobblemon:rare_candy 10"]
            }
            { name = "Top 10", topRank = 10, commands = ["give {player} cobblemon:master_ball 3"] }
            { name = "Champion", topRank = 1, commands = ["say {player} is the Summer Singles Champion!"] }
        ]
    }
}

Caution

Season date ranges shouldn’t overlap. If two seasons are both active, only the first one found takes effect. Plan your season dates back-to-back or with gaps between them.