Seasons System

Status: VISION LOCKED 2026-07-25 — competitive power contract approved; implementation pending

Last updated: October 28, 2026

Darkness Falls - Seasons System Design

Status: VISION LOCKED 2026-07-25 — competitive power contract approved; implementation pending

Overview

Darkness Falls uses a seasonal competitive system where players progress through 4-month themed seasons. Each season provides a fresh competitive environment with seasonal leaderboards, unique trophies, and themed content. Characters are never lost - they migrate to the permanent Standard tier when a season ends, keeping all their progress.

Design Goal: Create recurring engagement cycles with seasonal urgency while keeping the ranked race fair. Seasonal achievements become permanent collection and Standard-mode value after migration; they do not make a veteran or paying player stronger in the next Current Season.

Current status — 2026-07-25

Surface	Current behavior	Target / gap
Season storage	Enum, character season, per-season stash/currency, season-filtered auction listings, and pending-currency tagging exist. Current live characters remain `EARLY_ACCESS`.	Configuration, new-character routing, migration, badges, and lifecycle operations are not implemented.
Competitive rankings	Per-season leaderboard persistence and basic level/power queries exist. Current Season is not open.	Reward-bearing Current Season metrics must consume only season-earned inputs; reward distribution and hall-of-fame freeze remain gaps.
Account power	Trophy, subscription, Mastery, and other account-level consumers are not comprehensively suppressed by season.	Every prohibited consumer needs an explicit Current Season gate before launch.
Paid value	The live $1.99/month subscription grants five Blood Emeralds plus a rare-or-better item daily, along with Standard power/pace benefits.	Blood Emeralds may accrue in Current Season; the daily item routes to a Standard claim, while XP, gold, teleport, survival, loot, equipment, and other mechanical benefits remain suppressed.
Fairness proof	`DarknessFallsSeasonParityGate` scaffolding LIVE; fixture list named; competitive launch returns false.	Full entitlement-on vs entitlement-off suite still required before Current Season opens.

Season Types

Season	Purpose	Duration	Who Joins
EARLY_ACCESS	Pre-launch balance and testing	Indefinite (until launch)	All current players
CURRENT_SEASON	Active competitive season	4 months, themed	New players + veterans starting fresh
STANDARD_SEASON	Permanent home for all characters	Permanent	Characters migrated from ended seasons

Key Distinction: Migration is NOT a Reset

When a season ends, characters do NOT reset. They migrate to STANDARD_SEASON with all their level, gear, gold, and progress intact. The only thing that changes is they can no longer compete for that season's leaderboards or earn that season's exclusive trophies. They continue playing normally in Standard.

EARLY_ACCESS to Launch Transition

When the game officially launches:

All EARLY_ACCESS characters migrate to STANDARD_SEASON
Season 1 begins as CURRENT_SEASON with a theme
New players entering after launch join CURRENT_SEASON
EARLY_ACCESS enum remains for legacy data but no new characters use it

Switching modes

A player's mode is the character they play: a Standard hero or a Current Season hero. There is no mode toggle; a player switches modes from the character menu, by saying characters and then playing or creating a hero of the other kind. DarknessFallsModeSwitchHint.HOW_TO_SWITCH_MODES is the one sentence that says so, and it is said in two places:

every help reply, after its first line ();
the hideout, the first time a character stands in it, once (DarknessFallsModeSwitchHint.sayOnceAtTheHideout, from the hideout guide in ). The character keeps that it heard it beside the squares whose intro it has heard, so a relaunch does not repeat it.

Account-Level vs Character-Level Systems

Critical architectural clarification:

System	Level	Rationale
Warbands	Account	Social group, persists across all characters and seasons
Guilds	Account	Social organization, not tied to any character
Friends	Account	Social connections are permanent
Login streak	Account	Engagement tracking, not character-specific
Trophy room	Account	Collection persists; mechanical bonuses apply in Standard and are suppressed in Current Season
Blood emeralds	Account	Premium currency, paid with real money
Character slots	Per-season pool	1 slot = 1 STANDARD + 1 CURRENT character simultaneously
Gold/resources	Character	Season-locked on the character
Equipment	Character	Earned through gameplay
Star map	Character	Part of character power curve

