stats-module

What problem does it solve?

Managing player and game metrics across sessions can be error-prone and inconsistent when you need caps, source tracking, event notifications, and persistent storage. This Skill describes a unified StatsModule that centralizes registration, clamping, consumption checks, batched persistence, and change broadcasting so gameplay systems can read and modify stats safely and predictably.

Core Features & Use Cases

• Centralized registration and lookup of stat definitions with initial values and definition-level caps.
• Deterministic operations: set, add, consume (with failure event), and convenience queries such as HasEnough and IsAtCap.
• Cap management with automatic clamping, reset semantics (to initial values or zero), and bulk reset operations.
• Event publishing for StatChanged, StatReset, StatConsumeFailed, and StatCapChanged to drive UI and achievement systems.
• Batched tick-based persistence for performance with immediate saves on cap and reset changes, plus test helpers and a mock factory for unit tests.
• Typical usage: bootstrap registration of StatsDefinition assets, runtime updates from gameplay systems, and subscription from UI/analytics for reactive updates.

Quick Start

Register your StatsDefinition assets during bootstrap and use the IStatsService RegisterStat, Add, Set, Consume, and SetCap methods to track, cap, and persist player metrics.