Character Stats And Equipment Modifiers

What This System Is

The character-stat pipeline resolves progression and equipped-item contributions into one authoritative, explainable stat snapshot. The shared domain owns stable stat identifiers, saturating aggregation, deterministic source ordering, and runtime clamps. The game server owns which item sources are equipped and clients only render the replicated result.

How Authors Use It

Equipment stats are authored in assets/gameplay/game_data/items.json under equipment:

weapon.damage and weapon.delay_ms describe the equipped weapon;
defense and magic_defense provide armor values;
stat_modifiers provide signed flat contributions such as attack_power, critical_hit, or maximum resources.

Explicit defense or magic_defense modifiers take precedence over the matching legacy direct field for that item, preventing older catalog rows from being counted twice. Other modifiers add together across equipped items.

Rules And Invariants

Resolution starts with the authored level progression source and then applies equipment sources in stable source-id order. Health, mana, and stamina maxima are clamped to at least one. Combat-facing values are clamped to zero or greater. Current resource percentages are preserved when login, level changes, or equipment changes alter a maximum.

The server recalculates stats during session activation, authoritative equip/unequip commits, experience rewards, and trigger-driven level/stat updates. Equipment changes publish equipment, player-stat, and player-combat snapshots together.

Authoritative attacks add resolved Attack Power and weapon damage before critical and target mitigation. Critical Hit is interpreted as percentage points and uses the request id for deterministic rolls; critical attacks deal 150% damage. Physical contact damage uses Defense while magic, fire, ice, lightning, and arcane contact damage use Magic Defense.

Replicated player-stat snapshots contain final values plus progression/equipment source breakdowns. The character panel displays core totals and names the first equipped sources. Source categories for passive abilities and status effects are part of the shared contract for later expansion, while current temporary combat modifiers remain in the status-effect pipeline.

Passive stat sources and conditional traits are described in Passive Traits And Procs.

Validation And Debugging

Unknown stat identifiers fail catalog parsing. Existing game-data validation rejects zero-valued modifiers and checks equipment stat budgets. Authority ignores missing catalog items rather than accepting client-supplied values.

When totals look wrong, inspect the replicated resolved_stats and stat_sources arrays first. Then verify the authoritative equipment snapshot, item catalog row, and whether a defense value is authored through the direct field or explicit modifier.

Examples

A spear with five Attack Power and five weapon damage contributes both values to accepted Dragoon attacks. Equipping an item with ten maximum health increases the resolved maximum and preserves the player's previous health percentage rather than granting or removing an arbitrary flat amount.