Efectos

Los efectos toman temporalmente el control de una entidad para comportamientos complejos como dashes, ataques, animaciones de comer, cinemáticas o secuencias de muerte/reaparición.

Los efectos pueden usarse en jugadores, NPCs o cualquier entidad. Son especialmente útiles cuando quieres:

• Movimiento que controlas en código (dash/retroceso/rodar)

• "Bloquear" la entrada del jugador para una secuencia corta (comer, revivir, cinemática)

• Una ventana temporizada de estado (invencibilidad, lentitud, aturdimiento)

• UI vinculada a un estado temporal (cuenta atrás de reaparecer)

Activos vs. pasivos

All Out admite dos tipos de efectos:

• Efectos activos: uno a la vez por entidad. Establecer un nuevo efecto activo interrumpe el efecto activo actual.

• Efectos pasivos: varios pueden adjuntarse a la vez (buffs/debuffs/efectos de estado apilables).

Un efecto activo también se inserta en la lista de efectos de la entidad, así que aparece en effect_iterator igual que los efectos pasivos.

Inicio rápido (un efecto temporizado simple)

Crea una clase que herede de Effect_Base, y luego adjúntala a una entidad.

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); // se elimina automáticamente después de 0,4 s
    }

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

        // Aumentar la escala y luego encoger hasta desaparecer
        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);

        // Flotar ligeramente hacia arriba
        rise := Ease.out_quad(t) * 0.5;
        entity.set_local_position({start_pos.x, start_pos.y + rise});

        // Desvanecer cerca del final
        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) {
        // Limpiar al terminar (o al interrumpirse)
        entity.destroy();
    }
}

Adjuntarlo como un efecto activo:

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

Ciclo de vida del efecto

Los efectos se basan en callbacks. Implementa solo lo que necesites:

• effect_start(): se llama una vez cuando se adjunta el efecto

• effect_update(dt): se llama en cada fotograma

• effect_late_update(dt): se llama en cada fotograma después de effect_update

• effect_draw(dt): dibujo solo cosmético en fotogramas renderizables

• effect_end(interrupt): se llama cuando se elimina el efecto

effect_draw incluye a los jugadores y omite la resimulación. La UI interactiva debe usar effect_update/effect_late_update, nunca effect_draw.

Efectos activos (control exclusivo)

Usa set_active_effect para efectos que deben ser mutuamente excluyentes (dash, preparación de ataque, secuencia de muerte).

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

Si la entidad ya tiene un efecto activo, este termina con interrupt = true.

Efectos pasivos (buffs/estado apilables)

Usa add_passive_effect para efectos que pueden apilarse (lentitud, veneno, escudo, ventana de invencibilidad).

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

Referencia de API

Effect_Base

Effect_Base :: class {
    entity: Entity;
    player: Player; // null si este efecto no se añadió a un jugador!

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

    // Callbacks opcionales
    #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_draw        :: proc(c: Effect_Base, dt: float);
    #interface effect_end         :: proc(c: Effect_Base, interrupt: bool);

    // Solo lectura
    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);
}

Aplicar / eliminar efectos

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;

Comprobar / iterar efectos

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;

Después de llamar a remove_effect(...), el efecto se desacopla y deja de estar anclado. Su referencia deja de ser válida. Devuelve de inmediato y no accedas a this de nuevo.

freeze_player vs disable_movement_inputs

• player_specific.freeze_player = true: bloquea por completo la posición del jugador.

• player_specific.disable_movement_inputs = true: ignora la entrada, pero tu efecto aún puede mover al jugador (dash/rodar).

Ambos solo se aplican cuando player != null (es decir, el efecto está en una entidad que tiene un Player componente).

Emotes del jugador

Las emotes del jugador usan un efecto activo integrado. Iniciar otra emote interrumpe la emote actual, mientras que cualquier otro efecto activo impide que se inicie una nueva emote. El movimiento interrumpe las emotes y restaura la capa principal de animación, excepto Emote/T_Pose, que permite movimiento.

Usa motivos de bloqueo cuando la jugabilidad deba impedir temporalmente que la rueda de emotes inicie una emote:

player.add_emote_block_reason("stunned");

// Más tarde, cuando termine la restricción:
player.remove_emote_block_reason("stunned");

Los motivos se cuentan como entradas, así que es importante que las llamadas add/remove coincidan. remove_emote_block_reason elimina una entrada coincidente y devuelve si encontró una. Usa has_emote_block_reason(reason) para consultar un motivo y has_any_emote_block_reason() para consultar si hay alguno activo. También puedes controlar directamente el efecto integrado:

if player.has_any_emote_block_reason() {
    // Al menos un motivo de bloqueo está activo.
}

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

try_trigger_emote devuelve false cuando la animación no está equipada, las emotes están bloqueadas o otro tipo de efecto activo controla al jugador. La rueda normal de emotes usa esta misma ruta.

Ejemplos de efectos

Dash / rodar (efecto activo)

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

Ventana de invencibilidad (efecto pasivo)

Usa un efecto pasivo para representar el estado invencible, y compruébalo en cualquier lugar donde apliques daño.

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

// Ejemplo de puerta de daño:
take_damage :: proc(player: Player, amount: s64) {
    if player.entity.has_effect(Invincible_Effect) {
        return;
    }
    // Asume que tu clase Player tiene un campo de salud.
    player.health.take_damage(amount);
}

2x de tamaño durante unos segundos (efecto pasivo)

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

Secuencia de muerte / reaparecer (efecto activo con UI local)

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); // definido por el usuario: teletransporta al jugador al punto de aparición
        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, "Reapareciendo en %", {time_until_respawn.(int) + 1});
    }
}

Bloqueo de cinemática (efecto activo)

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

Visuales personalizados suaves

La simulación se ejecuta a una tasa fija, mientras que el renderizado puede ir más rápido. Dibujar desde una devolución de llamada de componente se ancla automáticamente a la entidad de ese componente. Para otros casos:

• Envuelve el dibujo en espacio mundial de otra entidad en UI.begin_world_space_ui(entity) y UI.end_world_space_ui().

• Para una posición en movimiento que no pertenece a una entidad, mantén un Position_Interpolation_Helper. Pasa el desplazamiento de update(position) a UI.push_interpolation_offset, y luego elimínalo después de dibujar.

• Usa un Float_Interpolation_Helper con los campos persistente para un valor de barra cambiante. persistente

• Llama a entity.mark_teleported() después de un cambio discontinuo de posición.

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

Mantén los ayudantes de interpolación en un componente persistente o en el estado de la UI. Un ayudante creado dentro del método draw no tiene un fotograma anterior desde el que interpolar.

Buenas prácticas

• Usa set_active_effect cuando el efecto “posee” la entidad durante una secuencia corta (dash/ataque/muerte/cinemática).

• Usa add_passive_effect para estado apilable (buffs/debuffs/estados).

• Usa set_duration(...) para efectos temporizados en lugar de temporizadores manuales.

• Restaura siempre cualquier estado modificado en effect_end (fricción, escala, disparadores de animación, etc.).

• Ejecuta los efectos de jugabilidad en la ruta predicha compartida.

• effect_draw es solo cosmético. Dibuja la UI interactiva del efecto desde la del jugador método ao_late_update en is_local_or_server().