Locked Competitive Power Contract

Current Season is a fresh race. A reward-bearing seasonal result MUST come only from the character's play in that season.

The rule

While a CURRENT_SEASON character is active:

Account trophies, Mastery perks, inherited hideout power, and mechanical rewards from earlier seasons MUST remain visible but mechanically inactive.
Paid benefits that change combat, movement, survival, inventory capacity, loot quality or rate, currency or experience rate, death cost, encounter access, or a leaderboard metric MUST be suppressed. The action MUST refuse cleanly and charge nothing when suppression cannot be automatic.
Premium equipment and purchased trophies MUST NOT be equipped or activated.
Trophies earned during the season may display immediately, but their mechanical bonuses activate only after the character migrates to Standard.
Current Season Power Level and every reward-bearing leaderboard MUST exclude account age, entitlements, purchased slots, prior trophies, prior Mastery, and paid modifiers.
Blood Emeralds may accrue to the account. A currency balance is not power until it is spent, and spending it on a prohibited Current Season effect remains blocked.

Paid-benefit eligibility

Benefit	Current Season	Standard
Cosmetics, titles, badges, hideout presentation	Active	Active
Blood Emerald packs and account balance	May accrue; prohibited power spends remain blocked	Active
Extra character slots	Active access benefit; one reward-eligible result per account per category	Active
Outcome-neutral automation	Active only when it reproduces a free action without improving rate or result	Active
Subscription XP/gold bonus	Suppressed	Active
Subscriber daily five Blood Emeralds	May accrue to the account; prohibited power spends remain blocked	Active
Subscriber daily rare-or-better item	Route to a Standard claim; never enters Current inventory or stash	Active
Subscriber enemy-blocked teleport bypass	Suppressed	Active
Subscriber five-slot carried-inventory bonus	Suppressed	Active
Paid combat, loot, movement, survival, or death-protection consumables	Unavailable; refuse and charge nothing	Active
Premium equipment and purchased trophy power	Unavailable	Active
Account trophy and Mastery bonuses	Visible, mechanically inactive	Active

Leaderboard treatment

Current Season rankings are competitive and may grant rewards.
One account may receive only one placement reward in each leaderboard category per season.
The Current Season Power Level formula uses only the active character's level, gear, Star Map, and other power earned inside that season.
Standard and all-time boards are record books and showcases when paid or inherited power affects them. They MUST NOT grant competitive rewards unless their metric is normalized to remove that power.

Ship gate

Current Season MUST NOT launch until a deterministic parity suite proves that the same seeded seasonal character produces identical combat stats, rewards, movement access, survival rules, and leaderboard metrics with entitlements and prior-account progression both on and off.

Phase 0 entitlement parity test plan

Each parity case runs twice from clean state with the same CURRENT_SEASON character, fixed world fixture, fixed equipment, and deterministic random seed:

Control account: no subscription, no purchased consumables/equipment/trophies, no prior trophies or Mastery.
Loaded account: active subscription, maximum prior trophies and Mastery, purchased Standard equipment and consumables, extra slots, and an account Blood Emerald balance.

The two runs MUST match on every power-bearing result. Cosmetic and account-balance differences are allowed only where the eligibility table above says they are.

