Animaciones Spine

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

Spine es cómo funcionan los personajes y accesorios animados en All Out (cajas, animales, objetos, 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 animación + nombres de skin)

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

• Instancia_de_Spine: 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 con nombre (p. ej. "idle", "walk", "open")

Cuándo usar Spine_Animator vs Instancia_de_Spine

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

• Usa Instancia_de_Spine directamente cuando quieres dibujar un Spine en la UI o necesitas control manual del ciclo de vida.

Si llamas Spine_Instance.create(), debes llamar instance->destroy() cuando hayas terminado (si no, provocas una fuga).

Referencia de la API de Spine (CSL)

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

Spine_Instance_Base :: class {
    // Visuales
    color_multiplier: v4;
    scale: v2;
    speed_multiplier: float;
    state_machine: State_Machine #read_only;
    color_replace_color: Color_Replace_Color #read_only;
    set_color_replace_color :: method(color: Color_Replace_Color);
    set_material :: method(material: Material, transfer_ownership: bool);
}

Spine_Instance :: class : Spine_Instance_Base {
    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);
}

Agregar objetos animados a tu mundo

Hay 3 maneras 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 añade el componente Spine_Animator

  • Configura el Asset de Datos de Esqueleto campo a un archivo .spine en 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 comienzan al mismo tiempo, llama spine->awaken() antes de acceder a spine.instance.

Ejemplos

Cofre Abrible

Un cofre interactuable que reproduce una animación de “abrir” y luego permanece 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 Caminante

Un simple bucle “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) {
        // 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.instance->set_animation(moving ? "walk" : "idle", true, 0);
        }
    }
}

Coche Conducible

Si quieres comportamiento “conducible”, el enfoque más simple es conducir el movimiento con tu propia lógica de juego, y conducir la animación en función de si el coche está en movimiento.

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 alternando 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 por defecto. Si tu entidad está “invisible”, probablemente necesites seleccionar 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 múltiples skins
spine.instance->disable_all_skins();
spine.instance->enable_skin("body");
spine.instance->enable_skin("hat");
spine.instance->refresh_skins();

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

Máquinas de estado (opcionales, para lógica de animación compleja)

Puedes mantener la lógica de animación simple llamando 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 estado deben coincidir con los nombres de animación en tu archivo Spine.

Lo que hace una máquina de estado

Piensa en una máquina de estado 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 estado 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) Crear la máquina de estado + variables
        state_machine = State_Machine.create();
        moving_var := state_machine->create_variable("is_moving", .BOOL);
        attack_var := state_machine->create_variable("attack", .TRIGGER);

        // 2) Crear una capa (mapea a una pista de Spine, normalmente 0)
        layer := state_machine->create_layer("main", 0);

        // 3) Crear 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) Atacar 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) 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 Instancia_de_Spine destruirá la máquina de estado 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 empiezan con una skin por defecto.

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 fusionando 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 compuestos por 3 archivos (descargados automáticamente para ti cuando usas el Catálogo de Assets)

• El archivo de 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 .png del atlas se encuentra cada parte del objeto animado.

Crear tus propias animaciones

Actualmente, para hacer tus propias animaciones o rigs, necesitarás tener una copia de Esoteric Spine. Sin embargo, ofrecemos una enorme biblioteca de rigs y animaciones de spine existentes como parte de la Catálogo de activospara que las 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 en el Catálogo de Assets y replica su estructura o contáctanos!