Spine 动画

你可以使用我们现有的 50k+ Spine 骨骼库，为你的游戏添加可交互的动画对象。

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

为了让 Spine 感觉更简单，请记住这个思维模型：

• Spine rig（.spine)："蓝图"（骨骼 + 动画名称 + 皮肤名称）

• Spine_Animator：实体上的一个组件，用于在世界中渲染/更新 Spine rig

• Spine_Instance：你在代码中控制的底层实例（播放动画、切换皮肤等）

• 皮肤：决定哪些图像可见的“服装/变体”

• 动画：命名的时间轴（例如 "idle", "walk", "open")

何时使用 Spine_Animator 与 Spine_Instance

• 使用 Spine_Animator 用于任何存在于世界中的对象（道具、NPC、可交互对象）。

• 使用 Spine_Instance 当你想在 UI 中直接绘制 Spine，或者需要手动控制生命周期时直接使用。

如果你调用了 Spine_Instance.create()，你必须调用 instance->destroy() 当你用完时（否则会发生泄漏）。

Spine API 参考（CSL）

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

Spine_Instance_Base :: class {
    // 视觉
    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);

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

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

    // 可选：通过状态机驱动动画
    set_state_machine :: method(new_state_machine: State_Machine, transfer_ownership: bool);
}

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

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

• 将任意动画资源从 资源目录拖入你的场景中

• 创建一个新实体并添加 Spine_Animator 组件

  • 将 Skeleton Data Asset 字段设置为你资源中的 .spine 文件

• 使用脚本向你的世界添加一个 spine animator（示例中会讲到）

如果你的代码和 Spine_Animator 在同一个实体上并且同时启动，请调用 spine->awaken() 然后再访问 spine.instance.

示例

可开启的宝箱

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

Chest :: class : Interactable {
    opened: bool;

    ao_start :: method() {
        this->set_listener(this);
        this->set_text("打开");
        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("已打开");

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

行走的鸡

一个基于移动的简单“idle 与 walk”循环：

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

可驾驶的汽车

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

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

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

皮肤（变体/服装）

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

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

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

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

始终调用 refresh_skins() 在更改皮肤之后。

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

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

关键思想： 状态名称必须与动画名称匹配 在你的 Spine 文件中。

状态机的作用

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

• 你定义 状态 （每个状态名称都应与一个 Spine 动画名称匹配）

• 你定义 变量 (bool, 触发器, int, float)

• 你定义 转换 基于这些变量在状态之间切换

• 在运行时，你只更新变量（状态机会选择动画）

最小示例：idle/walk + attack 触发器

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 rig 中的动画匹配）
        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) 从任意状态攻击，然后在完成时返回 idle
        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) 附加到 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");
    }
}

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

故障排除

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

答：请确保点击“Add Skin”并选择一个要应用的 spine 变体！有些 spine 不会以默认皮肤开始。

问：当我访问时，我的脚本崩溃了 spine.instance

答：如果你的脚本和 Spine_Animator 同时启动，请调用 spine->awaken() 然后再使用 spine.instance.

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

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

自定义玩家皮肤/动画

如果你想给玩家添加自定义动画，可以通过将基础 All Out 玩家 spine rig 与包含更多动画的自定义 rig 合并来实现（我们可以提供许多这样的资源，联系我​​们即可开发者支持)

Spine Rig 格式

Spine rigs 由 3 个文件组成（当你使用 Asset Catalog 时会自动为你下载）

• 骨架文件（.spine）提供有关你的动画对象的骨骼、皮肤和结构的信息。

• 图集图像（.png）包含用于在世界中绘制 spine 的实际纹理。

• 图集文件（.atlas）提供有关动画对象各个部分位于 .png 图集图像内部何处的信息。

创建你自己的动画

目前，要制作你自己的动画或 rig，你需要拥有一份 Esoteric Spine。不过，作为 资源目录的一部分，我们提供了一个庞大的现有 spine rigs 和动画库供你使用，我们建议从这里开始！

导出格式

要在 All Out 中使用自定义 Spine rig，你需要将标准的 3 文件 Spine bundle 导出到你的 res 文件夹：

• something.spine

• something.atlas

• something.png （图集纹理）

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