Fixture	Commands / trigger	Required parity assertions
Basic and elite combat	Same attacks against seeded normal and elite enemies	Starting stats, damage dealt/taken, crit/resist behavior, rounds, death/victory, XP, gold, item rarity, and `combat_metrics` fields match.
Movement and retreat	Move across a rate cap; attempt enemy-blocked teleport	Distance and access match. Subscriber bypass does not fire.
Death	Die with subscription, charm, anchor, trophies, and Mastery present on the loaded account	Revive state, XP loss, item loss, location, and available recovery actions match; no paid protection is consumed or charged.
Loot and progression	Kill a seeded enemy with paid loot/XP/gold effects present	Drops, rarity, pickup value, XP, gold, and progression counters match; prohibited counters remain unconsumed.
Equipment and trophies	Attempt to equip/activate purchased or inherited mechanical items	Both attempts leave Current Season combat state unchanged; loaded-account attempt refuses before charge.
Leaderboards	Submit the same completed run	Current Season Power Level, rank metric, tie behavior, and reward eligibility match; only one reward-eligible entry exists per account/category.
Cosmetic/account allowance	Launch and inspect with subscriber badge/cosmetics and daily grant	Cosmetics may differ and five Blood Emeralds may accrue. The rare item routes to a Standard claim; no Current inventory, stash, character currency, or ranked metric changes.

Test surfaces: calculation-level JUnit for each suppression consumer; hermetic game_test.scenario_tests for purchase/equip/refusal and player-visible state; one paired integration runner that diffs the complete allowlisted gameplay snapshot.

Entry: all Current Season gates and ranking consumers are implemented. Exit: every fixture passes twice from clean state, the paired snapshot contains no unexplained difference, prohibited purchase attempts charge nothing, and the affected full Darkness Falls scenario suite is green.

Seasonal Themes

Each season has a unique theme that affects:

Exclusive season trophies (visual + mechanical)
Seasonal zone modifiers or events
Leaderboard categories
Cosmetic rewards for participation

Example themes: Infernal Onslaught, Frozen Wastes, Plague Tide, Shadow Eclipse

Trophy System (Cross-Season Core Loop)

Trophies are the primary cross-season collection and Standard-progression system. They are account-level and persist forever. Their mechanical bonuses apply to Standard characters; Current Season characters may display them but receive no mechanical effect.

Trophy Categories

Category	Availability	Purpose
Landmark trophies	Every season	Achievements anyone can earn (kill 1000 enemies, reach level 50, etc.)
Ranked trophies	Every season	Better trophies for top performers (top 1%, 10%, 25%)
Season-exclusive trophies	Specific season only	Themed trophies that can ONLY be earned during that season

Cross-Season Trophy Value

A player who has played three seasons keeps the trophies from all three:

The collection remains visible in every season.
Titles, badges, and cosmetic displays remain active.
Mechanical bonuses remain active on Standard characters.
Mechanical bonuses are suppressed on Current Season characters.

Veterans therefore retain history and permanent Standard value without receiving a ranked advantage over a first-season player.

Trophy Activation

Players choose which trophies to activate (limited slots based on trophy room level)
Active trophies provide bonuses to Standard characters. Current Season activation controls display and the future Standard loadout but applies no mechanical effect.
Trophy room is accessible from the hideout in any season

What is Season-Scoped

Component	Season-Scoped?	Notes
Character level and XP	Per-character	Characters in CURRENT start fresh, but keep everything on migration
Gold	Per-character	Stays with the character, not shared across characters
Equipment and inventory	Per-character	Stays with the character
Stash tabs	Per-season on account	CURRENT and STANDARD each have their own stash
Auction house listings	Per-season	Players only see same-season listings
Star map progress	Per-character	Earned by the character, stays with them
Quest progress	Per-character	Stays with the character
Seasonal leaderboards	Per-season	Frozen at season end, hall of fame (the freeze is NOT BUILT, see End-of-Season Flow)
Season-exclusive trophies	Per-season	Can only be EARNED during that season

Cross-Season Restrictions

Party System

Players CANNOT party across seasons
A CURRENT_SEASON character cannot join a party with a STANDARD_SEASON character
Validation: party invite handler checks both players characterSeason matches
Error: "That player is in a different season. You can only party with players in the same season."

Auction House

Already season-scoped in code ( filters by seasonRef)
Players only see listings from their own season

Warband and Guild (Account-Level)

Membership persists across seasons (account-level)
Warband combat bonuses only count same-season members
Guild chat works cross-season (social feature)
Guild war stats are season-scoped
UI clearly shows which members are in which season

End-of-Season Flow

When a season ends:

