Modules · Inventory

Inventory Module

Query player balances and item quantities in real time. Results are cached in Redis and delivered via async callback — no game thread blocking.

Get Currency Balance

Returns the current balance for a single currency. Cached 60 seconds in Redis.

GM_GetBalance

// Query a player's current currency balance
GM_GetBalance(
  game_id,
  R"({"currency_id": "gold", "player_id": "player_001"})",
  [](const char* result_json) {
    // result_json: {"currency_id":"gold","balance":1250.0}
  }
);

Get Item Inventory

Returns all items and quantities for a player. Use to gate offers on owned items.

GM_GetInventory

// Query all items owned by a player
GM_GetInventory(
  game_id,
  R"({"player_id": "player_001"})",
  [](const char* result_json) {
    // result_json: {"items":[{"item_id":"shield_lvl2","quantity":3}, ...]}
  }
);

Track IAP Purchase

Call after every verified IAP. The SDK maps the real-money price to your BCU rate and records an iap_purchase ledger entry. This drives the holdout ARPU comparison used for revenue share eligibility.

GM_TrackPurchase

// Track an IAP purchase (maps real money to BCU rate)
GM_TrackPurchase(
  game_id,
  R"({
    "player_id":    "player_001",
    "product_id":   "com.studio.gold_pack_500",
    "currency_code":"USD",
    "price":        4.99,
    "item_id":      "gold_pack_500",
    "quantity":     1
  })"
);

Redis Cache Keys

Key Pattern	TTL	Contents
balance:{game_id}:{player_id}:{currency}	60s	Currency balance cache
inventory:{game_id}:{player_id}	4h	Item quantity map (HSET)
player:features:{game_id}:{player_id}	4h	ML feature store (spend_score, segment, etc.)

BCU — Base Currency Unit

BCU is your game's normalised currency unit. Set the conversion rate in Dashboard → Games → Currency Mapping. For example, if 100 Gold = $0.01 USD, your BCU rate is 0.0001. The AI uses BCU to compare economy health across all games in the fleet.