Animaciones de Spine

Puedes añadir objetos interactivos animados a tu juego usando nuestra biblioteca existente de más de 50.000 rigs de Spine.

Spine es cómo funcionan los personajes animados y los props en All Out (cofres, animales, props, rigs de VFX y el jugador).

Para hacer que Spine se sienta más simple, ten este modelo mental:

• Rig de Spine (.spine): el “plano” (huesos + nombres de animaciones + nombres de skins)

• Spine_Animator: un componente en una entidad que renderiza/actualiza un rig de Spine en el mundo

• Spine_Instance: una instancia independiente (no componente), usada para animaciones de UI o control manual del ciclo de vida

• Skins: “atuendos/variantes” que deciden qué imágenes son visibles

• Animaciones: líneas de tiempo con nombre (por ejemplo "idle", "walk", "open")

Spine_Bone_Transform describe la base afín actual de un hueso en el espacio local del esqueleto. Un punto local del hueso {x, y} se asigna a posición + x_axis*x + y_axis*y.

Cuándo usar Spine_Animator vs Spine_Instance

• Usa Spine_Animator para cualquier cosa que exista en el mundo (props, NPCs, objetos interactivos).

• Usa Spine_Instance directamente cuando quieras dibujar un Spine en la UI o necesites control manual del ciclo de vida.

El motor actualiza una Spine_Animator automáticamente. Una instancia independiente debe ser actualizada y destruida por tu código.

Si llamas a Spine_Instance.create(), debes llamar a instance.destroy() cuando termines (si no, filtras memoria).

Referencia de la API de Spine (CSL)

// Componente — adjunto a entidades del mundo
Spine_Animator :: class : Component {
    depth_offset: float;
    layer: s32;
    mask_in_shadow: bool;
    instance: Spine_Instance #read_only;

    // Visuales
    color: v4; // Multiplicador RGBA; {1, 1, 1, 1} deja la apariencia sin cambios.
    scale: v2;
    speed_multiplier: float;
    state_machine: State_Machine #read_only;

    set_skeleton :: method(asset: Spine_Asset) -> u64;
    get_skeleton :: method(id: u64 = 0) -> Spine_Asset;
    set_animation :: method(animation: string, loop: bool, track: s64, speed: float = 1);

    // Skins
    set_skin          :: method(skin: string);
    enable_skin       :: method(skin: string);
    disable_skin      :: method(skin: string);
    disable_all_skins :: method();
    refresh_skins     :: method();
    get_skins         :: method() -> []string;
    set_to_setup_pose :: method();

    // Desplazamientos locales de huesos (avanzado)
    get_bone_local_position :: method(bone_name: string) -> v2;
    try_get_bone_local_transform :: method(bone_name: string) -> (Spine_Bone_Transform, bool);
    set_bone_local_position :: method(bone_name: string, position: v2);

    // Opcional: controla las animaciones mediante una máquina de estados
    set_state_machine       :: method(machine: State_Machine, transfer_ownership: bool);
    set_color_replace_color :: method(color: Color_Replace_Color);
    set_material            :: method(material: Material, transfer_ownership: bool);
    get_tint                :: method() -> v4;
    set_tint                :: method(tint: v4);
    set_destroy_entity_when_done_current_animation :: method(enabled: bool);
}

Spine_Animator hereda Component.awaken(). Cuando tu script y el animador comienzan en la misma entidad, llama a awaken() antes de acceder a la instancia del animador.

Añadiendo objetos animados a tu mundo

Hay 3 formas de añadir objetos animados a tu escena, y todas crearán un componente Spine_Animator.

• Arrastra cualquier asset animado desde el Catálogo de recursos a tu escena

• Crea una nueva entidad y añade el componente Spine_Animator

  • Establece el campo Skeleton Data Asset en un archivo .spine en tus assets

• Añade un spine animator a tu mundo usando scripting (se cubre en los ejemplos)

Si tu código y el Spine_Animator están en la misma entidad y comienzan al mismo tiempo, llama a spine.awaken() antes de llamar a cualquier método de animación.

Ejemplos

Cofre que se puede abrir

Un cofre interactivo que reproduce una animación de “open” y luego permanece abierto:

Chest :: class : Interactable {
    opened: bool;

    ao_start :: method() {
        this.set_listener(this);
        this.set_text("Abrir");
        radius = 1.25;
        required_hold_time = 0.15;

        spine := entity.get_component(Spine_Animator);
        spine.awaken();
        spine.set_animation("idle", true, 0);
    }

    can_use :: method(player: Player) -> bool {
        return !opened;
    }

    on_interact :: method(player: Player) {
        opened = true;
        this.set_text("Abierto");

        spine := entity.get_component(Spine_Animator);
        spine.set_animation("open", false, 0);
    }
}

Los nombres de animaciones y skins deben coincidir con los nombres del rig.

Pollo caminante

Un simple ciclo “idle vs walk” basado en el movimiento:

Chicken :: class : Component {
    @ao_serialize speed: float = 1.5;
    last_pos: v2;
    was_moving: bool;

    ao_start :: method() {
        last_pos = entity.world_position;

        spine := entity.get_component(Spine_Animator);
        spine.awaken();
        spine.set_animation("idle", true, 0);
    }

    ao_update :: method(dt: float) {
        // Movimiento de ejemplo (patrulla)
        entity.add_local_position({speed * dt, 0});

        moving := length_squared(entity.world_position - last_pos) > 0.0001;
        last_pos = entity.world_position;

        if moving != was_moving {
            was_moving = moving;
            spine := entity.get_component(Spine_Animator);
            spine.set_animation(moving ? "walk" : "idle", true, 0);
        }
    }
}

Coche conducible

Si quieres un comportamiento “conducible”, la forma más simple es controlar el movimiento con tu propia lógica de juego, y controlar la animación según si el coche se está moviendo.

Car :: class : Component {
    @ao_serialize agent: Movement_Agent;
    @ao_serialize target: Entity;

    ao_start :: method() {
        spine := entity.get_component(Spine_Animator);
        spine.awaken();
        spine.set_animation("idle", true, 0);
    }

    ao_update :: method(dt: float) {
        if #alive(target) {
            agent.set_path_target(target.world_position, agent.movement_speed);
        }

        moving := length_squared(agent.velocity) > 0.01;
        spine := entity.get_component(Spine_Animator);
        spine.set_animation(moving ? "drive" : "idle", true, 0);
    }
}

Si solo vas a alternar entre dos animaciones en bucle, las llamadas directas a set_animation suelen ser más simples que construir una máquina de estados.

Skins (variantes/atuendos)

Algunos spines no comienzan con una skin predeterminada. Si tu entidad está “invisible”, probablemente necesites elegir una skin.

spine := entity.get_component(Spine_Animator);
spine.awaken();

// Opción A: establecer una sola skin
spine.set_skin("default");
spine.refresh_skins();

// Opción B: combinar varias skins
spine.disable_all_skins();
spine.enable_skin("body");
spine.enable_skin("hat");
spine.refresh_skins();

Llama siempre a refresh_skins() después de cambiar las skins.

Eventos de animación

Usa callbacks cuando un evento de la línea de tiempo de Spine deba activar gameplay o audio. Para un Spine_Animator componente, registra callbacks en su instancia.

Spine_Event_Listener :: class : Component {
    ao_start :: method() {
        spine := entity.get_component(Spine_Animator);
        spine.awaken();

        spine.instance.set_on_event(this, proc(userdata: Object, event: Spine_Event_Data) {
            listener := userdata.(Spine_Event_Listener);
            listener.handle_spine_event(event);
        });
    }

    handle_spine_event :: method(event: Spine_Event_Data) {
        if event.event == "footstep" {
            desc := SFX.default_sfx_desc();
            desc.set_position(entity.world_position);
            SFX.play(get_asset(SFX_Asset, "sfx/footstep.wav"), desc);
        }
    }
}

Spine_Event_Data :: struct {
    event: string;
    int_value: s64;
    float_value: float;
    string_value: string;
}

El callback del evento se ejecuta en la ruta predicha compartida. Llama directamente al gameplay y a los SFX; no lo protejas con Game.is_server() o is_local().

Instancias independientes y UI.spine

La API independiente proporciona control manual del ciclo de vida y actualizaciones de animación:

Spine_Instance :: class {
    create  :: proc() -> Spine_Instance;
    destroy :: method();
    update  :: method(dt: float);

    set_skeleton      :: method(asset: Spine_Asset) -> u64;
    get_skeleton      :: method(id: u64 = 0) -> Spine_Asset;
    add_skeleton      :: method(asset: Spine_Asset) -> u64;
    remove_skeleton   :: method(id: u64);
    set_main_skeleton :: method(id: u64);

    set_animation :: method(animation: string, loop: bool, track: s64, speed: float = 1);
    set_skin      :: method(skin: string);
    refresh_skins :: method();

    get_bone_local_position       :: method(bone_name: string) -> v2;
    try_get_bone_local_transform  :: method(bone_name: string) -> (Spine_Bone_Transform, bool);

    set_on_event           :: method(userdata: Object, callback: proc(userdata: Object, event: Spine_Event_Data));
    set_on_animation_start :: method(userdata: Object, callback: proc(userdata: Object, animation: string));
    set_on_animation_end   :: method(userdata: Object, callback: proc(userdata: Object, animation: string));
}

Mantén la instancia en el estado persistente de la UI del jugador. Créala una sola vez, actualízala y dibújala desde método ao_late_update, y luego destrúyela desde ao_end:

My_Player :: class : Player_Base {
    menu_spine: Spine_Instance;

    ao_start :: method() {
        menu_spine = Spine_Instance.create();
        menu_spine.set_skeleton(get_asset(Spine_Asset, "characters/shopkeeper.spine"));
        menu_spine.set_skin("default");
        menu_spine.refresh_skins();
        menu_spine.set_animation("idle", true, 0);
    }

    ao_late_update :: method(dt: float) {
        if !is_local_or_server() return;

        menu_spine.update(dt);

        UI.push_screen_draw_context();
        defer UI.pop_draw_context();
        UI.spine(UI.get_screen_rect().center(), menu_spine, {0.75, 0.75});
    }

    ao_end :: method() {
        if menu_spine != null {
            menu_spine.destroy();
            menu_spine = null;
        }
    }
}

