Skip to content
Programming Bible

14 — Monetary platform (Credits, BTUCOIN, LUMENAR)

Intent

Section titled “Intent”

Ship the three-currency economy as a separate, reusable monetary platform plugin — not a Terra Firma–only code dump inside combat/inventory. demo5.8 / TFA consumes it through a thin game-side adapter; another Unreal project can enable the same plugin with its own adapter.

Anti-cheat / TrustSignals ship in the same portable plugin (public module). Lyra / TFACore enable MonetaryPlatform and call that API without TFAEconomy. Cheap combat hit-auth stays in TFACombat spine / TFAWeapons (Melee publishes via Core messages — Plugify).

Anchors

Section titled “Anchors”
  • FS-PRD-007, FS §16b FS-ECO-* (including FS-ECO-012 Founding Clubs / CF cosmetics)
  • FS anti-cheat notes, FS-ARCH-012 / FS-ARCH-013, FS-TRS-* (Trust UI stays game-side)
  • GDD: Marketplace Economy — Credits & BTUCOIN & LUMENAR; Founding Clubs & CF Cosmetics — In-Game
  • FE Spec marketplace wallet
  • Architecture Map: logical TFAEconomy (in TFA this GFP hosts the platform money adapter; the platform itself is portable) · §7 CF entitlements

Product boundary

Section titled “Product boundary”
Layer Owns Portable?
Monetary platform plugin Ledgers, mint/spend authority, convert rules, config DAs, offline/online persistence hooks, Marketplace Wallet widgets (generic), AntiCheat / TrustSignals public API, economy/marketplace fraud, statistical signal ingest, case-log store hooks Yes — drop into another UE5 project
TFA adapter (game) Play-grant sources (missions, daily/weekly/hard), Character I title-bar chips, vendor vs marketplace isolation rules that cite TFA item IDs, GDD naming (BTUCOIN / LUMENAR / Credits) TFA-specific
Host (Lyra / other) EOS PUID / local save identity the ledgers key on; enables MonetaryPlatform so Core / Online can reach AntiCheat Project-specific
TFA Trust UI (game) Report sheet, Trust overlay, ghost spectate chrome (FS-TRS presentation) — submits into platform case/signal API; does not own case storage TFA-specific

Rules:

  • Gameplay GFPs (Combat, Weapons, Character I) never own mint math or ledger-fraud logic. They call platform interfaces / Gameplay Messages.
  • Gameplay GFPs never own the case/signal store. Combat may submit worker signals only; Game Thread hit-auth stays in Combat / Weapons (FS-ARCH-013).
  • Lyra / TFACore may depend on MonetaryPlatform and call UAntiCheatSubsystem (public). TFAEconomy is not required for anti-cheat access.
  • Do not put economy or anti-cheat in ADDON (FS-ARCH-011).

Plugin packaging (target)

Section titled “Plugin packaging (target)”

Suggested Unreal layout (names can be finalized at scaffold time; keep the split):

Plugins/
  MonetaryPlatform/          # or TFAMonetary — portable product
    MonetaryPlatform.uplugin
    Source/MonetaryPlatformRuntime/
      CreditWalletComponent
      CryptoLedger (BTUCOIN)
      LumenarLedger
      MonetarySubsystem
      IMonetaryHost (identity, realm, online gate)
    Source/MonetaryAntiCheatRuntime/   # public module — Lyra/TFACore may depend
      AntiCheatSubsystem               # UAntiCheatSubsystem (name lock at scaffold)
      TrustSignal ingest API
      EconomyFraudRules
      CaseStore hooks (feeds FS-TRS workflows)
    Content/
      DA_Monetary_CryptoConfig
      DT_Monetary_PlayGrants   # empty template; host fills
      DT_Monetary_CashPacks
      UI/W_Monetary_MarketplaceWallet
  GameFeatures/
    TFAEconomy/              # TFA-only GFP: enables platform + TFA money adapter
      binds play objectives → PlayGrants
      paints CREDITS · BTUCOIN on Character I (not LUMENAR)
      does NOT gate AntiCheat access

For a non-TFA project: enable MonetaryPlatform only, implement IMonetaryHost, fill grant/cash tables, skip TFAEconomy; still get ledgers + AntiCheat API.

Ownership (runtime)

