Эффекты

Эффекты временно берут управление над сущностью для сложных действий, таких как рывки, атаки, анимации еды, катсцены или последовательности смерти/возрождения.

Эффекты можно использовать на игроках, NPC или любой сущности. Они особенно полезны, когда вам нужно:

• Движение, которым вы управляете в коде (рывок/отбрасывание/кувырок)
• На короткое время "заблокировать" ввод игрока для последовательности (еда, воскрешение, катсцена)
• Ограниченное по времени состояние (неуязвимость, замедление, оглушение)
• UI, привязанное к временным состояниям (таймер возрождения)

Активные и пассивные

All Out поддерживает два типа эффектов:

• Активные эффекты: по одному за раз на сущность. Назначение нового активного эффекта прерывает текущий активный эффект.
• Пассивные эффекты: можно прикреплять несколько одновременно (стекаемые баффы/дебаффы/статусы).

Активный эффект также добавляется в список эффектов сущности, поэтому он появляется в effect_iterator так же, как и пассивные эффекты.

Быстрый старт (простой эффект с таймером)

Создайте класс, который наследуется от Effect_Base, затем прикрепите его к сущности.

Apple_Pop_Effect :: class : Effect_Base {
    sprite: Sprite_Renderer;
    start_scale: v2;
    start_pos: v2;

    effect_start :: method() {
        sprite = entity.get_component(Sprite_Renderer);
        start_scale = entity.local_scale;
        start_pos = entity.local_position;
        set_duration(0.4); // автоматически удаляется через 0.4 с
    }

    effect_update :: method(dt: float) {
        t := get_elapsed_time() / 0.4;

        // Увеличить, а затем уменьшить до нуля
        scale_curve: float;
        if t < 0.3 {
            scale_curve = lerp(1.0, 1.3, Ease.out_back(t / 0.3));
        } else {
            scale_curve = lerp(1.3, 0.0, Ease.in_back((t - 0.3) / 0.7));
        }

        entity.set_local_scale(start_scale * scale_curve);

        // Слегка всплываем вверх
        rise := Ease.out_quad(t) * 0.5;
        entity.set_local_position({start_pos.x, start_pos.y + rise});

        // Почти в конце исчезаем
        if sprite != null {
            alpha := 1.0 - Ease.in_quad(max(0.0, (t - 0.5) / 0.5));
            sprite.color.w = alpha;
        }
    }

    effect_end :: method(interrupt: bool) {
        // Очистить ресурсы по завершении (или при прерывании)
        entity.destroy();
    }
}

Добавьте его как активный эффект:

effect := new(Apple_Pop_Effect);
entity.set_active_effect(effect);

Жизненный цикл эффекта

Эффекты основаны на колбэках. Реализуйте только то, что нужно:

• effect_start(): вызывается один раз, когда эффект прикрепляется
• effect_update(dt): вызывается каждый кадр
• effect_late_update(dt): вызывается каждый кадр после effect_update
• effect_end(interrupt): вызывается, когда эффект удаляется

Активные эффекты (эксклюзивное управление)

Используйте set_active_effect для эффектов, которые должны быть взаимоисключающими (рывок, подготовка атаки, последовательность смерти).

dash := new(Dash_Effect);
dash.direction = {1, 0};
player.entity.set_active_effect(dash);

Если у сущности уже есть активный эффект, он завершается с interrupt = true.

Пассивные эффекты (стекаемые баффы / статусы)

Используйте add_passive_effect для эффектов, которые могут складываться (замедление, яд, щит, окно неуязвимости).

slow := new(Slow_Effect);
slow.speed_multiplier = 0.5;
slow.set_duration(4.0);
enemy.entity.add_passive_effect(slow);

Справочник API

Effect_Base

