购买/产品 API

玩家可以在你的游戏中购买商品（游戏通行证 + 消耗品）以获取 Sparks。购买发生时，All Out 会调用你的 购买处理器 ，这样你就可以授予该物品或功能。

有关创建商品和查看分析数据，请参阅 游戏内产品.

商品类型（快速概览）

• 游戏通行证：一次性、永久解锁（管理员通行证、永久能力、房屋所有权）

• 消耗品：可多次购买（药水、临时增益、一次性金币包）

商品类型在创建者门户中配置。请参阅 游戏内产品.

购买 API 参考

Product :: struct {
    id: string;
    name: string;
    description: string;
    price: s64;
    consumable: bool;
    icon: Texture_Asset;
}

Purchasing :: struct {
    prompt_purchase :: proc(player: Player, id: string);
    owns_product    :: proc(player: Player, id: string) -> bool;
    get_product     :: proc(id: string) -> Product;
}

发起购买提示

要开始购买流程，请调用 Purchasing.prompt_purchase 并传入商品 ID。

BUY_DOUBLE_JUMP_ID :: "prod_double_jump";

try_prompt_double_jump :: proc(player: Player) {
    Purchasing.prompt_purchase(player, BUY_DOUBLE_JUMP_ID);
}

商品 ID 显示在创建者门户的变现/商品页面中（你可以点击复制）。请参阅 游戏内产品.

检查玩家是否拥有某个商品（游戏通行证）

对于游戏通行证，你可以通过检查所有权来限制游戏玩法功能。

ADMIN_PASS_ID :: "prod_admin";

is_admin :: proc(player: Player) -> bool {
    return Purchasing.owns_product(player, ADMIN_PASS_ID);
}

消耗品可以多次购买，owns_product 不应用于授予它们。消耗品通常在你的购买处理器中发放（金币、物品、增益等）。

读取商品信息（名称/价格/图标）

如果你想显示“购买”界面或记录商品信息，可通过 ID 获取商品定义：

product := Purchasing.get_product("prod_double_jump");
log_info("商品 % 需要 % Sparks", {product.name, product.price});

购买处理器（授予）

当玩家在你的游戏中购买商品时，All Out 会调用：

ao_purchase_handler :: proc(player: Player, id: string) -> bool

你应该：

• 根据商品 ID 进行切换

• 授予该物品/功能

• 返回 true 如果授予成功

• 返回 false 如果授予失败（背包已满、缺少前置条件等）

COIN_PACK_ID :: "prod_coin_pack_small";
DOUBLE_JUMP_ID :: "prod_double_jump";

ao_purchase_handler :: proc(player: Player, id: string) -> bool {
    switch id {
        case COIN_PACK_ID: {
            // 示例：授予金币（消耗品）
            Economy.deposit_currency(player, "Coins", 500);
            Notifier.notify(player, "谢谢！+500 金币");
            return true;
        }
        case DOUBLE_JUMP_ID: {
            // 示例：游戏通行证解锁（永久）
            // 通常你只需要在其他地方通过 owns_product() 检查来启用它。
            // 仍然返回 true，这样该购买会被视为已授予。
            Notifier.notify(player, "双重跳跃已解锁！");
            return true;
        }
    }

    // 未知 ID
    return false;
}

授予失败与重试

如果你的购买处理器返回 false，该购买会被标记为 授予失败.

• 授予失败会显示在创建者门户中

• 在玩家加入时会自动重试，直到成功

• 你可以在玩家数据 UI 中将某笔购买标记为“未授予”，以手动重新运行购买处理器

请参阅：

• 游戏内产品 （“购买处理器 / 授予失败”）

• 编辑/查看玩家数据 （“购买”部分）

跨游戏（大厅 + 小游戏）

如果你使用游戏父子关系，购买可以在你的各个游戏之间共享。请参阅 跨游戏产品/数据.