No crees la instancia dentro de método ao_late_update; eso reiniciaría su animación en cada fotograma y filtraría la instancia anterior.

Máquinas de estados (opcional, para lógica de animación compleja)

Puedes mantener la lógica de animación simple llamando a set_animation directamente. Si tienes muchos estados (idle/run/attack/hit/death), una State_Machine te ayuda a definir las transiciones una sola vez y luego solo establecer variables/triggers.

La idea clave: los nombres de los estados deben coincidir con los nombres de las animaciones en tu archivo Spine.

Qué hace una máquina de estados

Piensa en una máquina de estados como un pequeño “controlador de animación”:

• Defines estados (cada nombre de estado debe coincidir con un nombre de animación de Spine)

• Defines variables (bool, disparadores, int, float)

• Defines transiciones entre estados basadas en esas variables

• En tiempo de ejecución, solo actualizas variables (la máquina de estados elige la animación)

Ejemplo mínimo: idle/walk + disparador de ataque

NPC_Anim :: class : Component {
    state_machine: State_Machine;
    is_moving: bool;

    ao_start :: method() {
        // 1) Crea la máquina de estados + variables
        state_machine = State_Machine.create();
        moving_var := state_machine.create_variable("is_moving", .BOOL);
        attack_var := state_machine.create_variable("attack", .TRIGGER);

        // 2) Crea una capa (se mapea a una pista de Spine, normalmente 0)
        layer := state_machine.create_layer("main", 0);

        // 3) Crea estados (los nombres deben coincidir con las animaciones en el rig de Spine)
        idle := layer.create_state("idle", true);
        walk := layer.create_state("walk", true);
        attack := layer.create_state("attack", false);
        layer.set_initial_state(idle);

        // 4) Transiciones de movimiento
        idle_to_walk := layer.create_transition(idle, walk, false);
        idle_to_walk.create_bool_condition(moving_var, true);

        walk_to_idle := layer.create_transition(walk, idle, false);
        walk_to_idle.create_bool_condition(moving_var, false);

        // 5) Ataque desde cualquier estado, luego vuelve a idle al completarse
        to_attack := layer.create_global_transition(attack, true);
        to_attack.create_trigger_condition(attack_var);

        attack_to_idle := layer.create_transition(attack, idle, true); // require_state_complete = true

        // 6) Adjuntar al animador
        spine := entity.get_component(Spine_Animator);
        spine.awaken();
        spine.set_state_machine(state_machine, true); // transfer_ownership = true
    }

    ao_update :: method(dt: float) {
        state_machine.set_bool("is_moving", is_moving);
    }

    do_attack :: method() {
        state_machine.set_trigger("attack");
    }
}

Si pasas transfer_ownership = true a set_state_machine, el animador destruirá la máquina de estados por ti. De lo contrario, debes destruirla tú mismo.

Solución de problemas

P: Arrastré un asset de spine a mi escena y no veo ningún objeto, solo una entidad vacía

R: ¡Asegúrate de hacer clic en "Agregar skin" y seleccionar una variante de spine para aplicar! Algunos spines no comienzan con una skin predeterminada.

P: Mi script falla cuando llamo a métodos de animación en mi Spine_Animator

R: Si tu script y el Spine_Animator comienzan al mismo tiempo, llama a spine.awaken() antes de llamar a cualquier método de animación.

P: Cambié las skins pero no pasó nada

R: Después de cualquier cambio de skin (set_skin, enable_skin, disable_skin, disable_all_skins), debes llamar a refresh_skins().

Skins/animaciones personalizadas del jugador

Si quieres añadir animaciones personalizadas a tu jugador, puedes hacerlo fusionando el rig base de Spine del jugador de All Out con un rig personalizado que contenga más animaciones. Podemos proporcionar muchas de estas; solo Soporte para desarrolladores.

El formato del rig de Spine

Los rigs de Spine incluyen:

• Un archivo de esqueleto (.spine) con los huesos, skins, animaciones y estructura.

• Un archivo atlas (.atlas) que asigna los attachments a imágenes.

• Cada página de imagen nombrada por el atlas. Una exportación de una sola página normalmente tiene un .png.

Creando tus propias animaciones

Actualmente, para crear tus propias animaciones o rigs, necesitarás tener una copia de Esoteric Spine. Sin embargo, proporcionamos una enorme biblioteca de rigs de Spine y animaciones existentes como parte de Catálogo de recursos para que las uses, ¡y recomendamos empezar por ahí!

Formato de exportación

Para usar un rig personalizado de Spine en All Out, exporta el paquete estándar de Spine en tu res carpeta:

• something.spine

• something.atlas

• Cada archivo de imagen nombrado por something.atlas

Si no estás seguro de los ajustes de exportación, empieza a partir de un asset de Spine existente de All Out desde el Asset Catalog y replica su estructura, ¡o contacta con nosotros!