Leaderboard snapshot - Final rankings frozen permanently (hall of fame)
Season rewards distributed - Ranked trophies, blood emerald bonuses, cosmetic titles
Character migration - All CURRENT_SEASON characters get characterSeason = STANDARD_SEASON
Characters keep everything - Level, gear, gold, quests, progress all intact
Seasonal trophies lock - Can no longer earn that seasons exclusive trophies
New season begins - Fresh CURRENT_SEASON with new theme, trophies, challenges

Status: steps 1 and 2 are NOT BUILT for the themed season, and nothing runs the flow. Steps 3 and 6 exist as (migrate, then write the new season number and theme), which has no caller: no batch job, no admin endpoint, no scheduled event.

Step 1, the hall-of-fame freeze. Nothing freezes a themed season's final rankings. The live leaderboard row is written and read by game_type and season_type (mappers/leaderboard/game-leaderboard-mapper.xml), and season_type is the lane name CURRENT_SEASON, not a season number, so a second season would update the first season's rows in place. No command reads a past season's standings back to a player.
Step 2, reward distribution. No code ranks a finished season into the top 1, 10 and 25 percent, grants a ranked trophy, a title or a badge, or pays the Blood Emeralds in the table below.

What does run is a different, weekly ladder, and it is not this flow: (engine/prestige.md § 3) closes a week every Monday, copies the top ten Darkness Falls characters by level into claude.leaderboard_season_snapshot, and queues 1000 gold for ranks one to three and 500 gold for ranks four to ten. It ranks every character of the game together whatever its season, keeps ten rows, pays gold only, and knows nothing of the themed season's number, theme or end date. The snapshot table is the natural home for the freeze when it is built; the weekly payout is not a substitute for the rewards below.

Season Rewards

NOT BUILT — every row below, the Season badge included.

Rank	Reward
Top 1%	Exclusive ranked trophy (season-themed, strongest Standard bonus) + 500 blood emeralds + title
Top 10%	Ranked trophy (good Standard bonus) + 200 blood emeralds + badge
Top 25%	Participation trophy (minor Standard bonus) + 100 blood emeralds
Participated	Season badge + 50 blood emeralds

Stash Management and Gear Cannibalization

Stash Per-Season

CURRENT_SEASON has its own stash tabs
STANDARD_SEASON has its own stash tabs
When migrating, season stash contents remain accessible under STANDARD

Gear Cannibalization (Prevents Bloat)

Players need mechanisms to break down old gear accumulated across seasons:

Salvage at workbench - Already implemented, converts gear to gold and crafting materials
Rune extraction - Already implemented as part of salvage: a rare item returns an awakening rune, a legendary item returns two awakening runes and an empowering rune, and the higher rune of each rarity needs item level above 40 or 60. is the definition; pins it. There is no separate extract command.
Trophy crafting - Combine excess gear into trophy materials (future)
Bulk salvage - Already implemented: "salvage all" and "salvage junk" at the workbench (items-economy.md § Bulk Salvage)

Season Calendar

3 seasons per year, no gaps between seasons.

Season	Duration	Theme Example
Season 1	Jan - Apr	Infernal Onslaught
Season 2	May - Aug	Frozen Wastes
Season 3	Sep - Dec	Shadow Eclipse

World Multiplayer (Auto-Matchmaking)

Toggle

Players can toggle World Multiplayer on/off at any time via settings or voice command ("turn on multiplayer" / "turn off multiplayer"). Default: ON for new players.

How It Works

When World Multiplayer is enabled:

Auto-party matching — As you explore, the system matches you with other players of similar level (within 5 levels) in the same or adjacent zones
Seamless join/leave — Players flow in and out of parties naturally as they move through zones. No manual invite needed.
Party size — Auto-matched parties are 2-4 players
Same-season only — Auto-matching respects season boundaries (CURRENT_SEASON players only match with CURRENT_SEASON)
Opt-out respected — Players with multiplayer OFF are invisible to the matcher

Multiplayer Rewards (Encourage Grouping)

