Modules · Economy

Economy Module

Track every currency earn and spend event. The AI uses this ledger to detect inflation, project player trajectories, and personalise offers with surgical precision.

Event Types

event_type	Direction	Description
currency_earn	+	Player receives currency (reward, login bonus, quest)
currency_spend	−	Player spends currency (purchase, upgrade, craft)
iap_purchase	+	Real-money IAP completed (maps to BCU rate)
currency_convert	⇄	Cross-currency conversion (soft → hard)
admin_adjust	±	Manual balance correction (support, refund)

Recording an Earn Event

Call after every currency grant — quests, level rewards, login bonuses.

economy_earn

// Record a currency earn event (level reward, login bonus, etc.)
GM_SendEconomyEvent(
  game_id,
  R"({
    "event_type":   "currency_earn",
    "currency_id":  "gold",
    "amount":       500,
    "source":       "level_complete",
    "player_id":    "player_001",
    "session_id":   "sess-uuid"
  })"
);

Recording a Spend Event

Amount should be negative for spends. The ledger is append-only — never update past records.

economy_spend

// Record a spend event (store purchase, upgrade, etc.)
GM_SendEconomyEvent(
  game_id,
  R"({
    "event_type":   "currency_spend",
    "currency_id":  "gold",
    "amount":       -200,
    "source":       "item_purchase",
    "item_id":      "shield_lvl2",
    "player_id":    "player_001",
    "session_id":   "sess-uuid"
  })"
);

Batching & Flush

The SDK buffers events locally and flushes automatically. Call flush manually on app pause.

flush

// Events are buffered locally and flushed automatically:
// • Every 50 events  OR
// • Every 30 seconds
// whichever comes first.
//
// Manual flush (e.g. on pause / background):
GM_FlushEvents();

⚠ Rules

• economy_ledger is append-only — never send corrective events that cancel previous ones. Use admin_adjust for corrections.
• Always include session_id — the AI uses it to compute session-level FSR.
• client_ts is set automatically by the SDK. Do not override it.
• Maximum batch size: 50 events. Offline buffer: 500 events (SQLite, FIFO eviction).