效果

效果会暂时接管实体以实现复杂行为，例如冲刺、攻击、进食动画、过场动画或死亡/重生序列。

效果可用于玩家、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));
        Notifier.notify(player, "低生命值！");
            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;
    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(...), 效果对象将被释放。 立即返回 并且在移除后不要接触 在结构体/类内部。方法有一个隐式的 。

freeze_player 对比 disable_movement_inputs

• player_specific.freeze_player = true: 完全锁定玩家位置。

• player_specific.disable_movement_inputs = true: 忽略输入，但你的效果仍然可以移动玩家（冲刺/翻滚）。

两者仅在 player != null 时适用（即效果作用于具有 Player 组件的实体）。

效果示例

冲刺 / 翻滚（主动效果）

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->player_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.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) {
    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->player_set_trigger("death");
    }

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

        if player->is_local() {
            ts := UI.default_text_settings();
            ts.size = 64;
            rect := UI.get_screen_rect()->bottom_center_rect()->offset(0, 150);
            UI.text(rect, ts, "Respawning in %s", {time_until_respawn.(int) + 1});
        }

        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->player_set_trigger("RESET");
    }
}

过场锁定（主动效果）

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

    effect_late_update :: method(dt: float) {
        if player != null && player->is_local() {
            Notifier.notify("Cutscene...");
        }
    }
}

最佳实践

• 使用 set_active_effect 当效果在短序列内“拥有”实体时（冲刺/攻击/死亡/过场）。

• 使用 add_passive_effect 用于可叠加的状态（增益/减益/状态）。

• 使用 set_duration(...) 用于定时效果而不是手动计时器。

• 始终在 effect_end 中恢复任何被修改的状态（摩擦、缩放、动画触发等）。

• 保持 纯粹装饰性的 本地 UI/效果（包装在 player->is_local()）内，并保持游戏玩法状态由服务器为权威。