Section titled “Ownership (runtime)”
Class / asset Lives in Job
UMonetarySubsystem Platform Server-authoritative entry for mint/spend/convert / entitlement upsert
UCreditWalletComponent Platform Soft play currency (Credits) — account / PUID shared across characters (FS-ECO-001)
UCryptoLedger Platform BTUCOIN; 51/49 mint split (FS-ECO-004)
ULumenarLedger Platform LUMENAR from BTUCOIN convert only; Marketplace spend
EntitlementFlags store Platform CF / Founding Club looks flags on EOS PUID (FS-ECO-012); not Combat power
DA_Monetary_CryptoConfig Platform Display names, floor (TBD-035), market feed, (R) convert (TBD-036), split locked; settlement (P=\max(\text{floor},\text{market}))
IMonetaryHost Host implements Player identity (EOS PUID / local), Solo vs Online realm, “can mint” gate
UAntiCheatSubsystem Platform (public AntiCheat module) Signal ingest, economy/marketplace fraud, case-log hooks; never on Game Thread hit path
Trust UI widgets / spectate chrome TFAOnline + TFAFrontend (FS-TRS) Player/staff surfaces; submit into platform API
TFA money adapter TFAEconomy GFP Maps FS-ECO play grants, I chips, marketplace routes only

Authority

Section titled “Authority”
  • Server-authoritative on Online; Solo local authority OK if host says so.
  • Never trust client balance packets.
  • Marketplace spend isolated from in-world vendors (FS-ECO marketplace locks).
  • Character I title bar: CREDITS · BTUCOIN only — LUMENAR is Marketplace Wallet only (GDD / FE lock).
  • Anti-cheat heuristics and case writes: worker / marshal path only (FS-ARCH-012). Never delay damage GEs (FS-ARCH-013).

Integration checklist (another project)

Section titled “Integration checklist (another project)”
  1. Add MonetaryPlatform plugin to .uproject (Runtime + AntiCheat modules).
  2. Implement IMonetaryHost (identity + realm + online).
  3. Author or fork DA_Monetary_CryptoConfig (rename tokens if needed; keep ledger split if using BTUCOIN rules).
  4. Fill play-grant / cash-pack tables or leave empty until live.
  5. Mount Marketplace Wallet UI; do not hardcode TFA Character I.
  6. Call subsystem RPCs from your rewards / store — do not fork ledger code into game modules.
  7. Call UAntiCheatSubsystem (or agreed public name) from host / online / combat workers for signals and fraud; do not route through a game-only money adapter.

Done

Section titled “Done”
  • Three-currency locks in FS/GDD: Credits (play), BTUCOIN (51/49 mint from play + fiat), LUMENAR (convert only; cash never grants LUMENAR)
  • Settlement (P=\max(\text{floor},\text{market})); play/cash mint (M=V/P); convert uses same (P) so LUMENAR stays flat for (V)
  • Floor / (V) / (R) TBDs listed (do not invent)
  • Doc lock: monetary stack is a separate portable platform (this chapter)
  • Doc lock: AntiCheat / TrustSignals is a public module inside MonetaryPlatform; Lyra/TFACore access without TFAEconomy

Have

Section titled “Have”
  • No MonetaryPlatform plugin / TFAEconomy GFP / ledgers / AntiCheat module in demo5.8 yet

Need

Section titled “Need”
  • Scaffold MonetaryPlatform (or equivalent) as its own .uplugin with Runtime + public AntiCheat modules + Content templates
  • TFA TFAEconomy GFP that only adapts money — enables platform, wires FS-ECO grants, I chips, marketplace
  • IMonetaryHost on Lyra/TFA player identity (EOS / Solo pools)
  • Server-authoritative mint/spend/convert; fail-closed ledgers
  • UAntiCheatSubsystem public API: signal ingest, economy fraud, case-store hooks for FS-TRS
  • Config + grant + cash-pack DAs (FS §20 crypto rows)
  • Marketplace Wallet UI in platform Content; TFA I title-bar chips stay in Character I / FE art pipeline
  • Register platform in .uproject early enough that TFACore / Online / Combat workers can submit signals without waiting on TFAEconomy
  • Register platform for any second consumer project

AC

Section titled “AC”
  • AC-ECO-001..003 (FS); Season Pass AC-ECO-004; CF / clubs AC-ECO-005
  • Portable smoke: second sample map/project enables plugin + host stub and can mint/spend Credits without TFA GFPs
  • Portable smoke: host can call AntiCheat signal ingest without enabling TFAEconomy