库存

概览

All Out 提供一个玩家物品栏 API，允许你创建物品、把它们发给玩家，并让玩家在你的游戏中整理、使用和丢弃物品。

有三个核心概念：

• 物品定义 (Item_Definition）：一个物品的 是 （名称/图标/堆叠 + 你自己的字段）
• 物品实例 (Item_Instance）：世界中/物品栏中的实际堆叠
• 物品栏 (Inventory）：一个装有物品实例的槽位容器

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

持久化

如果你希望玩家物品栏在不同游戏会话之间自动保存，请启用 自动保存玩家物品栏 编辑器中的 编辑 → 游戏配置 部分。

你也可以在 CSL 中以编程方式配置这些设置。调用 Scene.set_auto_save_player_inventory(true) 和 Scene.set_player_inventory_capacity(32) 在场景初始化期间（例如在 ao_before_scene_load）中，在任何玩家加入之前。

物品栏 API 参考

Item_Definition_Desc :: struct {
    id:         string;
    name:       string;
    icon:       Texture_Asset;
    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_move_all_items                          :: proc(entries: []Item_Transaction_Entry) -> bool;
    move_all_items                              :: proc(entries: []Item_Transaction_Entry);
    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);

    // 查询
    calculate_room_in_inventory_for_item :: proc(definition: Item_Definition, inventory: Inventory) -> s64;
    destroy_all_items :: proc(inventory: Inventory);

    // UI（可选）
    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 {
    get_item :: proc(inventory: Inventory, index: s64) -> Item_Instance;
    has_item_id :: proc(inventory: Inventory, item_id: string) -> bool;
    capacity: s64 #read_only;
}

Item_Definition :: class {
    get_icon :: method() -> Texture_Asset;
    id: string #read_only;
    name: string #read_only;
    type: typeid #read_only;
    instance_type: typeid #read_only;
    tier: Item_Tier #read_only;
}

Item_Instance :: class {
    quantity:   s64       #read_only;  // 堆叠数量
    slot_index: s64       #read_only;  // 父物品栏中的槽位
    inventory:  Inventory #read_only;  // 父物品栏（如果不在任何物品栏中则为 null）
    get_definition :: method() -> Item_Definition;
}

Item_Transaction_Entry :: struct {
    instance: Item_Instance;
    inventory: Inventory;
}

Inventory_Draw_Options :: struct {
    title: string;
    show_exit_button: bool;
    show_scroll_bar: bool;
    show_background: bool;
    allow_drag_drop: bool;
    drag_drop_color_multiplier: v4;
    hotbar_item_count: s32;
    columns: s32;
    rows: s32;
    force_select_hotbar_index: s32;
    hide_bag_button: bool;
    enable_selection: bool;
    scroll_item_selection: bool;
    keyboard_item_selection: bool;
    enable_use_from_hotbar: bool;
    on_before_draw: (proc(item: Item_Instance, rect: Rect));
    on_after_draw: (proc(item: Item_Instance, rect: Rect));

    default :: proc() -> Inventory_Draw_Options;
}

Draw_Hotbar_Result :: struct {
    selected_item: Item_Instance;
    selected_item_index: s64;
    dropped_item: Item_Instance;
    entire_rect: Rect;
    inventory_open: bool;
    inventory_open_t: float;
}

快速开始（注册 + 发放物品）

只需在 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=get_asset(Texture_Asset, "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);
        // 如果 will_destroy 为 true，则该物品已被吸收到现有堆叠中
        // 移动后不应再使用这个物品引用。
    }
    else {
        // 物品栏已满 → 销毁我们创建的实例
        Items.destroy_item_instance(item);
    }
}

显示快捷栏

要在屏幕上显示标准物品栏快捷栏 UI，请调用 Items.draw_hotbar 在你的 Player 的 ao_late_update 方法中。没有它，物品栏系统仍会在后台运行，但玩家看不到！

Player :: class : Player_Base {
    ao_late_update :: method(dt: float) {
        if this.is_local_or_server() {
            draw_player_hotbar(this);
        }
    }
}

draw_player_hotbar :: proc(player: Player) {
    options := Inventory_Draw_Options.default();
    options.hide_bag_button = false;

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

    // result.selected_item 是当前高亮的物品（或 null）
    // result.inventory_open 告诉你完整背包 UI 是否正在显示
}

Items.draw_hotbar 它会为你处理整个快捷栏 + 背包切换 UI。它返回一个 Draw_Hotbar_Result 包含 selected_item, selected_item_index, inventory_open，以及 dropped_item 字段。

hide_bag_button = true 会阻止玩家打开背包。如果背包已经打开，它会关闭，所以只有在玩家仍有其他方式访问重要物品时才使用它。

检查玩家是否已经拥有某个物品

一种常见做法是：只有在玩家还没有该物品时才发放它：

使用该定义注册的 ID：

give_sword_if_needed :: proc(player: Player) {
    if player.default_inventory.has_item_id("sword") return;
    give_sword(player);
}

在创建某种特定物品之前，你还可以检查剩余空间有多少：

room := Items.calculate_room_in_inventory_for_item(sword_defn, player.default_inventory);
if room > 0 {
    give_sword(player);
}

自定义物品栏

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

• 箱子 / 储物容器
• 鱼群/怪物队伍

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

要访问物品：

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

原子性物品移动

当多次物品移动必须要么全部成功要么全部失败时，请使用事务：

moves: [..]Item_Transaction_Entry;
moves.append({instance = sword, inventory = player.default_inventory});
moves.append({instance = shield, inventory = player.default_inventory});

if Items.can_move_all_items(moves) {
    Items.move_all_items(moves);
}

每个物品实例在事务中只能出现一次。务必先调用 can_move_all_items ； move_all_items 如果完整事务已无法放入，则会触发断言。移动可能会合并堆叠并销毁被移动的实例，因此事务结束后不要继续使用物品引用。

掉落物品

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

import "core:dropped_items"

生成一个掉落物品

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

掉落动画 + 吸附到导航网格

gameplay_rng: u64;

dropped.do_spawn_animation(ref gameplay_rng, navmesh); // navmesh 可选

处理来自快捷栏 UI 的拖放

如果你使用 Items.draw_hotbar，玩家可以把物品从 UI 中拖出以丢弃它。 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 gameplay_rng, navmesh);
}

掉落物会随着时间自动消失（并显示警告条）。按住与物品交互按钮会重置其消失计时器。

你可以使用 dropped.set_exclusive(player).