punkfuncgames/wallet-module

WalletModule Reference

Package: com.punkfuncgames.wallet | Define: PUNKFUNC_WALLET Location: Packages/com.punkfuncgames.wallet/Runtime/PunkFuncGames.Wallet/ Namespace: PunkFuncGames.Wallet

IWalletService

Registration/Lifecycle:

• RegisterCurrency(CurrencyDefinition, BigDouble initialAmount = default) — registers + applies pending save data
• RegisterCurrencies(IEnumerable<CurrencyDefinition>) — batch register
• UnregisterCurrency(CurrencyDefinition) — disposes container, removes lookup
• UniTask InitializeAsync(CancellationToken ct) — loads save data into pending buffer
• bool IsInitialized, int RegisteredCurrencyCount

Currency Operations:

• Add(CurrencyDefinition/string, BigDouble amount, CurrencyChangeSource source) — publishes CurrencyChangedEvent if amount changed; string overload silently no-ops on unknown ID
• bool Consume(CurrencyDefinition/string, BigDouble amount, CurrencyChangeSource source, string context) — returns false + publishes CurrencyInsufficientFundsEvent on failure; string overload returns false on unknown ID
• bool TryConsumeAll(IEnumerable<(CurrencyDefinition, BigDouble)>, string context) — atomic: verifies all first, then consumes all; materializes enumerable to prevent double-enumeration
• Set(CurrencyDefinition/string, BigDouble amount, CurrencyChangeSource source) — publishes event only if value changed

Queries:

• BigDouble GetAmount(CurrencyDefinition/string) — returns BigDouble.Zero for null/unregistered
• CurrencyContainer GetContainer(CurrencyDefinition/string) — returns null for unregistered
• CurrencyDefinition GetCurrencyDef(string) — returns null for null/empty/unregistered
• bool HasEnough(CurrencyDefinition/string, BigDouble amount)
• IEnumerable<CurrencyDefinition> GetAllCurrencies()
• IEnumerable<CurrencyContainer> GetAllContainers()

Cap Management:

• SetCap(CurrencyDefinition, BigDouble newCap) — saves immediately; publishes CurrencyCapChangedEvent; also publishes CurrencyChangedEvent if amount was clamped down
• RemoveCap(CurrencyDefinition) — saves immediately; publishes CurrencyCapChangedEvent

Reset:

• ResetCurrency(CurrencyDefinition) — publishes CurrencyChangedEvent (source=Prestige), saves immediately
• ResetAllCurrencies() — iterates all, calls ResetCurrency per currency (publishes individual events)

Error Behavior:

• Add/Consume/Set/SetCap/RemoveCap/ResetCurrency with null definition → ArgumentNullException
• Add/Consume/Set/SetCap/RemoveCap/ResetCurrency with unregistered definition → InvalidOperationException
• String-based overloads → return default/false silently for unknown IDs (no exception)

WalletService Implementation

sealed class WalletService : IWalletService, IAsyncStartable, ITickable, IDisposable

Constructor dependencies:

• ILogService (nullable — used for warnings/errors)
• ISaveService (required — ArgumentNullException)
• IPublisher<CurrencyChangedEvent> (required)
• IPublisher<CurrencyCapChangedEvent> (required)
• IPublisher<CurrencyInsufficientFundsEvent> (required)

Persistence strategy:

• Save key: "WalletData", version 1
• Batched saves: ITickable.Tick() checks _isDirty flag, saves after 5-second interval via Time.deltaTime
• Immediate saves: SetCap, RemoveCap, ResetCurrency, Dispose
• BigDouble amounts stored as strings in CurrencyEntryData for precision
• Lazy loading: InitializeAsync() loads all entries into _pendingLoadData dict; actual restore happens in RegisterCurrency() via ApplyLoadedData()
• Lifetime stats (earned/spent) are fully persisted and restored

Dual initialization:

• IAsyncStartable.StartAsync() (VContainer auto-calls)
• IWalletService.InitializeAsync() (manual calls)
• Both delegate to InitializeInternalAsync() which is idempotent

CurrencyContainer (Model)

Reactive runtime holder for a single currency. Bind UI directly to these properties.

• CurrencyDefinition Definition — identity reference
• ReadOnlyReactiveProperty<BigDouble> Amount — subscribe for UI updates
• ReadOnlyReactiveProperty<BigDouble> Cap — infinity when no cap
• BigDouble LifetimeEarned — cumulative earned, persisted
• BigDouble LifetimeSpent — cumulative spent, persisted

Operations:

