Player Statistics & Achievements · Game Documentation

Purpose & Player Value

[CONFIRMED] Lambeer records persistent statistics for every player. These statistics provide long-term evidence of player activity and are evaluated to unlock achievements.

The feature gives players durable goals beyond a single life while keeping achievement progress grounded in actions that already occur in combat, survival, and traversal.

Scope

Maintain one persistent statistics record for each player identity.
Track the five confirmed statistics listed in the statistic catalog.
Evaluate affected achievements after an authoritative statistic update.
Persist unlocked achievement IDs so the same achievement is not unlocked twice.
Restore statistics and unlock state after relogging and server restart.

Out of Scope

Leaderboards, rankings, competitive seasons, and public profile visibility.
Achievement names, descriptions, icons, rewards, thresholds, and platform-service integration until approved separately.
Using these totals as skill XP or character-level progression; learn-by-doing skills remain governed by FEAT-CRAFTING-PROGRESSION.

Terminology

Persistent statistic: A cumulative value saved against a stable player identity.
Current life: The interval beginning when the character becomes alive and ending when death is authoritatively confirmed.
Achievement definition: A data-driven rule that references a statistic, comparison, threshold, and stable achievement ID.
Achievement unlock: A permanent recorded state indicating that a player satisfied an achievement definition.

Statistic Catalog

Stable key	Display meaning	Authoritative update	Persistence rule
`ZombieKills`	Number of zombies killed	Increment when a zombie death awards this player kill credit.	Cumulative; death does not reset it.
`Deaths`	Number of player deaths	Increment exactly once when this player's death is confirmed.	Cumulative; the increment survives respawn.
`TimeAlive`	Total time alive	Accumulate only while the authoritative game state considers the player alive.	Cumulative across lives.
`DamageDealt`	Total damage dealt	Add accepted post-validation damage attributed to this player.	Cumulative; rejected or client-only damage is ignored.
`DistanceTravelled`	Total distance moved	Add validated movement distance attributed to the player; discontinuities such as spawn or teleport must not create distance.	Cumulative across lives.

The keys above are documentation-level stable identifiers. Runtime type names, storage schema, and Unreal asset/class names are not yet verified and must not be inferred from this specification.

Functional Behavior

An authoritative gameplay event identifies the affected player and statistic delta.
The server validates the event, applies the delta once, and marks the player record dirty for persistence.
The achievement evaluator checks only definitions that depend on the changed statistic.
When a threshold is satisfied and the stable achievement ID is not already unlocked, the unlock is recorded before presentation is requested.
The owning player may receive the updated total and unlock notification; the authoritative persisted record remains the source used for future evaluation.

Authority rule: clients may display progress, but they must not directly submit trusted totals or grant achievement unlocks.

States & Flows

Gameplay event → server validation → statistic update → achievement evaluation → persist total/unlock → notify owning player

On login, the game loads the player's persisted statistics and unlocked achievement IDs before accepting progress that depends on those values. On death, only the current-life interval closes; cumulative totals remain intact.

Rules & Edge Cases

A single authoritative event may update a given statistic only once, even if the event is retried during persistence or reconnect handling.
Achievement unlock is idempotent by stable achievement ID.
Statistics never decrease through normal gameplay. Administrative correction or data migration policy is not defined by this feature.
Deaths caused by environment, zombies, players, or self-inflicted damage all count as deaths unless a later rule explicitly excludes a cause.
Movement produced by spawn placement, teleportation, reconciliation snap, or other discontinuity is excluded from travelled distance.
Changing achievement thresholds later must not revoke already unlocked achievements unless a separate migration decision explicitly requires it.

Dependencies & Relationships

FEAT-PLAYER-CHARACTER — stable player identity, alive/dead state, and movement source.
FEAT-COMBAT — authoritative damage and kill attribution events.
FEAT-SURVIVAL — death state and alive-time boundaries.
FEAT-CRAFTING-PROGRESSION — adjacent progression system; statistics do not replace its skill or boss progression rules.
TECH-NETWORK-ARCH — player persistence and server authority.

Runtime source of truth: TBD. The storage schema, owning service/system, data migration strategy, and achievement-definition asset format require technical design.

Acceptance Criteria

ID	Scenario	Expected outcome
`AC-STAT-001`	A player receives valid zombie kill credit.	`ZombieKills` increases exactly once and remains after relogging.
`AC-STAT-002`	A living player dies and later respawns.	`Deaths` increases exactly once; cumulative statistics are not reset.
`AC-STAT-003`	A player remains alive, then dies.	The completed alive interval is included in cumulative `TimeAlive` and is restored after relogging.
`AC-STAT-004`	Authoritative damage is accepted or rejected.	Only accepted attributed damage contributes to `DamageDealt`.
`AC-STAT-005`	A player moves normally and is then teleported.	Normal movement contributes to `DistanceTravelled`; the teleport discontinuity does not.
`AC-STAT-006`	A statistic crosses an achievement threshold.	The achievement unlock is persisted once and remains unlocked after death, relog, and server restart.
`AC-STAT-007`	A client attempts to report an arbitrary total or unlock.	The untrusted value is rejected and does not alter authoritative progress.

Open Questions

TBD-7C5F9A21 — [TBD] Are statistics and achievements scoped per account globally, per server, or per character?
TBD-E2F4910C — [TBD] What achievement catalog, thresholds, rewards, presentation, and external platform integration will ship?
TBD-94B6D3E8 — [TBD] Finalize attribution rules: kill assists/final blow, valid damage target types, connected versus offline alive time, and movement units/filters.