Inventario

Descripción general

All Out ofrece una API de inventario de jugador que te permite crear objetos, dárselos a los jugadores y que los jugadores organicen, usen y suelten objetos en tu juego.

Hay tres conceptos básicos:

• Definiciones de objeto (Item_Definition): qué es un objeto es (nombre/icono/apilamiento + tus propios campos)

• Instancias de objeto (Item_Instance): una pila real en el mundo/en un inventario

• Inventarios (Inventory): un contenedor de espacios que almacena instancias de objeto

Cada jugador tiene un inventario integrado en player.default_inventory.

Persistencia

Si quieres que los inventarios de los jugadores se guarden automáticamente entre sesiones de juego, activa la casilla Auto Save Player Inventory en la Editar → Configuración del juego sección del editor.

Configura ambas opciones por programación en ao_before_scene_load, antes de que se creen o restauren los inventarios de los jugadores:

ao_before_scene_load :: proc() {
    Scene.set_player_inventory_capacity(32);
    Scene.set_auto_save_player_inventory(true);
}

La capacidad configurada es el mínimo usado durante una restauración persistente; se conserva una capacidad mayor almacenada en la partida guardada. Cambiar la opción de la escena en Player.ao_start es demasiado tarde para el default_inventory restaurado de ese jugador y no lo redimensiona. Usa Items.set_capacity cuando necesites redimensionar intencionadamente un inventario existente. Reducirlo falla si un espacio que se va a quitar contiene un objeto.

Inventarios de jugador con nombre

Crea inventarios persistentes solo durante el ao_start del jugador. Cada clave pertenece a ese jugador:

bank: Inventory;

ao_start :: method() {
    bank = Items.create_player_inventory(this, "bank", capacity=48);
}

La llamada devuelve sincrónicamente un inventario restaurado. Repetirla con el mismo jugador y la misma clave durante ao_start devuelve el mismo inventario sin restablecer su contenido ni su capacidad. Las llamadas fuera del ao_start ao_start de ese jugador fallan incluso si el inventario ya existe; guarda el inventario devuelto en un campo para usarlo más adelante. Las claves solo pueden contener letras, números, guiones bajos o guiones y no pueden estar vacías. Mantén la clave estable entre versiones del juego.

Los inventarios con nombre se guardan automáticamente de forma independiente de la opción de guardado automático del inventario predeterminado. El motor los guarda y los destruye cuando el jugador se va; no añadas una llamada correspondiente a destroy_inventory . Quitar un registro de tu juego no borra sus datos guardados. Usa con el inventario devuelto las APIs existentes de movimiento de objetos y de dibujo de inventario.

El inventario predeterminado conserva su $AO.inventory clave de guardado, formato codificado y ruta de obtención existentes. Los inventarios con nombre usan entradas de guardado separadas $AO.inventory_<key> . Ambos pasan por la ruta de inicio del jugador existente; no hace falta migración del inventario predeterminado.

Para un inventario guardado, la capacidad es la mayor entre la capacidad inicial solicitada y la capacidad guardada. Usa Items.set_capacity para cambios posteriores. Registra las definiciones de objeto antes de que se unan jugadores.

Después de modificar directamente los campos @ao_serialize de un objeto, llama a Items.mark_item_dirty(item) para guardar el inventario que lo contiene. Las operaciones normales de inventario ya marcan los cambios como pendientes de guardar. La red CSL replica los campos automáticamente.

Referencia de la API de inventario

Scene :: struct {
    get_player_inventory_capacity :: proc() -> int;
    set_player_inventory_capacity :: proc(capacity: int);
    get_auto_save_player_inventory :: proc() -> bool;
    set_auto_save_player_inventory :: proc(enabled: bool);
}

Item_Definition_Desc :: struct {
    id:         string;
    name:       string;
    icon:       Texture_Asset;
    stack_size: s64;    // 1 = no apilable, -1 = infinito
    tier:       Item_Tier;
}

Items :: struct {
    // Inventarios
    create_inventory  :: proc(unique_id: string, capacity: s64) -> Inventory;
    create_player_inventory :: proc(player: Player, key: string, capacity: s64) -> Inventory;
    destroy_inventory :: proc(inventory: Inventory) -> bool;
    mark_item_dirty :: proc(item: Item_Instance);
    set_capacity      :: proc(inventory: Inventory, capacity: s64);

    // Definiciones de objeto + instancias
    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);

    // Mover objetos
    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);

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

    // Interfaz de usuario (opcional)
    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 {
    slots :: method() -> Inventory_Slot_Iterator;
    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;  // recuento de la pila
    slot_index: s64       #read_only;  // espacio en el inventario padre
    inventory:  Inventory #read_only;  // inventario padre (null si no está en uno)
    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: int;
    columns: int;
    rows: int;
    force_select_hotbar_index: int;
    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));

    inventory_default :: proc() -> Inventory_Draw_Options; // hotbar_item_count = 0
    hotbar_default :: proc() -> Inventory_Draw_Options;    // hotbar_item_count = 6
}

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

Inicio rápido (registrar + dar un objeto)

Registra las definiciones de objeto una vez en ao_before_scene_load, luego crea instancias y muévelas al inventario de un jugador.

