物品栏

概述

All Out 提供了一个玩家物品栏 API，允许你创建物品、给予玩家物品，以及让玩家在你的游戏中整理、使用和丢弃物品。

有三个核心概念：

• 物品定义 (Item_Definition): 什么是物品 是 （名称/图标/是否可堆叠 + 你自己的字段）

• 物品实例 (Item_Instance): 世界中/物品栏内的一个实际堆栈

• 物品栏 (Inventory): 一个包含插槽并存放物品实例的容器

每个玩家都有一个内置物品栏，位于 player.default_inventory.

持久化

如果你希望玩家物品栏在游戏会话之间自动保存，请在编辑器的 Edit -> Game Settings 部分启用“自动保存玩家物品栏”选项框

物品栏 API 参考

Item_Definition_Desc :: struct {
    id:         string;
    name:       string;
    icon:       string; // /res 中的路径（省略 "/res/"）
    stack_size: s64;    // 1 = 不可堆叠，-1 = 无限
    tier:       Item_Tier;
}

Items :: struct {
    // 物品栏
    create_inventory  :: proc(unique_id: string, capacity: s64) -> Inventory;
    destroy_inventory :: proc(inventory: Inventory) -> bool;
    set_capacity      :: proc(inventory: Inventory, capacity: s64);

    // 物品定义 + 实例
    register_item_definition :: proc(desc: Item_Definition_Desc, $Definition_Type: typeid = Item_Definition, instance_type: typeid = Item_Instance) -> Definition_Type;
    create_item_instance     :: proc(definition: Item_Definition, count: s64 = 1) -> Item_Instance;
    create_item_instance     :: proc(definition: Item_Definition, $T: typeid, count: s64 = 1) -> T;
    destroy_item_instance    :: proc(instance: Item_Instance, count: s64 = -1);

    // 在不同位置移动物品
    can_move_item_to_inventory                  :: proc(instance: Item_Instance, inventory: Inventory, will_destroy_item: ref bool) -> bool;
    move_item_to_inventory                      :: proc(instance: Item_Instance, inventory: Inventory);
    move_as_many_items_as_possible_to_inventory :: proc(instance: Item_Instance, inventory: Inventory, destroyed_item: ref bool) -> s64;
    remove_item_from_inventory                  :: proc(instance: Item_Instance, inventory: Inventory);
    can_swap_items                              :: proc(inventory_a: Inventory, inventory_b: Inventory, slot_a: s64, slot_b: s64) -> bool;
    swap_items                                  :: proc(inventory_a: Inventory, inventory_b: Inventory, slot_a: s64, slot_b: s64);

    // 界面（可选）
    draw_inventory :: proc(rect: Rect, inventory: Inventory, options: Inventory_Draw_Options) -> bool;
    draw_hotbar    :: proc(player: Player, inventory: Inventory, options: Inventory_Draw_Options) -> Draw_Hotbar_Result;
}

Inventory :: class : Inventory_Base {
    get_item :: proc(inventory: Inventory, index: s64) -> Item_Instance;
}

Item_Definition :: class : Item_Definition_Base {
    get_name :: method() -> string;
    get_id   :: method() -> string;
    get_icon :: method() -> Texture_Asset;
}

Item_Instance :: class : Item_Instance_Base {
    get_definition :: method() -> Item_Definition;
}

快速开始（注册 + 给予物品）

在以下位置注册物品定义一次 ao_before_scene_load，然后创建实例并将它们移入玩家的物品栏。

// 可选：自定义物品类型
Weapon_Definition :: class : Item_Definition {
    damage: s64;
}

Weapon_Item :: class : Item_Instance {
    durability: s64 @ao_serialize; // @ao_serialize 使该字段在会话之间自动保存
}

sword_defn: Weapon_Definition;

ao_before_scene_load :: proc() {
    sword_defn = Items.register_item_definition(
        {id="sword", name="Iron Sword", icon="icons/sword.png", stack_size=1, tier=.COMMON},
        Weapon_Definition,
        Weapon_Item
    );
    sword_defn.damage = 10;
}

give_sword :: proc(player: Player) {
    item := Items.create_item_instance(sword_defn, Weapon_Item);

    will_destroy: bool;
    if Items.can_move_item_to_inventory(item, player.default_inventory, ref will_destroy) {
        item.durability = 100;
        Items.move_item_to_inventory(item, player.default_inventory);
    }
    else {
        // 物品栏已满 → 销毁我们创建的实例
        Items.destroy_item_instance(item);
    }
}

自定义物品栏

你可以创建不与玩家绑定的物品栏，用于例如：

• 箱子 / 存储容器

• 鱼/怪物队伍

chest_inventory := Items.create_inventory("chest_01", 12);

要访问物品：

for i: 0..chest_inventory.capacity-1 {
    item := chest_inventory->get_item(i);
    if item == null continue;
    defn := item->get_definition();
    log_info("Slot %: %", {i, defn->get_name()});
}

掉落物品

如果你希望玩家将物品丢到世界中（并允许其他玩家拾取），使用掉落物品系统：

import "core:dropped_items"

生成一个掉落物品

item := Items.create_item_instance(sword_defn, Weapon_Item);
dropped := Dropped_Item.spawn(player.entity.world_position, item);

丢弃动画 + 对齐到导航网格

server_rng: u64;

dropped->do_spawn_animation(ref server_rng, navmesh); // navmesh 为可选项

处理从快捷栏界面拖放

如果你使用 Items.draw_hotbar，玩家可以从界面将物品拖出以将其丢弃。 Dropped_Item.handle_dropped_item 会将其从物品栏移除并生成一个掉落物品实体。

result := Items.draw_hotbar(player, player.default_inventory, Inventory_Draw_Options.default());

dropped: Dropped_Item;
if Dropped_Item.handle_dropped_item(result, player.entity.world_position, ref dropped) {
    dropped->do_spawn_animation(ref server_rng, navmesh);
}

掉落物品会随着时间自动消失（有一个警告条）。在物品上按住交互按钮可重置其消失计时器。

你可以使用以下方法使掉落物品具有排他性（仅对某个玩家可见/可拾取）： dropped->set_exclusive(player).