Economy

Economy APIs let you create custom currencies (coins, gems, XP, etc) and automatically persist them for each player across sessions.

• Each currency is stored per-player

• Balances are automatically persisted across sessions

• Balances can be viewed/edited in the creator portal (see Editing/Viewing Player Data)

Economy API reference

Economy :: struct {
    register_currency     :: proc(currency: string, icon: Texture_Asset);
    deposit_currency      :: proc(player: Player, currency: string, amount: s64);
    get_balance           :: proc(player: Player, currency: string) -> s64;
    can_withdraw_currency :: proc(player: Player, currency: string, amount: s64) -> bool;
    withdraw_currency     :: proc(player: Player, currency: string, amount: s64);
    delete_save_data      :: proc(player: Player);
}

Registering a currency (one time)

Before you use a currency name, register it with an icon.

// Pick an icon from your /res folder
coin_icon := get_asset(Texture_Asset, "ui/coin.png");

Economy.register_currency("Coins", coin_icon);
Economy.register_currency("XP", coin_icon); // example (use a different icon ideally)

Currency names are just strings. Pick a consistent name and stick to it (for example "Coins" vs "coins").

Reading a player's balance

coins := Economy.get_balance(player, "Coins");

Giving currency (rewards)

Use deposit_currency whenever a player earns currency.

on_enemy_killed :: proc(player: Player) {
    Economy.deposit_currency(player, "Coins", 10);
    Economy.deposit_currency(player, "XP", 3);
}

Spending currency (shops/upgrades)

Always check can_withdraw_currency before withdrawing.

UPGRADE_COST :: 50;

try_buy_upgrade :: proc(player: Player) -> bool {
    if !Economy.can_withdraw_currency(player, "Coins", UPGRADE_COST) {
        Notifier.notify(player, "Not enough coins!");
        return false;
    }

    Economy.withdraw_currency(player, "Coins", UPGRADE_COST);

    // Grant the upgrade here...
    Notifier.notify(player, "Upgrade purchased!");
    return true;
}

Resetting a player's economy data

If you need to wipe all economy balances for a player (for example, an admin reset button or a game mode reset), you can delete their economy save data:

reset_economy :: proc(player: Player) {
    Economy.delete_save_data(player);
    Notifier.notify(player, "Your economy data was reset.");
}

Economy.delete_save_data is destructive. Use it sparingly, and consider adding confirmations/admin-only access.

Economy vs Save

• Use Economy for "currencies" (coins, gems, XP, tickets) where you want auto-persistence + portal editing.

• Use Save for everything else (settings, quest state, unlock lists, complex progress structures). See Save System