Economy

经济 API 允许你创建自定义货币（金币、宝石、经验值等），并自动为每位玩家在不同会话之间持久保存。

• 每种货币都按 每个玩家
• 余额会 自动持久保存 跨会话保存
• 余额可在创作者门户中查看/编辑（见 编辑/查看玩家数据)

经济 API 参考

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

注册一种货币（一次性）

在使用某个货币名称之前，先为它注册一个图标。

ao_before_scene_load :: proc() {
    // 从你的 /res 文件夹中选择一个图标
    coin_icon := get_asset(Texture_Asset, "ui/coin.png");

    Economy.register_currency("Coins", coin_icon);
    Economy.register_currency("XP", coin_icon); // 示例（理想情况下请使用不同的图标）
}

货币名称只是字符串。请选择一个一致的名称并坚持使用它（例如 "Coins" 与 "coins").

读取玩家余额

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

发放货币（奖励）

使用 deposit_currency 只要玩家获得货币时就调用。

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

消耗货币（商店/升级）

始终检查 can_withdraw_currency 在取款前先检查。存入和取出金额必须为非负数。

UPGRADE_COST :: 50;

try_buy_upgrade :: proc(player: Player) -> bool {
    if !Economy.can_withdraw_currency(player, "Coins", UPGRADE_COST) {
        Notifier.notify(player, "金币不足！");
        return false;
    }

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

    // 在这里授予升级……
    Notifier.notify(player, "升级已购买！");
    return true;
}

内置商店

一个商店包含分类，而每个分类包含商品。先注册其货币，再创建商店。请将其句柄保存在场景级字段或全局变量中，因为它们只在当前场景中有效。

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

    // 返回 false 会取消购买，并且不会向玩家收费。
    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",
        "增加 10 点最大生命值。",
        "ui/health_upgrade.png",
        "Coins",
        50,
        "",
        Item_Rarity.COMMON.(s64),
        ""
    );

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

购买处理器必须授予该商品并返回 true. 返回 false 会拒绝该购买。

在玩家 UI 代码中绘制商店。 Shop.draw 返回 true 只要商店保持打开：

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 可以为每个玩家更改商品的价格或按钮。 Shop.set_custom_display 可以替换商品卡片的绘制。两个回调都使用相同的显式 userdata 模式，与购买处理器相同。

重置玩家的经济数据

如果你需要清除某个玩家的所有经济余额（例如管理员重置按钮或游戏模式重置），你可以删除其经济存档数据：

reset_economy :: proc(player: Player) {
    Economy.delete_save_data(player);
    Notifier.notify(player, "你的经济数据已重置。\");
}

Economy.delete_save_data 具有破坏性。请谨慎使用，并考虑添加确认步骤/仅管理员访问。

经济系统 vs 存档

• 使用 经济系统 用于“货币”（金币、宝石、XP、票券），希望自动持久保存 + 门户可编辑。
• 使用 存档 用于其他一切（设置、任务状态、解锁列表、复杂进度结构）。参见 保存系统