Animaciones Spine

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

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

Para que Spine resulte más sencillo, mantén este modelo mental:

• Rig de Spine (.spine): el “plano” (huesos + nombres de animación + nombres de skin)

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

• Spine_Instance: la instancia subyacente que controlas en código (reproducir animaciones, cambiar skins, etc.)

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

• Animaciones: líneas de tiempo nombradas (p. ej. "idle", "walk", "open")

Cuándo usar Spine_Animator vs Spine_Instance

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

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

Si llamas Spine_Instance.create(), debes llamar instance->destroy() cuando termines (de lo contrario generas una fuga de memoria).

Referencia de la API de Spine (CSL)

Spine_Animator :: class : Component {
    depth_offset: float;
    layer: s32;
    instance: Spine_Instance #read_only;
}

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

    set_skeleton :: method(asset: Spine_Asset);
    get_skeleton :: method() -> 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;

    // 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: controlar animaciones mediante una máquina de estados
    set_state_machine :: method(new_state_machine: State_Machine, transfer_ownership: bool);

    // Visuales
    color_multiplier: v4;
    set_color_replace_color :: method(color: Color_Replace_Color);
}

Agregar objetos animados a tu mundo

Hay 3 formas de agregar objetos animados a tu escena, todas las cuales crearán un componente Spine_Animator.

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

• Crea una nueva entidad y agrega el componente Spine_Animator

  • Configura el Asset de datos del esqueleto al campo a un archivo .spine en tus assets

• Agrega un animador de spine 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 spine->awaken() antes de acceder a spine.instance.

Ejemplos

Cofre que se puede abrir

Un cofres interactuable que reproduce una animación de “abrir” y luego se queda abierto:

Chest :: class : Interactable {
    opened: bool;

    ao_start :: method() {
        this->set_listener(this);
        this->set_text("Open");
        radius = 1.25;
        required_hold_time = 0.15;

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

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

    on_interact :: method(player: Player) {
        opened = true;
        this->set_text("Opened");

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

Pollo caminando

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

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

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

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

    ao_update :: method(dt: float) {
        // Ejemplo de movimiento (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.instance->set_animation(moving ? "walk" : "idle", true, 0);
        }
    }
}

Coche manejable

Si quieres comportamiento “manejable”, el enfoque más simple es conducir el movimiento con tu propia lógica de juego, y controlar la animación basada en 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.instance->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.instance->set_animation(moving ? "drive" : "idle", true, 0);
    }
}

Si estás cambiando entre solo 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 escoger una skin.

spine := entity->get_component(Spine_Animator);
spine->awaken();

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

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

Siempre llama a refresh_skins() después de cambiar skins.

Máquinas de estados (opcionales, 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 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 animación”:

• 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 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 (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 volver a idle cuando se complete
        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 a la instancia de spine
        spine := entity->get_component(Spine_Animator);
        spine->awaken();
        spine.instance->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 Spine_Instance 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, es 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 comienzan con una skin predeterminada.

P: Mi script se bloquea cuando accedo a spine.instance

R: Si tu script y el Spine_Animator comienzan al mismo tiempo, llama spine->awaken() antes de usar spine.instance.

P: Cambié skins pero no pasó nada

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

Skins/Animaciones personalizadas del jugador

Si quieres añadir animaciones personalizadas a tu jugador, puedes hacerlo combinando el rig base del jugador de All Out con un rig personalizado que contenga más animaciones (podemos proporcionar muchos de estos, solo contáctanosSoporte para Desarrolladores)

El formato del rig de Spine

Los rigs de Spine están formados por 3 archivos (descargados automáticamente cuando usas el Catálogo de Assets)

• El archivo del esqueleto (.spine) proporciona información sobre los huesos, skins y la estructura de tu objeto animado.

• La imagen del atlas (.png) contiene las texturas reales usadas para dibujar el spine en el mundo.

• El archivo del atlas (.atlas) proporciona información sobre dónde dentro de la imagen atlas .png se encuentra cada parte del objeto animado.

Crear 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 Activospara que la uses y recomendamos comenzar allí.

Formato de exportación

Para usar un rig de Spine personalizado en All Out, necesitas exportar el paquete estándar de 3 archivos de Spine dentro de tu res carpeta:

• algo.spine

• algo.atlas

• algo.png (textura del atlas)

Si no estás seguro sobre los ajustes de exportación, comienza a partir de un asset de Spine existente de All Out del Catálogo de Assets y replica su estructura o contáctanos.