Skip to content

🔌 Currency System — Integration Surfaces

Namespace: RevGaming.RevFramework.Currency

This page explains where new gameplay logic should integrate with the RevFramework Currency system.

Currency is designed as a composable ledger pipeline.
You extend behaviour primarily through service composition (decorators), not by replacing core implementations.

Choosing the correct surface ensures systems remain predictable, maintainable, and compatible with the rest of the framework.

🧠 Extension Surfaces Overview

Goal Extension Point Example
Modify balances ICurrencyService (resolved/composed instance) gameplay spending
Add constraints CurrencyPolicy min/max caps
Add cross-cutting behaviour Decorators via CurrencyFactories audit, authority
Reserve funds ICurrencyEscrow crafting reservations
Prevent duplicate calls Idempotency decorator network retry safety
Observe balance changes OnWalletChanged / batch events UI updates
Aggregate operations CurrencyBatching shop transactions
Convert currencies ICurrencyExchange gold → gems
Persist balances ICurrencyPersistence save systems
Display currency UI components (CurrencyBar, etc.) HUD

⚙️ Supported Extension Surfaces (✅)

Use these for normal integration:

  • ICurrencyService (via resolved/composed instance — do not replace unless necessary)
  • CurrencyPolicy
  • ICurrencyEscrow
  • ICurrencyExchange
  • ICurrencyPersistence
  • CurrencyFactories (composition entry points)
  • OnWalletChanged / batch events (observation)

⚠️ Advanced / Composition Surfaces

Use carefully:

  • Custom ICurrencyService implementations
  • Custom decorator chains via CurrencyFactories
  • Custom ITransferPolicyProvider

These require understanding of: - composition order - capability model - system guarantees

❌ Internal (Do Not Use)

  • RevGaming.RevFramework.Currency.Internal.*
  • Decorator classes directly
  • Resolver override internals

If you think you need these:

→ You are likely solving the problem at the wrong layer. → Re-check the supported extension surfaces first.

⚙️ Example Decision Flow

Shop purchase logic

Use: 

ICurrencyService
Gameplay systems coordinate currency — Currency itself does not contain shop logic.

Wallet caps or limits

Use: 

CurrencyPolicy
Policies define rules, not behaviour.

Server authority

Use: 

CurrencyFactories.WithAuthority(...)
Authority controls who, not how.

Temporary reservations

Use: 

ICurrencyEscrow
Escrow must be explicitly composed into the service stack.

Prevent duplicate requests

Use: 

CurrencyFactories.WithIdempotency(...)

Currency conversion

Use: 

ICurrencyExchange

Save / load

Use: 

ICurrencyPersistence
(or integration helpers like CurrencyJsonSave)

UI updates

Observe: 

CurrencyDelta
ICurrencyService.OnWalletChanged
UI should observe events, not poll.

🧩 Decorators vs Core Service

The core service owns ledger truth.
Decorators add behaviour around that truth.

Behaviour Implementation
Caps WithCaps
Audit logs WithAudit
Authority checks WithAuthority
Escrow support WithEscrow
Require escrow enforcement WithRequireEscrow
Retry safety WithIdempotency
Batch events WithBatchEvents

💥 Transactions vs Currency

Currency handles ledger mutations, not gameplay systems.

Behaviour Correct Surface
Shop purchase Economy system
Crafting cost Economy system
Quest reward Economy system
Direct wallet change Currency

⚠️ Common Mistakes

Avoid:

  • Mutating wallet state outside ICurrencyService
  • Emitting fake CurrencyDelta events
  • Implementing gameplay logic inside decorators
  • Using UI to change balances
  • Assuming batching changes mutation semantics
  • Assuming escrow is automatically present

🧠 Architecture Summary

Currency Intent
      ↓
Argument Validation
      ↓
Policy / Cap Rules
      ↓
Authority Checks
      ↓
Ledger Mutation
      ↓
Events / Audit / Batch

Decorators attach to these stages.

  • Mental Model
  • Public API
  • System Guarantees Matrix
  • FAQ