// Opcional: tipos de objeto personalizados
Weapon_Definition :: class : Item_Definition {
    damage: s64;
}

Weapon_Item :: class : Item_Instance {
    @ao_serialize durability: s64;
}

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);
        // Si will_destroy es true, el objeto fue absorbido en una pila existente
        // y no deberías usar esta referencia al objeto después del movimiento.
    }
    else {
        // Inventario lleno → destruir la instancia que creamos
        Items.destroy_item_instance(item);
    }
}

Cada Item_Instance campo personalizado que deba sobrevivir al guardado y la restauración del inventario necesita campos @ao_serialize@ao_serialize. Un campo sin él vuelve a su valor predeterminado normal después de la restauración. En clases personalizadas anidadas, anota tanto el campo contenedor como cada campo anidado que deba persistir.

Persiste una selección como un arma equipada usando Save.save_item_reference(player, key, item) y Save.get_item_reference(player, key). El objeto puede pertenecer al default_inventory inventario con guardado automático del jugador o a cualquier inventario de jugador con nombre. Las referencias sobreviven al reordenamiento de espacios dentro de ese inventario y al volver a conectarse. Quitar, soltar, destruir o transferir un objeto a cualquier otro inventario invalida sus referencias anteriores, incluso para el mismo jugador o aunque el objeto luego regrese. Una pila consumida por una fusión también invalida sus referencias. Crea los inventarios con nombre antes de resolver selecciones guardadas. El inventario sigue siendo la autoridad para la propiedad y los campos del objeto, así que no copies esos valores a Save.

item.entry_id_in_inventory expone el número de entrada del inventario actual para diagnóstico. Es positivo mientras el objeto está poseído, permanece sin cambios cuando se reordenan los espacios, cambia en las transferencias y se vuelve 0 cuando se separa. Las referencias guardadas incluyen la clave del inventario junto con este número. Usa Save.save_item_reference en lugar de persistir el número directamente.

Mostrar la barra rápida

Para mostrar en pantalla la interfaz estándar de la barra rápida del inventario, llama a Items.draw_hotbar dentro del método ao_late_update de tu Player. Sin ello, el sistema de inventario funciona internamente, ¡pero el jugador no lo verá!

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.hotbar_default();
    options.hide_bag_button = false;

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

    // result.selected_item es el objeto actualmente resaltado (o null)
    // result.inventory_open te dice si se está mostrando la interfaz completa de la mochila
}

Items.draw_hotbar gestiona por ti toda la interfaz de la barra rápida + el alternador de mochila. Devuelve un Draw_Hotbar_Result con los campos selected_item, selected_item_index, inventory_open y dropped_item .

hide_bag_button = true impide que el jugador abra la mochila. Si la mochila ya está abierta, se cerrará, así que úsalo solo cuando los jugadores todavía tengan otra forma de acceder a objetos importantes.

Comprobar si un jugador ya tiene un objeto

Un patrón común es dar un objeto solo si el jugador no tiene ya uno:

Usa el ID registrado de la definición:

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

También puedes comprobar cuánto espacio queda para un tipo específico de objeto antes de crearlo:

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

Inventarios personalizados

Puedes crear inventarios que no estén vinculados a un jugador, para cosas como:

• Cofres / contenedores de almacenamiento

• Equipos de peces/mobs

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

Para acceder a los objetos:

for item, slot: chest_inventory.slots() if item != null {
    defn := item.get_definition();
    log_info("Slot %: %", {slot, defn.name});
}

slots() visita cada espacio en orden. item es null para un espacio vacío, y la segunda variable opcional del bucle es el índice real del espacio. Usa get_item(index) cuando necesites acceso aleatorio a un espacio.

Movimientos atómicos de objetos

Usa una transacción cuando varios movimientos de objetos deban tener todos éxito o todos fallar:

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

Cada instancia de objeto puede aparecer solo una vez en la transacción. Llama siempre primero a can_move_all_items ; move_all_items lanza una aserción si la transacción completa ya no cabe. Un movimiento puede fusionar una pila y destruir la instancia movida, así que no sigas usando referencias al objeto después de la transacción.

Objetos soltados

Si quieres que los jugadores suelten objetos en el mundo (y que otros jugadores los recojan), usa el sistema de objetos soltados:

import "core:dropped_items"

Generar un objeto soltado

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

Animación de soltar + ajuste a la navmesh

gameplay_rng: u64;

dropped.do_spawn_animation(ref gameplay_rng, navmesh); // la navmesh es opcional

Gestionar arrastrar y soltar desde la interfaz de la barra rápida

Si usas Items.draw_hotbar, los jugadores pueden arrastrar un objeto fuera de la interfaz para soltarlo. Dropped_Item.handle_dropped_item lo elimina del inventario y genera una entidad de objeto soltado.

result := Items.draw_hotbar(player, player.default_inventory, Inventory_Draw_Options.hotbar_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);
}

Los objetos soltados desaparecen automáticamente con el tiempo (con una barra de advertencia). Mantener pulsado el botón de interactuar sobre un objeto reinicia su temporizador de desaparición.

Puedes hacer que un objeto soltado sea exclusivo (solo visible/recogible por un jugador) usando dropped.set_exclusive(player).