Animaciones 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 y props animados en All Out (cofres, animales, props, rigs de VFX y el jugador).

Para que Spine se sienta más simple, mantén 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 (sin componente) — se usa para animaciones de UI o control manual de la vida útil
• Skins: “atuendos/variantes” que deciden qué imágenes son visibles
• Animaciones: líneas de tiempo con nombre (p. ej. "idle", "walk", "open")

Cuándo usarlo Spine_Animator vs Spine_Instance

• Usa Spine_Animator para cualquier cosa que exista en el mundo (props, NPCs, interactuables).
• Usa Spine_Instance directamente cuando quieras dibujar un Spine en UI o necesites control manual de la vida útil.

El motor actualiza un 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 hayas terminado (si no, provocarás fugas).

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_multiplier: v4;
    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;
    set_bone_local_position :: method(bone_name: string, position: v2);

    // Opcional: dirigir 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 empiezan en la misma entidad, llama a awaken() antes de acceder a la instancia del animador.

Añadir objetos animados a tu mundo

Hay 3 formas de añadir objetos animados a tu escena, 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 Skeleton Data Asset campo en un archivo .spine de tus assets
• Añade un spine animator a tu mundo usando scripting (cubierto en los ejemplos)

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

Ejemplos

Cofre abrible

Un cofre interactuable 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 las animaciones y skins deben coincidir con los nombres del rig.

Pollo caminante

Un simple bucle de "idle vs walk" basado en el movimiento:

Chicken :: class : Component {
    speed: float = 1.5 @ao_serialize;
    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 comportamiento "conducible", el enfoque más simple es controlar el movimiento con tu propia lógica de gameplay, y controlar la animación según si el coche se está moviendo.

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

    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 estás alternando solo 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 empiezan con una skin predeterminada. Si tu entidad es "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 múltiples 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 línea de tiempo de Spine deba disparar 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 a la lógica de gameplay y a los SFX; no lo protejas con Game.is_server() o is_local().

Instancias independientes y UI.spine

La API independiente proporciona vida útil y actualizaciones de animación manuales:

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

    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 vez, actualízala y dibújala desde ao_late_update, 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 ao_late_update; eso reiniciaría su animación en cada frame y provocaría una fuga de 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 ayuda a definir las transiciones una vez y luego solo establecer variables/disparadores.

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 animaciones”:

• Defines estados (cada nombre de estado debe coincidir con un nombre de animación de Spine)
• Defines variables (bool, disparador, int, float)
• Defines transiciones entre estados según 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 un track de Spine, normalmente 0)
        layer := state_machine.create_layer("main", 0);

        // 3) Crea estados (los nombres deben coincidir con las animaciones del 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 volver a idle cuando termine
        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) Adjunta 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 "Add Skin" y seleccionar una variante del spine para aplicar. Algunos spines no empiezan 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 empiezan 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 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 skeleton (.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 una .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 y animaciones de Spine existentes como parte de la Catálogo de recursos para que los uses, ¡y recomendamos empezar por ahí!

Formato de exportación

Para usar un rig de Spine personalizado 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 sobre la configuración de exportación, empieza con un asset de Spine existente de All Out desde el Catálogo de Assets y replica su estructura o ¡contáctanos!