Spine 动画

你可以使用我们现有的 5 万+ Spine 绑定库，为你的游戏添加可动画交互对象。

Spine 是 All Out 中动画角色和道具的工作方式（宝箱、动物、道具、VFX 骨骼，以及玩家）。

为了让 Spine 更容易理解，记住这个心智模型：

• Spine 骨骼（.spine)：骨骼的“蓝图”（骨骼 + 动画名称 + 皮肤名称）
• Spine_Animator：实体上的一个组件，会在世界中渲染/更新一个 Spine 骨骼
• Spine_Instance：一个独立的（非组件）实例——用于 UI 动画或手动控制生命周期
• 皮肤：“服装/变体”，决定哪些图像可见
• 动画：命名时间线（例如 “idle”, “walk”, “open”)

何时使用 Spine_Animator 与 Spine_Instance

• 使用 Spine_Animator 用于世界中存在的任何东西（道具、NPC、可交互物）。
• 使用 Spine_Instance 当你想在 UI 中绘制 Spine，或者需要手动控制生命周期时，直接使用。

引擎会自动更新 Spine_Animator 。独立实例必须由你的代码负责更新和销毁。

如果你调用 Spine_Instance.create()，你必须调用 instance.destroy() 在完成后销毁它（否则会泄漏）。

Spine API 参考（CSL）

// 组件——附加到世界实体上
Spine_Animator :: class : Component {
    depth_offset: float;
    layer: s32;
    mask_in_shadow: bool;
    instance: Spine_Instance #read_only;

    // 外观
    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);

    // 皮肤
    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();

    // 骨骼局部偏移（高级）
    get_bone_local_position :: method(bone_name: string) -> v2;
    set_bone_local_position :: method(bone_name: string, position: v2);

    // 可选：通过状态机驱动动画
    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 继承 Component.awaken()。当你的脚本和 animator 在同一个实体上启动时，调用 awaken() ，再访问 animator 的实例。

将动画对象添加到你的世界中

有 3 种方式可以把动画对象添加到你的场景中，都会创建一个 Spine_Animator 组件。

• 从 资源目录 拖拽任意动画资产到你的场景中
• 新建一个实体并添加 Spine_Animator 组件

  • 将 Skeleton Data Asset 字段设置为你资源中的 .spine 文件
• 使用脚本向你的世界中添加 spine animator（示例中会讲到）

如果你的代码和 Spine_Animator 在同一个实体上并同时启动，调用 spine.awaken() ，再调用任何动画方法。

示例

可打开的宝箱

一个可交互宝箱，会播放“open”动画，然后保持打开状态：

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.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.set_animation("open", false, 0);
    }
}

动画和皮肤名称必须与骨骼中的名称一致。

行走的鸡

一个基于移动的简单“待机 vs 行走”循环：

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) {
        // 示例移动（巡逻）
        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);
        }
    }
}

可驾驶汽车

如果你想要“可驾驶”行为，最简单的方法是用你自己的游戏逻辑驱动 移动 ，并根据汽车是否在移动来驱动 动画 。

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

如果你只是在两个循环动画之间切换，直接 set_animation 调用通常比构建状态机更简单。

皮肤（变体/服装）

有些 spine 没有默认皮肤。如果你的实体“不可见”，你很可能需要选择一个皮肤。

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

// 选项 A：设置单个皮肤
spine.set_skin("default");
spine.refresh_skins();

// 选项 B：组合多个皮肤
spine.disable_all_skins();
spine.enable_skin("body");
spine.enable_skin("hat");
spine.refresh_skins();

在更改皮肤后， refresh_skins() 总是要调用。

动画事件

当 Spine 时间线事件应触发游戏逻辑或音效时，使用回调。对于一个 Spine_Animator 组件，在其 实例.

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;
}

事件回调会在共享的预测路径中运行。直接调用游戏逻辑和 SFX；不要用 Game.is_server() 或 is_local().

独立实例和 UI.spine

独立 API 提供手动生命周期和动画更新：

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

将实例保存在持久化的玩家 UI 状态中。只创建一次，从 ao_late_update中更新和绘制它，然后从 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;
        }
    }
}

不要在 ao_late_update里面创建实例；那样会让动画每帧都重新开始，并泄漏上一个实例。

状态机（可选，适用于复杂动画逻辑）

你可以通过直接调用 set_animation 来保持动画逻辑简单。如果你有很多状态（idle/run/attack/hit/death），一个 State_Machine 可以帮助你一次性定义好转换，然后只需要设置变量/触发器。

关键思想： 状态名称必须与动画名称一致 ，并且在你的 Spine 文件中。

状态机的作用

把状态机想成一个小型的“动画控制器”：

• 你定义 状态 （每个状态名称都应匹配一个 Spine 动画名称）
• 你定义 变量 (bool, 触发器, int, float)
• 你定义 转换 ，并根据这些变量在状态之间切换
• 运行时，你只更新变量（状态机负责选择动画）

最小示例：待机/行走 + 攻击触发器

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

    ao_start :: method() {
        // 1) 创建状态机 + 变量
        state_machine = State_Machine.create();
        moving_var := state_machine.create_variable("is_moving", .BOOL);
        attack_var := state_machine.create_variable("attack", .TRIGGER);

        // 2) 创建一个层（映射到 Spine 的一个轨道，通常为 0）
        layer := state_machine.create_layer("main", 0);

        // 3) 创建状态（名称必须与 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) 移动转换
        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) 从任意状态攻击，然后在完成后返回待机
        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) 绑定到 animator
        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");
    }
}

如果你传入 transfer_ownership = true 给 set_state_machine，animator 会替你销毁这个状态机。否则，你必须自己销毁它。

故障排查

问：我把一个 spine 资产拖到场景里，却看不到任何对象，它只是一个空实体

答：请确保点击“Add Skin”并选择一个 spine 变体来应用！有些 spine 没有默认皮肤。

问：当我在 Spine_Animator 上调用动画方法时，我的脚本崩溃了

答：如果你的脚本和 Spine_Animator 同时启动，调用 spine.awaken() ，再调用任何动画方法。

问：我更改了皮肤，但什么都没发生

答：在任何皮肤更改（set_skin, enable_skin, disable_skin, disable_all_skins）之后，你必须调用 refresh_skins().

自定义玩家皮肤/动画

如果你想为玩家添加自定义动画，可以通过将基础的 All Out 玩家 spine 骨骼与一个包含更多动画的自定义骨骼合并来实现。我们可以提供许多这样的资源；只需 开发者支持.

Spine 骨骼格式

Spine 骨骼包含：

• 一个骨骼文件（.spine）以及骨骼、皮肤、动画和结构。
• 一个 atlas 文件（.atlas）将附件映射到图像。
• atlas 命名的每个图像页。一个单页导出通常有一个 .png.

创建你自己的动画

目前要制作你自己的动画或骨骼，你需要拥有 Esoteric Spine 的副本。不过，我们提供了大量现有的 spine 骨骼和动画，作为 资源目录 供你使用，我们建议从那里开始！

导出格式

要在 All Out 中使用自定义 Spine 骨骼，请将标准 Spine 捆绑导出到你的 res 文件夹：

• something.spine
• something.atlas
• 每个图像文件都由 something.atlas

如果你不确定导出设置，请从 Asset Catalog 中现有的 All Out Spine 资源开始，照着它的结构来做，或者联系我们！