punkfuncgames/stats-module

StatsModule Reference

Package: com.punkfuncgames.stats | Define: PUNKFUNC_STATS Location: Packages/com.punkfuncgames.stats/Runtime/PunkFuncGames.Stats/ Namespace: PunkFuncGames.Stats

IStatsService : IService, IAsyncInitializable, IResettable

Registration:

• RegisterStat(StatsDefinition, BigDouble initialValue = default) — registers and applies saved data if available
• RegisterStats(IEnumerable<StatsDefinition>)
• UnregisterStat(StatsDefinition) — removes stat, caps, and initial values

Operations:

• Set(StatsDefinition/string, BigDouble value, StatChangeSource source = Manual) — sets value (capped)
• Add(StatsDefinition/string, BigDouble amount, StatChangeSource source = Gameplay) — adds amount (capped)
• bool Consume(StatsDefinition/string, BigDouble amount, StatChangeSource source = Gameplay, string context = "") — returns false + publishes StatConsumeFailedEvent if insufficient

Queries:

• BigDouble GetValue(StatsDefinition/string) — returns BigDouble.Zero for unregistered
• bool HasEnough(StatsDefinition/string, BigDouble amount) — convenience check
• StatsDefinition GetStatDef(string) — lookup by DisplayNameKey
• IEnumerable<StatsDefinition> GetAllStats()
• int RegisteredStatCount
• bool IsInitialized

Caps:

• SetCap(StatsDefinition/string, BigDouble cap) — enforces max value, clamps if current > cap
• RemoveCap(StatsDefinition/string) — sets cap to BigDouble.PositiveInfinity
• BigDouble GetCap(StatsDefinition/string) — returns BigDouble.PositiveInfinity if no cap
• bool IsAtCap(StatsDefinition/string) — true when value >= cap (and cap is finite)

Reset:

• ResetStat(StatsDefinition) — resets to initial value (from RegisterStat)
• ResetAllStats() — resets all to initial values
• ResetToZero(StatsDefinition) — explicit zero reset
• ResetAllToZero() — all stats to zero
• Reset() — delegates to ResetAllStats() (IResettable)

Events (MessagePipe)

All events are readonly struct in PunkFuncGames.GameTemplate.Runtime.StatsModule.Event:

| Event | Fields | Published When | |-------|--------|---------------| | StatChangedEvent | Stat, NewValue, PreviousValue, Delta, Source | Set/Add/Consume changes value | | StatResetEvent | Stat, PreviousValue, ResetToValue | ResetStat/ResetAll/ResetToZero | | StatConsumeFailedEvent | Stat, AttemptedAmount, AvailableAmount, Context | Consume fails (insufficient) | | StatCapChangedEvent | Stat, NewCap, PreviousCap | SetCap/RemoveCap |

StatChangeSource Enum

Unknown, Manual, Gameplay, Achievement, Prestige, Cheat, SaveLoad, OfflineProgress

StatsDefinition (Config + Data Pattern)

Same identity-object pattern as CurrencyDefinition.

StatsDefinition (ScriptableObject): Thin wrapper with public StatsDefinitionData data; Access fields via definition.data.fieldName.

StatsDefinitionData ([Serializable] public struct, camelCase fields):

• string displayNameKey — unique ID (auto-set from asset name)
• Sprite icon, Color color
• bool showInUI, int uiSortOrder
• bool hasCap, SerializableBigDouble initialCap — definition-level cap applied on RegisterStat

Implementation: StatsService

Implements: IStatsService, IAsyncStartable, ITickable, IDisposable

Dependencies: ISaveService, ILogService, IPublisher<StatChangedEvent>, IPublisher<StatResetEvent>, IPublisher<StatConsumeFailedEvent>, IPublisher<StatCapChangedEvent>

• Save key: "StatsData", version 1
• Lazy loading: stat data loaded when RegisterStat() is called
• Dictionary-based storage with lookup by DisplayNameKey
• Batched saves: Set/Add/Consume mark dirty; Tick() flushes every 5s
• Immediate saves: SetCap, RemoveCap, Reset*, Dispose

Installer

StatsInstaller.Install(builder, options);
// Registers: StatsService as IStatsService (EntryPoint for IAsyncStartable/ITickable)
// Brokers: StatChangedEvent, StatResetEvent, StatConsumeFailedEvent, StatCapChangedEvent

Usage Pattern

// Register stats (usually in a bootstrap phase or game scope)
_statsService.RegisterStat(totalKillsStat);
_statsService.RegisterStat(playTimeStat, new BigDouble(0));

// Track gameplay with source
_statsService.Add("TotalKills", BigDouble.One, StatChangeSource.Gameplay);
_statsService.Set("PlayTime", new BigDouble(totalSeconds), StatChangeSource.Manual);

// Spend-like operations
if (_statsService.Consume("Energy", new BigDouble(10), StatChangeSource.Gameplay, "spell_cast"))
{
    // success
}

// Query
BigDouble kills = _statsService.GetValue("TotalKills");
bool canCast = _statsService.HasEnough("Energy", new BigDouble(10));

// Caps
_statsService.SetCap(energyStat, new BigDouble(100));
bool full = _statsService.IsAtCap(energyStat);

// Subscribe to events
_subscriber.Subscribe(evt =>
{
    Debug.Log($"{evt.Stat.data.displayNameKey} changed by {evt.Delta} ({evt.Source})");
});

Test Helpers

• MockFactory.CreateStatsService(Dictionary<string, BigDouble>) — functional mock with Get/Set/Add/Consume/HasEnough
• TestFixtures.CreateStatsDefinition(displayNameKey, hasCap, initialCap, showInUI, sortOrder) — creates ScriptableObject with data struct initialized