Effect_Base :: class {
    entity: Entity;
    player: Player; // null, если этот эффект не был добавлен игроку!

    player_specific: struct {
        freeze_player: bool;
        disable_movement_inputs: bool;
    };

    // Необязательные колбэки
    #interface effect_start       :: proc(c: Effect_Base);
    #interface effect_update      :: proc(c: Effect_Base, dt: float);
    #interface effect_late_update :: proc(c: Effect_Base, dt: float);
    #interface effect_end         :: proc(c: Effect_Base, interrupt: bool);

    // Только для чтения
    start_time: float;
    next_effect: Effect_Base;
    prev_effect: Effect_Base;

    get_elapsed_time :: method() -> float;
    get_duration_remaining :: method() -> float;
    set_duration     :: method(duration: float);
    remove_effect    :: method(interrupt: bool);
}

Применение / удаление эффектов

set_active_effect  :: proc(entity: Entity, new_active_effect: $T);
add_passive_effect :: proc(entity: Entity, new_effect: $T);

remove_all_effects :: proc(entity: Entity);
remove_effect      :: proc(entity: Entity, type: typeid, interrupt: bool) -> bool;

Проверка / перебор эффектов

get_effect :: proc(entity: Entity, $T: typeid, mode := Try_Get_Effect_Mode.EXACT_MATCH) -> T, bool;
has_effect :: proc(entity: Entity, $T: typeid, mode := Try_Get_Effect_Mode.EXACT_MATCH) -> bool;

effect_iterator :: proc(entity: Entity) -> Effect_Iterator;

После вызова remove_effect(...), эффект отсоединяется и больше не привязан к корню. Его ссылка недействительна. Немедленно верните управление и не обращайтесь this к нему снова.

freeze_player по сравнению с disable_movement_inputs

• player_specific.freeze_player = true: полностью блокирует положение игрока.
• player_specific.disable_movement_inputs = true: игнорирует ввод, но ваш эффект всё ещё может перемещать игрока (рывок/кувырок).

Оба варианта применяются только когда player != null (то есть эффект находится у сущности, у которой есть Player компонент).

Эмоции игрока

Эмоции игрока используют встроенный активный эффект. Запуск другой эмоции прерывает текущую эмоцию, а любой другой активный эффект не даёт запустить новую эмоцию. Движение прерывает эмоции и восстанавливает основную анимационную прослойку, кроме Emote/T_Pose, которая позволяет двигаться.

Используйте причины блокировки, когда геймплей должен временно запретить колесу эмоций запускать эмоцию:

player.add_emote_block_reason("stunned");

// Позже, когда ограничение закончится:
player.remove_emote_block_reason("stunned");

Причины учитываются как записи, поэтому важно вызывать add/remove в паре. remove_emote_block_reason удаляет одну совпадающую запись и возвращает, была ли она найдена. Вы также можете напрямую запросить или управлять встроенным эффектом:

if player.is_emote_blocked() {
    // Активна как минимум одна причина блокировки.
}

started := player.try_trigger_emote("Emote/Wave");
cancelled := player.cancel_emote();

try_trigger_emote возвращает false когда анимация не экипирована, эмоции заблокированы или другой тип активного эффекта уже управляет игроком. Обычное колесо эмоций использует тот же путь.

Примеры эффектов

Рывок / кувырок (активный эффект)

Roll_Effect :: class : Effect_Base {
    direction: v2;
    original_friction: float;

    effect_start :: method() {
        player_specific.disable_movement_inputs = true;
        original_friction = player.agent.friction;
        player.agent.friction = 0;
        player.animator.state_machine.set_trigger("dodge_roll");
        player.set_facing_right(direction.x > 0);
        set_duration(0.5);
    }

    effect_update :: method(dt: float) {
        player.agent.velocity = direction * 8;
    }

    effect_end :: method(interrupt: bool) {
        player.agent.friction = original_friction;
    }
}

Окно неуязвимости (пассивный эффект)

Используйте пассивный эффект для представления состояния неуязвимости и проверяйте его везде, где наносите урон.

Invincible_Effect :: class : Effect_Base {
}

give_invincibility :: proc(player: Player, seconds: float) {
    e := new(Invincible_Effect);
    e.set_duration(seconds);
    player.entity.add_passive_effect(e);
}

// Пример проверки получения урона:
take_damage :: proc(player: Player, amount: s64) {
    if player.entity.has_effect(Invincible_Effect) {
        return;
    }
    // Предполагается, что в вашем классе Player есть поле здоровья.
    player.health.take_damage(amount);
}