Status: BUILT for kills in a party's shared zone instance (party-combat.md § Party-size bonus). The party size of a kill is the killer plus the present allies within ten squares who share it, capped at four. Each amount multiplies the reward once, after every other modifier, and only rewards earned from a kill: the Rare Drop Bonus raises the magic find a drop rolls with. holds this table and is the one place the code reads it; where the two differ, the code is right. A solo kill pays exactly what it always did. The auto-party matching above is not built: a party is formed through the chat system.

Playing in a party provides scaling bonuses:

Party Size	Gold Bonus	XP Bonus	Drop Rate Bonus	Rare Drop Bonus
Solo	0%	0%	0%	0%
2 players	+15%	+10%	+10%	+5%
3 players	+25%	+20%	+15%	+10%
4 players	+40%	+30%	+25%	+15%

These bonuses stack with warband bonuses.

Matchmaking Criteria

Level range: Within 5 levels of each other
Zone proximity: Same zone or adjacent connected zones
Season: Must be same season
Activity: Only match with players who have been active in the last 5 minutes
Existing party: Prefers adding to existing parties over creating new ones

Design Intent

Multiplayer should feel natural and rewarding, not like a chore to set up. The auto-matchmaking removes friction while the reward bonuses make grouping always feel worth it. Players who prefer solo can turn it off anytime without penalty.

Character Zone and Slot System

Character Zone

The CHARACTER_ZONE is a dedicated zone accessible from the hideout where players manage their character roster. Each square on the grid represents a character slot.

Slot Flow:

Player enters Character Zone from hideout
Grid displays owned slots - occupied slots show character info, empty slots show "available"
Player can: swap to a character, create new character in empty slot, delete a character, or purchase more slots

Slot Progression Per Season

Status: NOT BUILT. An account holds three characters in total, whatever their season: is 3, and and count every character on the account against it. There is no per-season pool, no growth by season, and no slot purchase; the Blood Emerald shop has no character slot item (monetization.md § 2.2).

Character slots increase each season to reward returning players:

Season	Base Slots	Purchasable	Max Total	Cost Per Extra Slot
Season 1	3	+2	5	Blood emeralds (progressively more expensive)
Season 2	5	+2	7	Blood emeralds
Season 3	7	+2	9	Blood emeralds
Season 4	9	+1	10	Blood emeralds
Season 5+	10	+1	11	Blood emeralds (caps at +1/season after S4)

Per-season slot counting: A player with 3 slots can have up to 3 CURRENT_SEASON characters AND separately up to 3 STANDARD_SEASON characters. Slots are per-season pools, not shared.

Slot purchase pricing: Progressive cost in blood emeralds. Example: Slot 4 = 100 BE, Slot 5 = 250 BE, Slot 6 = 500 BE, etc.

Character Swapping

Stored as DarknessFallsAccount.currentCharacterRef
Swapping cleans up old zone state and loads new character into their last zone
Available anytime from the Character Zone (accessible from hideout)

When a player logs in and loads a STANDARD_SEASON character, they receive a prominent warning:

"You are playing a Standard character. Standard characters cannot compete for seasonal leaderboards or earn seasonal rewards. To participate in the current season, switch to a Current Season character from the Character Zone."

This warning:

Displays once per session (not every action)
Includes a shortcut option to go to Character Zone
Does NOT block gameplay - Standard characters play normally
Reminds returning players that seasonal content exists

Verification Results

All account-level systems confirmed via code audit:

System	Storage	Confirmed
Warbands	chat.chat_warbands (JSON), keyed by chatRef	Account-level
Guilds	chat.chat_guilds (JSON), keyed by chatRef	Account-level
Login streaks	.loginDetails.currentStreak	Account-level
Trophy room	DarknessFallsAccount.ownedCosmeticsAndTrophies	Account-level; current code applies bonuses to all characters, so Current Season suppression is an implementation gap
Blood emeralds	.currencyLedgers["blood_emeralds"]	Account-level, shared balance
Character switching	DarknessFallsAccount.currentCharacterRef	Works via zone cleanup + reload

