Spine 动画

你可以使用我们现有的 5 万多个 Spine 骨骼库向你的游戏添加可交互的动画对象。

Spine 是 All Out 中带动画的角色和道具的工作方式（箱子、动物、道具、特效骨架和玩家）。

为让 Spine 更易理解，请保持以下思维模型：

• Spine 资源（.spine)： “蓝图”（骨骼 + 动画名称 + 皮肤名称）

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

• 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 :: 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);

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

    // 可视属性
    color_multiplier: v4;
    set_color_replace_color :: method(color: Color_Replace_Color);
}

将带动画对象添加到世界

有三种方法可以将带动画的对象添加到场景中，所有方法都会创建一个 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("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);
    }
}

行走的鸡

基于移动的简单“闲置 vs 行走”循环：

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 state_machine 帮助你一次性定义转换，然后只需设置变量/触发器。 关键思想：

状态名称必须与 Spine 文件中的动画名称匹配。 状态机的作用 把状态机看作一个小型的“动画控制器”：

你定义

状态

• （每个状态名应与 Spine 动画名匹配） 变量 触发器

• （每个状态名应与 Spine 动画名匹配） 基于这些变量在状态之间的转换 (bool, 在运行时，你只需更新变量（状态机会选择动画）, int, float)

• （每个状态名应与 Spine 动画名匹配） 最小示例：闲置/行走 + 攻击触发 NPC_Anim :: class : Component {

• state_machine: State_Machine;

is_moving: bool;

// 1) 创建状态机 + 变量
    state_machine = State_Machine.create();
    moving_var := state_machine->create_variable("is_moving", .BOOL);

    ao_start :: method() {
        attack_var := state_machine->create_variable("attack", .TRIGGER);
        // 2) 创建图层（映射到 Spine 的 track，通常为 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) 附加到 spine 实例
        spine.instance->set_state_machine(state_machine, true); // transfer_ownership = true

        state_machine->set_bool("is_moving", is_moving);

        do_attack :: method() {
        spine := entity->get_component(Spine_Animator);
        spine->awaken();
        state_machine->set_trigger("attack");
    }

    ao_update :: method(dt: float) {
        如果你将
    }

    transfer_ownership = true
        传递给
    }
}

set_state_machine ， 会为你销毁状态机。否则，你必须自己销毁它。 故障排查问：我把 spine 资源拖到场景中但看不到任何对象，只是一个空实体 Spine_Instance 答：确保点击 “Add Skin” 并选择要应用的 spine 变体！有些 spine 没有默认皮肤。

问：当我访问时脚本崩溃

答：如果你的脚本和

同时启动，调用

在使用之前 spine.instance

问：我更改了皮肤但没有任何反应 Spine_Animator 答：在任何皮肤更改之后（ spine->awaken() set_skin spine.instance.

enable_skin

disable_skindisable_all_skins, ），你必须调用, 自定义玩家皮肤/动画, 如果你想为玩家添加自定义动画，可以将基础的 All Out 玩家 spine 资源与包含更多动画的自定义资源合并（我们可以提供许多这样的资源，只需联系我Spine 资源格式 refresh_skins().

Spine 资源由 3 个文件组成（当你使用资源目录时会自动为你下载）

骨架文件（.spine）提供有关骨骼、皮肤和动画对象结构的信息。开发者支持)

图集图像（.png）包含在世界中绘制 spine 时使用的实际贴图。

图集文件（.atlas）提供有关动画对象的各个部分在 .png 图集图像中位置的信息。

• 创建你自己的动画

• 目前要制作你自己的动画或资源，你需要拥有 Esoteric Spine 的副本。不过，我们在

• 中为你提供了大量现有的 spine 资源和动画库，建议从那里开始！

导出格式

要在 All Out 中使用自定义 Spine 资源，你需要将标准的三文件 Spine 包导出到你的 资源目录文件夹：

something.spine

something.atlas res something.png

• （图集贴图）

• 如果你不确定导出设置，请从资源目录中已有的 All Out Spine 资源开始并模仿其结构，或联系我们！

• (atlas texture) If you're unsure about export settings, start from an existing All Out Spine asset from the Asset Catalog and mirror its structure or reach out to us!

If you pass