Увеличение размера в 2 раза на несколько секунд (пассивный эффект)

Grow_Effect :: class : Effect_Base {
    scale_multiplier: float;
    start_scale: v2;

    effect_start :: method() {
        start_scale = entity.local_scale;
        entity.set_local_scale(start_scale * scale_multiplier);
    }

    effect_end :: method(interrupt: bool) {
        entity.set_local_scale(start_scale);
    }
}

apply_grow :: proc(entity: Entity) {
    if entity.has_effect(Grow_Effect) return;

    e := new(Grow_Effect);
    e.scale_multiplier = 2.0;
    e.set_duration(3.0);
    entity.add_passive_effect(e);
}

Последовательность смерти / возрождения (активный эффект с локальным UI)

Death_Effect :: class : Effect_Base {
    effect_start :: method() {
        player_specific.freeze_player = true;
        player.add_name_invisibility_reason("death");
        player.animator.state_machine.set_trigger("death");
    }

    effect_update :: method(dt: float) {
        time_until_respawn := 5.0 - get_elapsed_time();

        if time_until_respawn <= 0 {
            remove_effect(false);
            return;
        }
    }

    effect_end :: method(interrupt: bool) {
        player.remove_name_invisibility_reason("death");
        respawn_player(player); // пользовательская функция: переместить игрока в точку появления
        player.health.reset();
        player.animator.state_machine.set_trigger("RESET");
    }
}

My_Player :: class : Player_Base {
    ao_late_update :: method(dt: float) {
        if !is_local_or_server() return;

        death, found := entity.get_effect(Death_Effect);
        if !found return;

        time_until_respawn := max(0.0, 5.0 - death.get_elapsed_time());
        ts := UI.default_text_settings();
        ts.size = 64;
        rect := UI.get_screen_rect().bottom_center_rect().offset(0, 150);
        UI.text(rect, ts, "Возрождение через %", {time_until_respawn.(int) + 1});
    }
}

Блокировка катсцены (активный эффект)

Cutscene_Effect :: class : Effect_Base {
    effect_start :: method() {
        player_specific.freeze_player = true;
        set_duration(2.0);
    }
}

Плавные пользовательские визуальные эффекты

Симуляция работает с фиксированной частотой, тогда как рендеринг может идти быстрее. Отрисовка из колбэка компонента автоматически привязывается к сущности этого компонента. В других случаях:

• Оберните отрисовку в мировом пространстве для другой сущности в UI.begin_world_space_ui(entity) и UI.end_world_space_ui().
• Для движущейся позиции, которая не принадлежит сущности, храните постоянный Position_Interpolation_Helper. Передавайте смещение из update(position) в UI.push_interpolation_offset, затем уберите его после отрисовки.
• Используйте постоянный Float_Interpolation_Helper с UI.quad_fill для изменяющегося значения полосы.
• Вызывайте entity.mark_teleported() после резкого изменения позиции.

Smooth_Bar :: class {
    progress: float;
    interpolation: Float_Interpolation_Helper;

    draw :: method(rect: Rect) {
        fill := UI.quad_fill(interpolation.update(progress), .RIGHT);
        UI.quad(rect, core_globals.white_sprite, {0.2, 0.9, 0.3, 1}, params={fill=fill});
    }
}

Храните вспомогательные объекты интерполяции в постоянном состоянии компонента или UI. Вспомогательный объект, созданный внутри метода draw, не имеет предыдущего кадра, от которого можно интерполировать.

Лучшие практики

• Используйте set_active_effect когда эффект на короткое время "владеет" сущностью (рывок/атака/смерть/катсцена).
• Используйте add_passive_effect для накапливаемого состояния (баффы/дебаффы/статусы).
• Используйте set_duration(...) для эффектов с таймером вместо ручных таймеров.
• Всегда восстанавливайте любое изменённое состояние в effect_end (трение, масштаб, триггеры анимации и т. д.).
• Запускайте игровые эффекты в общем предсказанном пути.
• Рисуйте UI, связанный с эффектами, из ao_late_update игрока и защищайте его с помощью is_local_or_server().