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.

ao_before_scene_load :: proc() {
    // 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. Deposit and withdrawal amounts must be non-negative.

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;
}

Built-in shops

A shop contains categories, and each category contains products. Create the shop after registering its currencies. Keep its handles in scene-wide fields or globals because they are valid only for the current scene.

shop: u64;

grant_shop_product :: proc(
    player: Player,
    product: u64,
    userdata: Object
) -> bool {
    if Game_Product.get_id(product) == "health_upgrade" {
        player.max_health += 10;
        return true;
    }

    // Returning false cancels the purchase and does not charge the player.
    return false;
}

ao_before_scene_load :: proc() {
    coin_icon := get_asset(Texture_Asset, "ui/coin.png");
    Economy.register_currency("Coins", coin_icon);

    shop = Economy.create_shop("upgrade_shop");
    upgrades := Shop.add_category(shop, "Upgrades");

    Shop_Category.add_product(
        upgrades,
        "health_upgrade",
        "Health Upgrade",
        "Adds 10 maximum health.",
        "ui/health_upgrade.png",
        "Coins",
        50,
        "",
        Item_Rarity.COMMON.(s64),
        ""
    );

    Shop.set_purchase_handler(shop, null, grant_shop_product);
}

The purchase handler must grant the product and return true. Returning false rejects the purchase.

Draw the shop from player UI code. Shop.draw returns true while the shop remains open:

Player :: class : Player_Base {
    max_health: int = 100;
    shop_open: bool;

    ao_late_update :: method(dt: float) {
        if !is_local_or_server() return;

        if shop_open {
            shop_open = Shop.draw(shop, UI.get_safe_screen_rect());
        }
    }
}

Shop.set_purchase_modifier can change a product's price or button per player. Shop.set_custom_display can replace product-card drawing. Both callbacks use the same explicit userdata pattern as the purchase handler.

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