• BigDouble Add(BigDouble, CurrencyChangeSource) — returns actual added after cap; no-ops for ≤0
• bool TryConsume(BigDouble, CurrencyChangeSource) — returns false if insufficient; no-ops for ≤0
• void Set(BigDouble, CurrencyChangeSource) — applies cap, tracks lifetime delta
• bool HasEnough(BigDouble)

Cap Management:

• bool SetCap(BigDouble) — returns true if amount was clamped down
• void RemoveCap() — sets cap to BigDouble.PositiveInfinity
• BigDouble GetPercentage() — 0-100 scale; returns 0 if no cap or zero cap
• BigDouble GetRemainingSpace() — PositiveInfinity if no cap
• bool IsAtCap() — false if cap is infinity

Lifetime Setters (for save restore):

• void SetLifetimeEarned(BigDouble) — direct setter for deserialization
• void SetLifetimeSpent(BigDouble) — direct setter for deserialization

Reset:

• void Reset() — zeroes amount, lifetimeEarned, lifetimeSpent

CurrencyDefinition (Config + Data Pattern)

Create via Assets menu: "GameTemplate/Currency Definition"

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

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

• string displayNameKey — unique ID and lookup key (auto-filled from asset name in OnValidate)
• Sprite icon, Color color
• bool hasCap, SerializableBigDouble initialCap (default 1e308)
• bool showInUI, int uiSortOrder

Serialization Models

WalletData:

• int Version (currently 1)
• List<CurrencyEntryData> Currencies

CurrencyEntryData:

• string CurrencyId — maps to DisplayNameKey
• string RawAmount, string RawCap — BigDouble as string
• string RawLifetimeEarned, string RawLifetimeSpent — BigDouble as string

Events

All events are readonly struct published via MessagePipe.

| Event | Fields | Published When | |-------|--------|----------------| | CurrencyChangedEvent | Currency, NewAmount, PreviousAmount, Delta (computed: New-Prev), Source | Any amount change (Add/Consume/Set/Reset/SetCap clamp) | | CurrencyCapChangedEvent | Currency, NewCap, PreviousCap | SetCap or RemoveCap (only if cap actually changed) | | CurrencyInsufficientFundsEvent | Currency, AttemptedAmount, AvailableAmount, Context | Consume fails (insufficient funds) |

CurrencyChangeSource enum (12 values): Unknown, Manual, Gameplay, Purchase, Reward, Prestige, Cheat, SaveLoad, Conversion, OfflineProgress, Production, Upgrade

Installer

WalletInstaller.Install(builder, options);
// Registers: WalletService as EntryPoint (IAsyncStartable + ITickable) with .As<IWalletService>()
// Brokers: CurrencyChangedEvent, CurrencyCapChangedEvent, CurrencyInsufficientFundsEvent

Dependencies

Required by WalletModule:

• ISaveService (SaveModule) — persistence
• ILogService (LogModule) — optional logging
• IPublisher<T> (MessagePipe) — event publishing
• BigDouble (Math) — large number arithmetic
• ReactiveProperty<T> (R3) — reactive UI binding

Modules that depend on WalletModule:

• IdleModule (ProductionService, UpgradeService, PrestigeService, OfflineProgressService)
• UnlockConditionModule (CurrencyThresholdConditionConfig)

Usage Pattern

public sealed class ShopController : IStartable, IDisposable
{
    private readonly IWalletService _wallet;
    private readonly CompositeDisposable _disposables = new();

    public ShopController(IWalletService wallet) => _wallet = wallet;

    public void Start()
    {
        CurrencyContainer gold = _wallet.GetContainer("Gold");
        gold.Amount
            .Subscribe(amount => UpdateGoldUI(amount))
            .AddTo(_disposables);
    }

    public bool TryBuyItem(BigDouble cost)
    {
        return _wallet.Consume("Gold", cost, CurrencyChangeSource.Purchase, "ShopItem");
    }

    public void Dispose() => _disposables.Dispose();
}

Test Coverage

Tests in Packages/com.punkfuncgames.wallet/Tests/EditMode/:

• CurrencyContainerTests — constructor, add, consume, set, cap, reset, lifetime, dispose
• WalletServiceTests — constructor guards, registration, CRUD, events, persistence, validation
• CurrencyEventsTests — struct field population, delta computation

Test helpers:

• MockFactory.CreateWalletService(currencies) — pre-configured mock with working Add/Consume/HasEnough
• MockFactory.CreateSaveService(data) — mock with working HasKey/Set
• TestFixtures.CreateCurrencyDefinition(displayNameKey, hasCap, initialCap) — SO factory with data struct initialized