Анимации Spine

Вы можете добавлять в свою игру анимированные интерактивные объекты, используя нашу существующую библиотеку из более чем 50 тысяч ригов Spine.

Spine — это то, как анимированные персонажи и объекты работают в All Out (сундуки, животные, объекты, VFX-ригги и игрок).

Чтобы сделать Spine проще для понимания, держите в голове такую модель:

Spine rig (.spine): «чертёж» (кости + имена анимаций + имена скинов)
Spine_Animator: компонент на сущности, который отрисовывает/обновляет Spine rig в мире
Spine_Instance: базовый экземпляр, которым вы управляете в коде (воспроизводите анимации, переключаете скины и т. д.)
Скины: «одежда/варианты», которые определяют, какие изображения видны
Анимации: именованные таймлайны (например, "idle", "walk", "open")

Когда использовать `Spine_Animator` vs `Spine_Instance`

Используйте Spine_Animator для всего, что существует в мире (объекты, NPC, интерактивы).
Используйте Spine_Instance непосредственно, когда вы хотите отрисовать Spine в UI или вам нужен ручной контроль над временем жизни.

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

Справочник API Spine (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);

    // Необязательно: управлять анимациями через state machine
    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("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);
    }
}

Идущая курица

Простой цикл «idle vs 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 обычно проще, чем строить state machine.

Скины (варианты/наряды)

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

State machine (необязательно, для сложной логики анимации)

Вы можете оставить логику анимаций простой, вызывая set_animation непосредственно. Если у вас много состояний (idle/run/attack/hit/death), State_Machine помогает один раз определить переходы, а затем просто задавать переменные/триггеры.

Ключевая идея: имена состояний должны совпадать с именами анимаций в вашем Spine-файле.

Что делает state machine

Думайте о state machine как о маленьком «контроллере анимаций»:

Вы определяете состояния (имя каждого состояния должно совпадать с именем анимации Spine)
Вы определяете переменные (bool, триггер, int, float)
Вы определяете переходы между состояниями на основе этих переменных
Во время выполнения вы только обновляете переменные (state machine выбирает анимацию)

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

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

    ao_start :: method() {
        // 1) Создаём state machine + переменные
        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 то state machine будет уничтожена автоматически. Иначе вы должны уничтожить её сами.

Поиск и устранение неисправностей

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

О: Убедитесь, что нажали «Add Skin» и выбрали вариант spine для применения! У некоторых spine нет скина по умолчанию.

В: Мой скрипт падает, когда я обращаюсь к spine.instance

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

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

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

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

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

Формат Spine Rig

Spine rigs состоят из 3 файлов (они автоматически загружаются для вас, когда вы используете Asset Catalog)

Skeleton-файл (.spine) содержит информацию о костях, скинах и структуре вашего анимированного объекта.
Atlas-изображение (.png) содержит реальные текстуры, используемые для отрисовки spine в мире.
Atlas-файл (.atlas) содержит информацию о том, где внутри atlas-изображения .png находится каждая часть анимированного объекта.

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

На данный момент, чтобы создавать собственные анимации или rig'и, вам понадобится копия Esoteric Spine. Однако мы предоставляем огромную библиотеку существующих spine rig'ов и анимаций в составе Каталог ресурсовдля вашего использования, и мы рекомендуем начать именно с этого!

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

Чтобы использовать пользовательский Spine rig в All Out, вам нужно экспортировать стандартный 3-файловый Spine bundle в вашу res папку:

something.spine
something.atlas
something.png (atlas texture)

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

ПредыдущаяЗвуковые эффекты СледующаяИнтерактивные объекты

Последнее обновление 23 дня назад

Добрый вечер

hashtagКогда использовать Spine_Animator vs Spine_Instance

hashtagСправочник API Spine (CSL)

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

hashtagПримеры

hashtagОткрываемый сундук

hashtagИдущая курица

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

hashtagСкины (варианты/наряды)

hashtagState machine (необязательно, для сложной логики анимации)

hashtagЧто делает state machine

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

hashtagПоиск и устранение неисправностей

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

hashtagФормат Spine Rig

hashtag

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

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

Когда использовать `Spine_Animator` vs `Spine_Instance`

Справочник API Spine (CSL)

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

Примеры

Открываемый сундук

Идущая курица

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

Скины (варианты/наряды)

State machine (необязательно, для сложной логики анимации)

Что делает state machine

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

Поиск и устранение неисправностей

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

Формат Spine Rig

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

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