Combat Rewards And Progression Persistence
Combat rewards are the durable bridge between encounter resolution and player progression. Encounter code can decide that a mob was defeated and which rewards were rolled, but combat_authority owns making XP, gold, item drops, reward snapshots, and defeat side effects idempotent.
Purpose
Use this page when a combat reward appears in the scene but does not persist, when a player receives duplicate rewards, or when adding a new reward type to scene combat.
Reward Snapshot Construction
Scene combat builds reward data from authored encounter and loot definitions. Runtime combat authority scopes each reward to the character, session, request, and reward index so a replayed defeat cannot apply the same durable reward twice.
The client-facing reward snapshot is feedback. It does not prove persistence succeeded by itself. The durable application record is the source of truth for duplicate prevention.
Idempotent DB Application
Combat reward application ids are written through the durable reward path. If an application id already exists, the reward should be treated as already applied rather than granted again. This is especially important across retries, reconnects, transfer edges, and server restarts.
XP And Derived Stats
XP is applied through the player snapshot helpers. Total experience drives the derived player level using the shared progression formula. If the stored level lags behind total experience, the derived level should win in the emitted stats snapshot.
When adding new progression fields, update reward application, snapshot loading, bootstrap, and client reducers together.
Gold And Loot Drops
Gold is granted through the canonical currency path, not a separate legacy column. Item drops are inventory grants and must obey the same stack and idempotency rules as other inventory mutations.
Loot roll authoring belongs to the combat system. Durable item and currency mutation belongs to economy authority.
Death Hooks And Retry Handling
Combat defeat can trigger gameplay-state changes, persistence jobs, and client feedback packets. If the DB write fails after the scene has advanced, the retry system stores a combat-rewards job with enough character, realm, zone, reward, and idempotency context to retry safely.
Do not create retry payloads that lack the original authority idempotency envelope. Otherwise an operator requeue can become a duplicate grant.
Debugging
For duplicate rewards, inspect combat_reward_applications and the scoped reward id. For missing XP, inspect apply_character_experience_reward and the emitted stats snapshot. For missing drops, inspect inventory grant application records and stack cap failures. For stuck rewards, inspect persistence retry dead letters before manually editing player tables.