Skip to content

🪙 Currency — What This System Does (and Doesn’t Do)

This page explains what the Currency system is responsible for and what is intentionally left to you.

No code. No implementation details. Just boundaries.

✅ What Currency does

Currency is responsible for:

  • Tracking wallet balances per owner
  • Supporting multiple currency ids such as gold, gems, tickets, or project-specific values
  • Providing explicit balance operations:
  • set
  • credit
  • debit
  • transfer
  • Returning clear operation results for success and failure
  • Handling common failure cases such as:
  • invalid arguments
  • missing services
  • insufficient funds
  • overflow
  • cap violations
  • unauthorized mutations
  • Supporting currency policies such as min/max caps
  • Supporting audit records when the composed stack includes auditing
  • Supporting live wallet change events for UI and gameplay listeners
  • Supporting batch notifications for grouped operations when enabled
  • Supporting escrow / hard-hold flows when composed into the service stack
  • Supporting best-effort transaction helpers for multi-operation currency workflows
  • Providing helpers for:
  • affordability checks
  • deficits / shortfalls
  • currency formatting
  • exchange tables
  • awaiters
  • save/load snapshots

👉 In short:

Currency owns wallet state, wallet mutations, and the rules applied to those mutations

❌ What Currency does not do

Currency intentionally does not provide:

Full Game Economy Design

  • No pricing strategy
  • No reward balancing
  • No inflation control
  • No economy simulation
  • No shop design

Currency gives you the tools to move values safely.

👉 You decide what those values mean.

Persistence Ownership

Currency provides snapshot helpers and JSON convenience utilities, but it does not own your save system.

It does not decide:

  • when to save
  • where saves are stored
  • which owners should be saved
  • how cloud saves work
  • how save slots are managed
  • how deleted or missing owners are handled in your game

👉 Currency can capture and restore balances. You own the save/load pipeline.

Networking

Currency does not provide:

  • replication
  • prediction
  • rollback networking
  • server reconciliation
  • anti-cheat
  • authoritative multiplayer state sync

Currency supports authority seams and explicit operation results, but:

👉 You must implement multiplayer rules and network behaviour.

Authority Rules

Currency can be composed with an authority layer.

But it does not decide:

  • who owns a wallet
  • who is allowed to spend
  • who is allowed to grant currency
  • whether the server, host, or client is trusted
  • how multiplayer permissions work

👉 Currency asks the authority layer. You define the authority rules.

UI / UX

Currency includes convenience UI components and formatting helpers, but it does not own your final interface.

It does not decide:

  • HUD layout
  • shop screens
  • reward popups
  • animations
  • sound effects
  • player messaging
  • confirmation flows

👉 Currency exposes balances and events. You decide how players see them.

Guaranteed Atomicity for Every Workflow

Currency includes transaction helpers and escrow-first hold transactions, but not every multi-operation flow can be perfectly atomic in every composed stack.

Rollback can be affected by:

  • policy caps
  • authority checks
  • escrow requirements
  • idempotency
  • destroyed owners
  • custom service implementations

Some helpers are deliberately described as best-effort.

👉 For stronger guarantees, use escrow/hard-hold flows where appropriate.

Real-World Money / Payments

Currency is for in-game wallet values.

It does not provide:

  • payment processing
  • platform store integration
  • refunds through Steam / Apple / Google / console platforms
  • tax handling
  • real-money compliance
  • fraud detection

👉 Treat it as gameplay currency infrastructure, not a payment SDK.

🧠 Responsibility Split

Responsibility Owner
Wallet balances Currency
Credit / debit / transfer operations Currency
Operation result codes Currency
Cap policy enforcement Currency
Audit logs when enabled Currency
Escrow holds when enabled Currency
Batch wallet events when enabled Currency
Currency formatting helpers Currency
Save/load timing You
Save file format / cloud sync You
Multiplayer replication You
Authority rules You
Economy balancing You
Shop design You
UI / UX You
Real-money platform payments You / platform SDK

🧩 The Mental Shortcut

If you’re ever unsure:

  • “What is this owner’s balance?” → Currency
  • “Can this debit, credit, transfer, hold, or exchange happen?” → Currency
  • “Why did this mutation fail?” → Currency result codes
  • “Who is allowed to mutate this wallet?” → Your authority rules
  • “When and where is wallet data saved?” → You
  • “How is this shown to the player?” → You
  • “What should this item cost?” → You
  • “How does this work online?” → You

🎯 The Point

Currency is designed to be:

  • Explicit
  • Modular
  • Service-driven
  • Policy-aware
  • Auditable when needed
  • Safe to compose
  • Clear about failure states

It gives you:

👉 a reliable wallet and mutation layer

It does not try to be:

👉 your entire economy, save system, multiplayer layer, or shop UI

TL;DR

Currency owns wallet state and wallet mutations.
You own the economy, persistence, networking, authority rules, and presentation around it.