Анимации Spine

Вы можете добавлять в игру анимированные интерактивные объекты, используя нашу библиотеку из более чем 50 000 ригов 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 напрямую, когда хотите отрисовать Spine в UI или вам нужен ручной контроль времени жизни.

Движок обновляет Spine_Animator автоматически. Самостоятельный экземпляр должен обновляться и уничтожаться вашим кодом.

Если вы вызываете Spine_Instance.create(), вы должны вызвать instance.destroy() когда закончите (иначе будет утечка).

Справочник по API Spine (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(). Когда ваш скрипт и аниматор запускаются на одной сущности, вызовите awaken() до обращения к экземпляру аниматора.

Добавление анимированных объектов в ваш мир

Есть 3 способа добавить анимированные объекты в вашу сцену, и все они создадут компонент Spine_Animator.

• Перетащите любой анимированный ресурс из Каталог ассетов в вашу сцену
• Создайте новую сущность и добавьте компонент Spine_Animator

  • Укажите поле Skeleton Data Asset на .spine-файл в ваших ресурсах
• Добавьте аниматор Spine в ваш мир с помощью скрипта (это показано в примерах)

Если ваш код и 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);
    }
}

Имена анимаций и скинов должны совпадать с именами в риге.

Ходящая курица

Простой цикл «idle vs walk» на основе движения:

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

Управляемая машина

Если вам нужно поведение "driveable", самый простой подход — управлять движением с помощью собственной игровой логики и управлять анимацией в зависимости от того, движется ли машина.

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() после изменения скинов.

События анимации

Используйте callback-функции, когда событие таймлайна Spine должно запускать геймплей или звук. Для Spine_Animator компонента регистрируйте callback'и на его экземпляре.

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

Callback события выполняется в общем предсказанном пути. Вызывайте геймплей и 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)
• Вы задаёте переходы между состояниями на основе этих переменных
• Во время работы вы просто обновляете переменные (конечный автомат выбирает анимацию)

Минимальный пример: idle/walk + триггер атаки

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) Атака из любого состояния, затем возврат в 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 := 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, аниматор сам уничтожит конечный автомат за вас. Иначе вы должны уничтожить его сами.

Поиск и устранение неполадок

В: Я перетащил spine-ресурс в сцену, и не вижу никакого объекта — это просто пустая сущность

О: Нажмите "Add Skin" и выберите вариант Spine, который нужно применить! У некоторых Spine нет скина по умолчанию.

В: Мой скрипт падает, когда я вызываю методы анимации у моего Spine_Animator

О: Если ваш скрипт и Spine_Animator запускаются одновременно, вызовите spine.awaken() до вызова любых методов анимации.

В: Я изменил скины, но ничего не произошло

О: После любого изменения скина (set_skin, enable_skin, disable_skin, disable_all_skins), вы должны вызвать refresh_skins().

Пользовательские скины/анимации игрока

Если вы хотите добавить собственные анимации своему игроку, вы можете сделать это, объединив базовый риг Spine игрока All Out с пользовательским ригом, содержащим дополнительные анимации. Мы можем предоставить много таких; просто Поддержка разработчиков.

Формат рига Spine

Риги Spine включают:

• Файл скелета (.spine) с костями, скинами, анимациями и структурой.
• Файл атласа (.atlas), который сопоставляет attachment'и с изображениями.
• Каждая страница изображения, указанная в атласе. Обычно экспорт на одну страницу имеет один .png.

Создание собственных анимаций

Сейчас, чтобы создавать собственные анимации или риги, вам понадобится копия Esoteric Spine. Однако в составе Каталог ассетов мы предоставляем огромную библиотеку существующих ригов Spine и анимаций, которую вы можете использовать, и мы рекомендуем начать с неё!

Формат экспорта

Чтобы использовать пользовательский риг Spine в All Out, экспортируйте стандартный пакет Spine в вашу res папку:

• something.spine
• something.atlas
• Каждый файл изображения, названный по something.atlas

Если вы не уверены в настройках экспорта, начните с существующего ресурса All Out Spine из Asset Catalog и повторите его структуру или свяжитесь с нами!