Themed Seasons Design

Season 1: Infernal Onslaught (Fire Theme)

Color Palette: Crimson, orange, ember glow Narrative: The demon invasion intensifies. Portals to the Infernal Plane tear open across the world, unleashing fire elementals and empowered demon lords.

Season 1 Trophies

Landmark Trophies (earnable every season):

Trophy	Requirement	Bonus
First Blood	Defeat 100 enemies	+2% damage
Veteran Slayer	Defeat 1,000 enemies	+5% damage
Zone Explorer	Explore 10 different zones	+1 sight distance
Rune Collector	Collect 50 runes	+5% crafting success
Gold Hoarder	Accumulate 50,000 gold (lifetime)	+5% gold find
Potion Master	Use 100 potions	+10% potion healing

Ranked Trophies (Season 1 only, by leaderboard position):

Trophy	Requirement	Bonus
Infernal Champion	Top 1% Season 1	+10% fire resistance, +5% all damage
Flame Warden	Top 10% Season 1	+5% fire resistance, +3% damage
Ember Guard	Top 25% Season 1	+3% fire resistance

Season-Exclusive Trophies (Season 1 ONLY):

Trophy	Requirement	Bonus
Demon Bane	Kill 500 demon-type enemies during S1	+8% damage vs demons
Portal Closer	Clear all Infernal portal zones during S1	+1 movement speed
Infernal Survivor	Reach level 50 during S1	Cosmetic: flame aura effect

Season 2: Frozen Wastes (Ice Theme)

Color Palette: Ice blue, white, silver frost Narrative: An unnatural winter grips the land. Frost giants descend from the mountains, freezing entire zones. Ancient ice magic awakens buried threats.

Season 2 Trophies

Ranked Trophies (Season 2 only):

Trophy	Requirement	Bonus
Frostborne Champion	Top 1% Season 2	+10% ice resistance, +5% max HP
Winter Sentinel	Top 10% Season 2	+5% ice resistance, +3% max HP
Frost Guard	Top 25% Season 2	+3% ice resistance

Season-Exclusive Trophies (Season 2 ONLY):

Trophy	Requirement	Bonus
Giant Slayer	Kill 500 frost giant-type enemies during S2	+8% damage vs giants
Thaw Bringer	Clear all Frozen Waste zones during S2	+1 attack range
Winter Conqueror	Reach level 50 during S2	Cosmetic: frost crystal aura

Season 3: Shadow Eclipse (Darkness Theme)

Color Palette: Deep purple, black, shadow violet Narrative: An eclipse plunges the world into permanent night. Shadow creatures emerge, visibility drops, and the undead grow far more powerful. This is the hardest season.

Season 3 Trophies

Ranked Trophies (Season 3 only):

Trophy	Requirement	Bonus
Eclipse Sovereign	Top 1% Season 3	+10% shadow resistance, +5% crit chance
Void Walker	Top 10% Season 3	+5% shadow resistance, +3% crit chance
Shadow Guard	Top 25% Season 3	+3% shadow resistance

Season-Exclusive Trophies (Season 3 ONLY):

Trophy	Requirement	Bonus
Undead Purger	Kill 500 undead-type enemies during S3	+8% damage vs undead
Light Bringer	Clear all Shadow Eclipse zones during S3	+2 sight distance
Eclipse Survivor	Reach level 50 during S3	Cosmetic: shadow tendril aura

Trophy Accumulation Example

A veteran player entering Season 3 who competed in Seasons 1 and 2 could have:

From Season 1: Demon Bane (+8% vs demons) + Infernal Champion (+10% fire res, +5% dmg) + First Blood (+2% dmg)
From Season 2: Giant Slayer (+8% vs giants) + Winter Sentinel (+5% ice res, +3% HP)
Landmark (any season): Gold Hoarder (+5% gold) + Potion Master (+10% potion healing)

This gives the veteran meaningful collection and Standard-mode advantages. On a Current Season character, the same trophies remain visible but mechanically inactive, so the veteran and a new player compete under the same power rules.

Player Inspection (Power Display)

