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 la forma en que los personajes y props animados funcionan en All Out (cofres, animales, props, rigs de VFX y el jugador).

Para que Spine se sienta más simple, conserva 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: 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 (por ejemplo, "idle", "walk", "open")

Cuándo usarlo Spine_Animator frente a 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 UI o necesites control manual del tiempo de vida.

Si llamas a Spine_Instance.create(), debes llamar a instance->destroy() cuando hayas terminado (de lo contrario, tendrás 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 formas de agregar objetos animados a tu escena, y todas 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

  • Establece el Skeleton Data Asset 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 a 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("Abrir");
        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("Abierto");

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

Pollo caminando

Un ciclo 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) {
        // 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 un comportamiento “conducible”, el enfoque 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 {
    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 solo estás alternando 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.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();

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

Máquinas de estados (opcional, 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 las transiciones una sola 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 de 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 (el nombre de cada 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 (se asigna 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 y luego volver 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) Adjunta 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, 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 a spine->awaken() antes de usar spine.instance.

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 combinando el rig de spine base de All Out con un rig personalizado que contenga más animaciones (podemos proporcionar muchas de estas, solo contáctanosSoporte para desarrolladores)

El formato del rig de Spine

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

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

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

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

Creación de 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 del Catálogo de activospara que la uses, ¡y recomendamos empezar por ahí!

Formato de exportación

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

• something.spine

• something.atlas

• something.png (textura del atlas)

Si no estás seguro de la configuración de exportación, comienza con un asset de Spine existente de All Out del Catálogo de Assets y replica su estructura, o ¡contáctanos!