Players should easily see how powerful other players are to incentivize growth.

Current Inspection Data

Character name, level, class
Equipment (10 slots: name, rarity, item level)
Currencies (gold, soul shards, blood emeralds)
Quest counts (active, completed)
Location (zone)

Missing (Needs Implementation)

Gear Score — Average item level across equipped slots (field exists in FullInspectionData but never populated)
Power Level — Separate Standard and Current Season metrics under the locked power contract
Combat Stats — Damage, defense, HP, crit chance (from CharacterStats)
Lifetime Stats — Total enemies killed, total gold earned, playtime
Season Badge — Which season the character belongs to
Paragon Path — Active path and level (50+)
Trophy Count — Number of trophies earned

Gear Score Formula

GearScore = average(itemLevel for each of 10 equipped slots)

Empty slots count as 0
Displayed as: "Gear Score: 45" alongside level

Power Level Formulas

StandardPowerLevel = (Level * 10) + (GearScore * 5) + (TrophyBonusCount * 2)

CurrentSeasonPowerLevel = (Level * 10) + (GearScore * 5) + SeasonEarnedBuildScore

Standard Power Level is a broad character comparison and may include inherited power.
Current Season Power Level includes only power earned by that character in the active season.
SeasonEarnedBuildScore MUST NOT read trophies, Mastery, entitlements, purchased power, or another character's state.
Both values may appear on inspection, but only Current Season Power Level may drive seasonal rewards.

Leaderboard System

Architecture

Leaderboards are per-season with an all-time component.

Leaderboard Categories

Category	Metric	Update Trigger	Season-Scoped
Level	Character level	On level up	Yes (current season) + All-time
Gear Score	Average equipped item level	On equip/unequip	Yes + All-time
Power Level	Combined score	On any stat change	Yes + All-time
Enemies Defeated	Lifetime kill count	On enemy kill	Yes + All-time
Quests Completed	Quest completion count	On quest complete	Yes + All-time
Gold Earned	Lifetime gold	On gold gain	Yes + All-time

Season Leaderboards

Reset each season (new characters start at 0)
Frozen at season end for hall of fame (NOT BUILT, see End-of-Season Flow)
Drive season reward distribution (top 1%/10%/25%) (NOT BUILT, see End-of-Season Flow)
Exclude paid and inherited modifiers under the Locked Competitive Power Contract
Award at most one placement reward per account per category

All-Time Leaderboards

Persist across all seasons
Track cumulative metrics from STANDARD_SEASON characters
Separate ranking from seasonal competition
Act as record books, not reward-bearing fair competition, unless the metric is normalized

Display

"leaderboard" command shows top 10 + player rank
Shows: Rank, Name, Level, Power Level, Season Badge (the Season Badge is NOT BUILT: the readout is filtered to the caller's season and never names it; the only badge spoken is the subscriber's Founder's Mark)
Options to filter by: current season, all-time, friends-only

Cross-Game Extension

All games can extend the base leaderboard by implementing:

A leaderboard entry model (extends base)
A leaderboard service (extends base)
A handler for the LEADERBOARD action
Game-specific metrics

Existing implementations: Mystery (per-scenario scores), Flip Match (dedicated table), Ryan3000 (simple scores).

Key Files

File	Purpose
model/user/SeasonTypes.java	Enum: EARLY_ACCESS, STANDARD_SEASON, CURRENT_SEASON
model/darknessfalls/DarknessFallsCharacter.java	characterSeason field
model/darknessfalls/DarknessFallsAccount.java	seasonalStashTabs map
model/user/SeasonalCurrencyCounts.java	Per-season currency storage
utils/darknessfalls/gear/inventory/.java	Season-aware stash operations
utils/darknessfalls/currency/.java	Season-aware currency getter
engines/handlers/darknessfalls/trading/.java	Season-filtered auction house
service/darknessfalls/.java	Season-tagged pending currency
utils/darknessfalls/character/.java	Star map (character-level)
engines/entry/shared/darknessfalls/.java	Trophy room activation