overlord_event_system/mechanics/

fight.rs

//! Native Rust fight logic.
//!
//! These are the pure-Rust fight primitives (`attack`, `try_cast`,
//! `spawn_wave`, ...) used by the native combat ports in
//! [`crate::behaviors`]. Results are emitted through the [`FightSink`]
//! abstraction and effect reactions through the [`EffectCb`] abstraction; the
//! shipped reactions live in [`crate::mechanics::effect_cb::OverlordEffectCb`].
//!

use std::sync::Arc;

use configs::game_config::GameConfig;
use essences::abilities::Ability;
use essences::entity::{Coordinates, Entity, EntityAttributes};
use essences::fighting::{ActiveFight, EntityTeam};
use event_system::script::random::GameRng;
use uuid::Uuid;

use crate::event::CustomEventData;
use crate::event::*;
use crate::game_config_helpers::GameConfigLookup;
use crate::mechanics::balance;
use crate::mechanics::content_lookups::{ContentLookups, EffectTpl};
use crate::state::OverlordState;

const BATTLEFIELD_HEIGHT: i64 = 3;
const DOT_EFFECT_ID: &str = "019589cb-7adf-7466-8c46-92ac45032880";
const HOT_EFFECT_ID: &str = "01958c0a-329e-744d-a5eb-0369e3f4c024";
const REGEN_EFFECT_ID: &str = "01978d0c-5a8a-7b50-aaa8-e4cd7782f8bc";
/// Effect applied to the player below `LOW_CHAPTER_EFFECT_MAX_CHAPTER`.
const LOW_CHAPTER_EFFECT_ID: &str = "019e27f4-f16b-7881-87cf-bc55605cb80b";
/// Inclusive chapter ceiling for applying `LOW_CHAPTER_EFFECT_ID`.
/// Matches `init_fight` in fight.yaml (raised from 10 to 16 in OVT-2405).
const LOW_CHAPTER_EFFECT_MAX_CHAPTER: i64 = 16;
const SLEEP_EFFECT_ID: &str = "0198f78c-70d9-7962-b34d-4222f5afa6a4";
const DUNGEON_TALENT_ID: &str = "019d1c47-5a66-76e5-bb18-6d115e5c6942";
const BOSS_TALENT_ID: &str = "019d1c47-8cc2-7136-b95b-68e15d7efd0c";
const COUNTERATTACK_PROJECTILE: &str = "019aeeed-5bcc-7dcc-a74f-589031a6b8f2";

// ---------------------------------------------------------------------------
// Output sink — abstracts how a fight method emits its results.
// ---------------------------------------------------------------------------

/// Where a fight method emits its results.
pub trait FightSink {
    fn push_event(&mut self, event: OverlordEvent) -> Result<(), anyhow::Error>;
    fn push_attack(&mut self, delay: u64, duration: u64, target: Uuid)
    -> Result<(), anyhow::Error>;
    fn push_run(&mut self, coords: Coordinates, duration: u64) -> Result<(), anyhow::Error>;
}

/// Sink that collects fight results as typed values for native callers. Mirrors
/// `start_behavior`s fill `casts`.
#[derive(Default)]
pub struct NativeSink {
    pub events: Vec<OverlordEvent>,
    pub casts: Vec<crate::behaviors::combat::start_cast::StartCastAbilityScriptResult>,
}

impl FightSink for NativeSink {
    fn push_event(&mut self, event: OverlordEvent) -> Result<(), anyhow::Error> {
        self.events.push(event);
        Ok(())
    }

    fn push_attack(
        &mut self,
        delay: u64,
        duration: u64,
        target: Uuid,
    ) -> Result<(), anyhow::Error> {
        self.casts.push(
            crate::behaviors::combat::start_cast::StartCastAbilityScriptResult {
                delay_ticks: Some(delay),
                animation_duration_ticks: Some(duration),
                target_entity_id: Some(target),
                ..Default::default()
            },
        );
        Ok(())
    }

    fn push_run(&mut self, coords: Coordinates, duration: u64) -> Result<(), anyhow::Error> {
        self.casts.push(
            crate::behaviors::combat::start_cast::StartCastAbilityScriptResult {
                coordinates: Some(coords),
                run_duration_ticks: Some(duration),
                ..Default::default()
            },
        );
        Ok(())
    }
}

/// Generic event push: converts any `EventStruct<OverlordEvent>` to the enum and
/// emits it through the sink.
fn push_event<ES>(sink: &mut dyn FightSink, event: ES) -> Result<(), anyhow::Error>
where
    ES: event_system::event::EventStruct<OverlordEvent> + 'static,
{
    sink.push_event(event.to_enum())
}

// ---------------------------------------------------------------------------
// Effect callbacks.
//
// Effect reactions (`on_apply` / `on_change`) are abstracted behind this trait
// so the native fns call `effects.on_apply(...)` without knowing the concrete
// dispatcher. The shipped reactions are native, keyed by effect `code`, in
// [`crate::mechanics::effect_cb::OverlordEffectCb`]. Callers that don't
// want reactions pass [`NoopEffectCb`].
// ---------------------------------------------------------------------------

/// Invokes an effect's `on_apply` / `on_change` reaction.
pub trait EffectCb {
    /// Called after an effect's duration is (re)applied, when the effect has an
    /// `on_apply` reaction.
    fn on_apply(
        &mut self,
        sink: &mut dyn FightSink,
        effect: &EffectTpl,
        target: &Entity,
    ) -> Result<(), anyhow::Error>;

    /// Called when an effect's stack count changes, when the effect has an
    /// `on_change` reaction.
    fn on_change(
        &mut self,
        sink: &mut dyn FightSink,
        effect: &EffectTpl,
        target: &Entity,
        new_stacks: i64,
        old_stacks: i64,
    ) -> Result<(), anyhow::Error>;
}

/// Effect callback that does nothing — for callers that don't want effect
/// reactions dispatched.
pub struct NoopEffectCb;

impl EffectCb for NoopEffectCb {
    fn on_apply(
        &mut self,
        _sink: &mut dyn FightSink,
        _effect: &EffectTpl,
        _target: &Entity,
    ) -> Result<(), anyhow::Error> {
        Ok(())
    }

    fn on_change(
        &mut self,
        _sink: &mut dyn FightSink,
        _effect: &EffectTpl,
        _target: &Entity,
        _new_stacks: i64,
        _old_stacks: i64,
    ) -> Result<(), anyhow::Error> {
        Ok(())
    }
}

// ---------------------------------------------------------------------------
// Attribute helpers
// ---------------------------------------------------------------------------

fn attr_get(entity: &Entity, attr_code: &str) -> f64 {
    entity.attributes.0.get(attr_code).copied().unwrap_or(0) as f64
}

fn attr_present(entity: &Entity, attr_code: &str) -> bool {
    entity.attributes.0.contains_key(attr_code)
}

/// Push an `EntityIncrAttribute` event. Rounds f64 deltas to the nearest int.
fn incr_attr(
    sink: &mut dyn FightSink,
    entity_id: Uuid,
    attr: &str,
    delta: i64,
) -> Result<(), anyhow::Error> {
    push_event(
        sink,
        OverlordEventEntityIncrAttribute {
            entity_id,
            attribute: attr.to_string(),
            delta,
        },
    )
}

/// `ctx.get_entity_stat(entity, "armor")` — applies attribute base value (from
/// content_raw), additive `bonus`, and multiplicative `mod` (`+10000 == +1.0`).
pub fn get_entity_stat(lookups: &ContentLookups, entity: &Entity, stat_code: &str) -> f64 {
    let mut stat = attr_get(entity, stat_code);
    if let Some(attr_id) = lookups.attribute_by_code.get(stat_code)
        && let Some(base) = lookups.attribute_base_value.get(attr_id)
    {
        stat += base;
    }
    let bonus = attr_get(entity, &format!("{stat_code}.bonus"));
    // Balance v2: floor the `.mod` multiplier so a stacking debuff (weakness on
    // attack, protection on received_damage, …) can't drive a stat to ≤0
    // (zero-damage / unkillable). Only bites at mod ≤ −9500; buffs unaffected.
    let mod_v = (attr_get(entity, &format!("{stat_code}.mod")) / 10000.0 + 1.0)
        .max(balance::MIN_STAT_MOD_MULT);
    (stat + bonus) * mod_v
}

/// True iff `stat_code` resolves to a promoted base value in
/// `attribute_base_value`. Lets combat tell a genuine "base missing" content
/// regression (the whole `attribute_base_value` lookup empty — see
/// `content_raw_extract`) apart from a stat that merely composed low via mods.
fn has_attribute_base(lookups: &ContentLookups, stat_code: &str) -> bool {
    lookups
        .attribute_by_code
        .get(stat_code)
        .is_some_and(|id| lookups.attribute_base_value.contains_key(id))
}

pub fn stat_throw(
    random: &GameRng,
    lookups: &ContentLookups,
    entity: &Entity,
    stat_code: &str,
    bonus: f64,
) -> bool {
    let stat_value = get_entity_stat(lookups, entity, stat_code) + bonus;
    if stat_value > 0.0 {
        let success = stat_value / 10000.0;
        return random.random_f64() < success;
    }
    false
}

// ---------------------------------------------------------------------------
// Entity geometry / target selection
// ---------------------------------------------------------------------------

/// True when a mover of `width` can place its front on `c` without overlapping
/// any other entity's current cell or reserved `move_target`. The body extends
/// behind the front (left for +x movers, right for -x). `mover_id` is skipped.
fn cell_exists_and_free(
    c: &Coordinates,
    entities: &[Entity],
    mover_id: Uuid,
    width: i64,
    direction: i64,
) -> bool {
    if c.y < 0 || c.y >= BATTLEFIELD_HEIGHT {
        return false;
    }
    let w = width.max(1);
    // The cells the mover's body covers with its front at `c`, on row `c.y`.
    let (lo, hi) = if direction >= 0 {
        (c.x - (w - 1), c.x)
    } else {
        (c.x, c.x + (w - 1))
    };
    let covers = |p: &Coordinates| p.y == c.y && p.x >= lo && p.x <= hi;
    for entity in entities {
        if entity.id == mover_id {
            continue;
        }
        if covers(&entity.coordinates) {
            return false;
        }
        if let Some(target) = &entity.move_target
            && covers(target)
        {
            return false;
        }
    }
    true
}

fn entity_get_tpl_width(config: &GameConfig, entity: &Entity) -> i64 {
    if let Some(tpl_id) = entity.entity_template_id
        && let Some(tpl) = config.entity_template(tpl_id)
    {
        return tpl.width as i64;
    }
    1
}

fn entity_get_tpl_cast_time(config: &GameConfig, entity: &Entity) -> i64 {
    if let Some(tpl_id) = entity.entity_template_id
        && let Some(tpl) = config.entity_template(tpl_id)
    {
        return tpl.cast_time as i64;
    }
    if let Some(class_id) = entity.class_id
        && let Some(class) = config.class(class_id)
    {
        return class.cast_time as i64;
    }
    0
}

fn find_advance_coordinates(
    entity: &Entity,
    entities: &[Entity],
    config: &GameConfig,
) -> Option<Coordinates> {
    let pos = &entity.coordinates;
    let width = entity_get_tpl_width(config, entity);
    let direction: i64 = if entity.team == EntityTeam::Ally {
        1
    } else {
        -1
    };
    let x = pos.x + direction;

    let cell_up = Coordinates { x, y: pos.y + 1 };
    let cell_forward = Coordinates { x, y: pos.y };
    let cell_down = Coordinates { x, y: pos.y - 1 };

    let mid = (BATTLEFIELD_HEIGHT - 1) / 2;
    let order: [&Coordinates; 3] = if pos.y > mid {
        [&cell_up, &cell_forward, &cell_down]
    } else if pos.y < mid {
        [&cell_down, &cell_forward, &cell_up]
    } else {
        [&cell_forward, &cell_up, &cell_down]
    };

    for c in order {
        if cell_exists_and_free(c, entities, entity.id, width, direction) {
            return Some(c.clone());
        }
    }
    None
}

fn get_distance_to(a: &Entity, b: &Entity) -> i64 {
    (b.coordinates.x - a.coordinates.x).abs()
}

fn get_target_with_lowest_hp(targets: &[Entity]) -> Option<&Entity> {
    targets.iter().min_by_key(|e| e.hp)
}

fn get_closest_target<'a>(caster: &Entity, targets: &'a [Entity]) -> Option<&'a Entity> {
    targets.iter().min_by_key(|t| {
        (t.coordinates.x - caster.coordinates.x).abs()
            + (t.coordinates.y - caster.coordinates.y).abs()
    })
}

fn get_target<'a>(caster: &Entity, targets: &'a [Entity]) -> Option<&'a Entity> {
    if caster.entity_template_id.is_some() {
        get_closest_target(caster, targets)
    } else {
        get_target_with_lowest_hp(targets)
    }
}

// ---------------------------------------------------------------------------
// Top-level fight methods
// ---------------------------------------------------------------------------

/// Native: `ctx.add_entity_attr(entity, attr, value)` — push an `IncrAttribute`
pub fn add_entity_attr(
    sink: &mut dyn FightSink,
    entity: &Entity,
    attr_code: &str,
    value: i64,
) -> Result<(), anyhow::Error> {
    incr_attr(sink, entity.id, attr_code, value)
}

/// Native: `ctx.add_entity_stat_mod(entity, stat, value)` — push an
/// `IncrAttribute` on `"{stat}.mod"` by `value`. Mirrors the engine's
/// `add_entity_stat_mod` (which lowers to `add_entity_attr(entity, "{stat}.mod",
/// value)`); used by the native effect-callback dispatcher to replicate the
pub fn add_entity_stat_mod(
    sink: &mut dyn FightSink,
    entity: &Entity,
    stat: &str,
    value: i64,
) -> Result<(), anyhow::Error> {
    add_entity_attr(sink, entity, &format!("{stat}.mod"), value)
}

/// Native: `ctx.set_entity_attr(entity, attr, value)` — push an `IncrAttribute`
/// that moves the attr TO `value` (delta = `round(value - current)`). Emitted
pub fn set_entity_attr(
    sink: &mut dyn FightSink,
    entity: &Entity,
    attr_code: &str,
    value: f64,
) -> Result<(), anyhow::Error> {
    let current = attr_get(entity, attr_code);
    incr_attr(sink, entity.id, attr_code, (value - current).round() as i64)
}

/// Native: returns whether `target` is touched (i.e. did NOT evade). Balance
/// v2: dodge probability follows the DR curve `ev/(ev+K_DODGE)` (asymptote
/// < 100%, no 100%-dodge cliff) instead of the old linear `ev/10000`. Consumes
/// exactly one `rng` draw iff the target has positive evasion rating — matching
/// the old `stat_throw`'s "draw only when stat > 0" so draw-count is preserved.
pub fn touch_enemy(rng: &GameRng, lookups: &ContentLookups, target: &Entity) -> bool {
    let evasion = get_entity_stat(lookups, target, "evasion");
    if evasion <= 0.0 {
        return true;
    }
    let dodge = evasion / (evasion + balance::tuning().k_dodge);
    // touched ⇔ not dodged ⇔ roll ≥ dodge (one draw, matching the old throw).
    rng.random_f64() >= dodge
}

/// Native: emit a `screen_shake` visual event.
pub fn screen_shake(sink: &mut dyn FightSink, power: i64) -> Result<(), anyhow::Error> {
    let mut data = CustomEventData::default();
    data.add("screen_shake_power", power);
    push_event(
        sink,
        OverlordEventFightVisualEvent {
            effect_type: "screen_shake".to_string(),
            effect_data: data,
        },
    )
}

/// Native: heal `entity`, capping at its missing HP. Returns the applied heal
/// (`None` if no heal was applied).
pub fn heal_entity(
    sink: &mut dyn FightSink,
    entity: &Entity,
    amount: f64,
) -> Result<Option<i64>, anyhow::Error> {
    let max_heal = entity.max_hp as i64 - entity.hp as i64;
    let heal = max_heal.min(amount.floor() as i64);
    if heal <= 0 {
        return Ok(None);
    }
    push_event(
        sink,
        OverlordEventHeal {
            entity_id: entity.id,
            heal: heal as u64,
        },
    )?;
    Ok(Some(heal))
}

/// Native: apply `raw_dmg` to `entity` (armor, shield, block roll, received
/// damage multiplier). Returns the floored post-mitigation damage value; `None`
/// only for the no-damage early-outs (`godmode` / a missing `received_damage`
/// base value — a content-extraction regression), which short-circuit before
/// the block roll. When a shield fully absorbs the
/// hit the function still returns `Some(floored_damage)` (and emits the shield
/// decrement) — this value drives `attack`'s return / lifesteal, so it
/// must not be `None` or the caller would discard the shield event.
/// Consumes one `block` `stat_throw` from `rng` when it is reached.
pub fn damage_entity(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    lookups: &ContentLookups,
    entity: &Entity,
    raw_dmg: f64,
    mut custom_data: CustomEventData,
) -> Result<Option<i64>, anyhow::Error> {
    if attr_present(entity, "godmode") {
        return Ok(None);
    }
    let armor = get_entity_stat(lookups, entity, "armor");
    let shield = attr_get(entity, "shield");
    // `received_damage` is a ×10000 multiplier whose base value (10000 == 100%
    // taken) lives in `attribute_base_value`. If that lookup is *entirely absent*
    // the content pipeline failed to promote it (see `content_raw_extract`) —
    // keep the loud legacy behaviour (cancel all damage → fights visibly stall)
    // so a content/extraction regression still surfaces, instead of silently
    // degrading to the floor below (~1% damage, a 100×-slower near-stalemate).
    if !has_attribute_base(lookups, "received_damage") {
        return Ok(None);
    }
    // Balance v2: with the base present, floor received-damage at a small
    // positive instead of treating `≤0` as full invuln — a negative
    // `received_damage.mod` (e.g. stacked `protection`, −50%/stack) would
    // otherwise cancel ALL damage forever and make the entity unkillable.
    // `godmode` above remains the only true invuln.
    let mut received_damage_k =
        get_entity_stat(lookups, entity, "received_damage").max(balance::MIN_RECEIVED_DAMAGE_K);

    if stat_throw(rng, lookups, entity, "block", 0.0) {
        received_damage_k *= 0.5;
        custom_data.add("block", 1);
    }

    let dmg_k = balance::armor_k(armor) * received_damage_k / 10000.0;
    let dmg = raw_dmg * dmg_k;
    let res = dmg.floor() as i64;
    if shield == 0.0 {
        push_event(
            sink,
            OverlordEventDamage {
                entity_id: entity.id,
                damage: res.max(0) as u64,
                damage_data: custom_data,
            },
        )?;
    } else if dmg > shield {
        incr_attr(sink, entity.id, "shield", -(shield as i64))?;
        let dmg_hp = (dmg - shield).floor() as i64;
        custom_data.add("shield_damage", shield as i64);
        push_event(
            sink,
            OverlordEventDamage {
                entity_id: entity.id,
                damage: dmg_hp.max(0) as u64,
                damage_data: custom_data,
            },
        )?;
    } else {
        incr_attr(sink, entity.id, "shield", -(dmg.round() as i64))?;
    }
    Ok(Some(res))
}

/// Typed form of the `attack` params.
#[derive(Clone, Debug, Default)]
pub struct AttackParams {
    pub no_counterattack: bool,
    pub crit_chance_bonus: f64,
    /// Forced crit value; `None` => roll `crit_chance`.
    pub is_crit: Option<bool>,
    pub power: Option<f64>,
    pub dot_power: Option<f64>,
}

impl AttackParams {
    /// The default `attack(caster, target)` overload uses `power = 1.0`.
    pub fn default_power() -> Self {
        Self {
            power: Some(1.0),
            ..Default::default()
        }
    }
}

/// Native: perform an attack from `caster` on `target`. Returns the floored
/// damage dealt (`None` => the no-damage paths: evasion, or no `power` given).
/// RNG is consumed in the exact original order: evasion, counterattack_chance,
/// deceit (+ `randint(0,2)` if it lands), crit_chance, then `damage_entity`'s
/// block roll.
#[allow(clippy::too_many_arguments)]
pub fn attack(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    player_id: Uuid,
    caster: &Entity,
    target: &Entity,
    params: &AttackParams,
) -> Result<Option<i64>, anyhow::Error> {
    if !touch_enemy(rng, lookups, target) {
        push_event(
            sink,
            OverlordEventEvasion {
                entity_id: target.id,
            },
        )?;
        return Ok(None);
    }
    if !params.no_counterattack && stat_throw(rng, lookups, target, "counterattack_chance", 0.0) {
        push_event(
            sink,
            OverlordEventCounterAttack {
                by_entity_id: target.id,
                to_entity_id: caster.id,
                duration_ticks: 200,
            },
        )?;
        push_event(
            sink,
            OverlordEventStartCastProjectile {
                by_entity_id: target.id,
                to_entity_id: caster.id,
                projectile_id: Uuid::parse_str(COUNTERATTACK_PROJECTILE).unwrap(),
                level: 1,
                delay: 0,
            },
        )?;
    }

    if stat_throw(rng, lookups, caster, "deceit", 0.0) {
        let pool = ["vulnerability", "weakness"];
        let idx = rng.random_index(pool.len());
        let code = pool[idx];
        change_entity_effect_duration(
            sink,
            lookups,
            effects,
            target,
            code,
            (balance::DECEIT_DEBUFF_DURATION * 1000.0).floor() as i64,
        )?;
    }

    let attack = get_entity_stat(lookups, caster, "attack");

    let mut dmg_mod = 1.0;
    let is_crit = match params.is_crit {
        Some(v) => v,
        None => stat_throw(
            rng,
            lookups,
            caster,
            "crit_chance",
            params.crit_chance_bonus,
        ),
    };
    if is_crit {
        dmg_mod = 2.0 + get_entity_stat(lookups, caster, "crit_modifier") / 10000.0;
    }

    // Balance v2 (Phase 5): soft 3-cycle class counter — ±swing when the
    // caster's class beats/loses to the target's. 1.0 for PvE (classless mob)
    // or same/neutral class, so this is PvP-only by construction.
    let counter = balance::class_counter_multiplier(lookups, caster.class_id, target.class_id);

    let mut dmg_dealt = None;
    if let Some(power) = params.power {
        let dmg = attack * power * dmg_mod * counter;
        let mut data = CustomEventData::default();
        if is_crit {
            data.add("crit", 1);
        }
        dmg_dealt = damage_entity(sink, rng, lookups, target, dmg * balance::DMG_K, data)?;
    }
    if let Some(dot_power) = params.dot_power {
        apply_entity_over_time_effect(
            sink,
            target,
            attack * dot_power * dmg_mod * counter * balance::DMG_K,
            "dot",
        )?;
    }

    if caster.id == player_id {
        let power = params.power.unwrap_or(0.0);
        if is_crit || power > 3.5 {
            let _ = screen_shake(sink, 25);
        }
    }
    Ok(dmg_dealt)
}

/// Typed form of the `spell_heal` params.
#[derive(Clone, Debug, Default)]
pub struct SpellHealParams {
    pub is_crit: Option<bool>,
    pub power: Option<f64>,
    pub hot_power: Option<f64>,
}

impl SpellHealParams {
    pub fn default_power() -> Self {
        Self {
            power: Some(1.0),
            ..Default::default()
        }
    }
}

/// Native: heal `target` from `caster`'s attack stat. Returns the applied heal
/// (`None` when no heal). Consumes `crit_chance` from `rng` (unless `is_crit` is
/// forced), then `heal_entity`'s path (no RNG).
pub fn spell_heal(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    lookups: &ContentLookups,
    caster: &Entity,
    target: &Entity,
    params: &SpellHealParams,
) -> Result<Option<i64>, anyhow::Error> {
    let attack = get_entity_stat(lookups, caster, "attack");
    let mut heal_mod = 1.0;
    let is_crit = match params.is_crit {
        Some(v) => v,
        None => stat_throw(rng, lookups, caster, "crit_chance", 0.0),
    };
    if is_crit {
        heal_mod = 2.0 + get_entity_stat(lookups, caster, "crit_modifier") / 10000.0;
    }
    let mut heal_event = None;
    if let Some(power) = params.power {
        heal_event = heal_entity(sink, target, attack * power * heal_mod * balance::DMG_K)?;
    }
    if let Some(hot_power) = params.hot_power {
        apply_entity_over_time_effect(
            sink,
            target,
            attack * hot_power * heal_mod * balance::DMG_K,
            "hot",
        )?;
    }
    Ok(heal_event)
}

/// Native: apply `effect_code` to `target` for `duration_seconds` (converted to
/// ticks). Effect `on_apply` reactions are dispatched through `effects`.
pub fn apply_entity_effect(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    target: &Entity,
    effect_code: &str,
    duration_seconds: f64,
) -> Result<(), anyhow::Error> {
    change_entity_effect_duration(
        sink,
        lookups,
        effects,
        target,
        effect_code,
        (duration_seconds * 1000.0).floor() as i64,
    )
}

/// Native: add `duration` ticks of `effect_code` to `target` (capped at the
/// effect's `max_duration_ticks`), emitting `EntityApplyEffect` on first
/// application and dispatching the effect's `on_apply` reaction.
pub fn change_entity_effect_duration(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    target: &Entity,
    effect_code: &str,
    duration: i64,
) -> Result<(), anyhow::Error> {
    let effect_tpl: Arc<EffectTpl> = match lookups.effects_by_code.get(effect_code) {
        Some(t) => t.clone(),
        None => {
            return Err(anyhow::anyhow!(
                "apply_entity_effect: unknown effect code {effect_code}"
            ));
        }
    };

    let duration_attr = format!("effect.{effect_code}.duration");
    let current_duration_ticks = attr_get(target, &duration_attr) as i64;
    let max_duration = effect_tpl.max_duration_ticks.unwrap_or(5000);
    let new_duration = (current_duration_ticks + duration).min(max_duration);
    incr_attr(
        sink,
        target.id,
        &duration_attr,
        new_duration - current_duration_ticks,
    )?;
    if current_duration_ticks == 0 {
        push_event(
            sink,
            OverlordEventEntityApplyEffect {
                entity_id: target.id,
                effect_id: effect_tpl.id,
            },
        )?;
    }
    effects.on_apply(sink, &effect_tpl, target)?;
    Ok(())
}

/// Native: apply a damage-/heal-over-time effect (`kind` = `"dot"` / `"hot"`),
/// splitting `amount` over 5 ticks. No effect callbacks, no RNG.
pub fn apply_entity_over_time_effect(
    sink: &mut dyn FightSink,
    target: &Entity,
    amount: f64,
    kind: &str,
) -> Result<(), anyhow::Error> {
    let effect_id = if kind == "dot" {
        Uuid::parse_str(DOT_EFFECT_ID).unwrap()
    } else {
        Uuid::parse_str(HOT_EFFECT_ID).unwrap()
    };
    let per_tick = (amount / 5.0).floor() as i64;
    for i in 1..=5 {
        let tick_attr = format!("effect.{kind}.tick.{i}");
        incr_attr(sink, target.id, &tick_attr, per_tick)?;
    }
    let next_attr = format!("effect.{kind}.next");
    if !attr_present(target, &next_attr) {
        // set to 1 (current is 0)
        incr_attr(sink, target.id, &next_attr, 1)?;
        push_event(
            sink,
            OverlordEventEntityApplyEffect {
                entity_id: target.id,
                effect_id,
            },
        )?;
    }
    Ok(())
}

/// Native: remove all stacks of `effect_code` from `target`, dispatching the
/// effect's `on_change` reaction with `(new_stacks=0, old_stacks=current)`.
pub fn remove_entity_effect(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    target: &Entity,
    effect_code: &str,
) -> Result<(), anyhow::Error> {
    let effect_tpl: Arc<EffectTpl> = match lookups.effects_by_code.get(effect_code) {
        Some(t) => t.clone(),
        None => {
            return Err(anyhow::anyhow!(
                "remove_entity_effect: unknown effect code {effect_code}"
            ));
        }
    };
    let stacks_attr = format!("effect.{effect_code}.stacks");
    let current_stacks = attr_get(target, &stacks_attr) as i64;
    incr_attr(sink, target.id, &stacks_attr, -current_stacks)?;
    effects.on_change(sink, &effect_tpl, target, 0, current_stacks)?;
    Ok(())
}

/// Native: emit the per-entity init events for a fight (regen effect, low-chapter
/// effect, party power adjustment, dungeon/boss talent attack mods). No RNG, no
/// effect callbacks. `fight` supplies player/party ids + the entity roster +
/// `party_adjusted_power`; reads talent levels / chapter from `state`.
#[allow(clippy::too_many_arguments)]
pub fn init_fight(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    fight: &ActiveFight,
    state: &OverlordState,
    fight_template_id: Uuid,
) -> Result<(), anyhow::Error> {
    let is_dungeon = lookups
        .fight_template_is_dungeon
        .get(&fight_template_id)
        .copied()
        .unwrap_or(false);
    let is_bossfight = lookups
        .fight_template_is_bossfight
        .get(&fight_template_id)
        .copied()
        .unwrap_or(false);

    let player_id = fight.player_id;
    let party_player_id = fight.party_player_id;
    let entities = fight.entities.clone();
    let regen_effect = Uuid::parse_str(REGEN_EFFECT_ID).unwrap();
    let low_chapter_effect = Uuid::parse_str(LOW_CHAPTER_EFFECT_ID).unwrap();
    let dungeon_talent = Uuid::parse_str(DUNGEON_TALENT_ID).unwrap();
    let boss_talent = Uuid::parse_str(BOSS_TALENT_ID).unwrap();

    for entity in &entities {
        if attr_present(entity, "regeneration_rate") {
            push_event(
                sink,
                OverlordEventEntityApplyEffect {
                    entity_id: entity.id,
                    effect_id: regen_effect,
                },
            )?;
        }

        let mut dungeon_level: Option<i64> = None;
        let mut boss_level: Option<i64> = None;

        if entity.id == player_id {
            dungeon_level = state
                .character_state
                .talent_levels
                .get(&dungeon_talent)
                .copied();
            boss_level = state
                .character_state
                .talent_levels
                .get(&boss_talent)
                .copied();
            if state.character_state.character.current_chapter_level
                <= LOW_CHAPTER_EFFECT_MAX_CHAPTER
            {
                push_event(
                    sink,
                    OverlordEventEntityApplyEffect {
                        entity_id: entity.id,
                        effect_id: low_chapter_effect,
                    },
                )?;
            }
        }
        if Some(entity.id) == party_player_id {
            let party = &state.party;
            if let Some(party_state) = &party.party_state {
                dungeon_level = party_state.talent_levels.get(&dungeon_talent).copied();
                boss_level = party_state.talent_levels.get(&boss_talent).copied();
                if let Some(adjusted) = party.party_adjusted_power {
                    let raw = party_state.character.power as f64;
                    if raw > 0.0 {
                        let adjust_k = adjusted as f64 / raw;
                        let stat_k = adjust_k.sqrt();
                        let current_attack = attr_get(entity, "attack");
                        let delta =
                            (current_attack * stat_k).floor() as i64 - current_attack as i64;
                        incr_attr(sink, entity.id, "attack", delta)?;
                        let new_max_hp = ((entity.hp as f64) * stat_k).floor() as u64;
                        push_event(
                            sink,
                            OverlordEventSetMaxHp {
                                entity_id: entity.id,
                                new_max_hp,
                                new_hp: new_max_hp,
                            },
                        )?;
                    }
                }
            }
        }

        if is_dungeon && let Some(level) = dungeon_level {
            let current = attr_get(entity, "attack.mod") as i64;
            incr_attr(sink, entity.id, "attack.mod", 200 * level - current)?;
        }
        if is_bossfight {
            // Boss fights scale `attack.mod` by the player's BOSS talent level.
            // talent being present while reading the boss talent level;
            // corrected here to gate on the boss talent itself.)
            if let Some(level) = boss_level {
                let current = attr_get(entity, "attack.mod") as i64;
                incr_attr(sink, entity.id, "attack.mod", 200 * level - current)?;
            }
        }
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// spawn_wave & simulated_wave helpers
// ---------------------------------------------------------------------------

/// Typed form of the `fight_data` prepare-fight blob fed to `spawn_wave`.
#[derive(Clone, Debug, Default, PartialEq, serde::Serialize)]
pub struct WaveFightData {
    /// `entities[].{ entity_id, power }` — the per-template relative powers.
    pub entities: Vec<WaveEntityPower>,
    /// `waves[][].{ data: { entity_id, delay }, position }`.
    pub waves: Vec<Vec<WaveSpawn>>,
    /// `time` — the fight time budget used to normalise mob HP.
    pub time: f64,
    /// The per-fight reference power (`base_power` for `spawn_wave`).
    /// `None` mirrors a missing/unconfigured value (treated as 0.0 by callers).
    pub power: Option<f64>,
}

#[derive(Clone, Debug, PartialEq, serde::Serialize)]
pub struct WaveEntityPower {
    /// `None` mirrors an entry with no readable `entity_id`. The original
    /// `min_power` pass ignores `entity_id` entirely (so such an entry can still
    /// lower `min_power`), while the `entity_powers` pass skips it — both
    /// behaviours are preserved by keeping this optional.
    pub entity_id: Option<String>,
    /// `None` mirrors a missing/unreadable `power`. The original `min_power`
    /// pass skips a missing power; the `entity_powers` pass defaults it to 1.0.
    pub power: Option<f64>,
}

#[derive(Clone, Debug, PartialEq, serde::Serialize)]
pub struct WaveSpawn {
    pub entity_id: String,
    /// `delay` (ms). `None` mirrors a missing key (treated as 0.0 in sims, and
    /// the spawn loop reads it as `unwrap_or(0.0) as i64`).
    pub delay: Option<f64>,
    /// `None` mirrors an unreadable `position`. The original only reads the
    /// position in the final spawn loop (current wave), where a missing one is
    /// an error; spawns in other waves never have their position validated, so
    /// this stays optional to preserve that error timing.
    pub position: Option<Coordinates>,
}

#[derive(Clone, Debug)]
struct SimEnemy {
    eff_damage: f64,
    ttk: f64,
    delay: f64,
}

fn sim_wave_choose_next_target(enemies: &[SimEnemy]) -> Option<usize> {
    let mut fastest = 1800.0f64;
    let mut idx = None;
    for (i, e) in enemies.iter().enumerate() {
        if e.delay <= 0.0 && e.ttk < fastest {
            idx = Some(i);
            // Track the lowest time-to-kill among the arrived enemies so we
            // pick the fastest-dying target. (The original legacy script stored
            // `enemy.delay` here — always 0 for arrived enemies — which pinned
            // `fastest` to 0 and made the loop always keep the FIRST arrived
            // enemy regardless of ttk; corrected to `e.ttk`.)
            fastest = e.ttk;
        }
    }
    idx
}

fn sim_wave_choose_sim_time(enemies: &[SimEnemy], current_target: Option<usize>) -> f64 {
    let mut next_step = 1800.0f64;
    for e in enemies {
        if e.delay > 0.0 && e.delay < next_step {
            next_step = e.delay;
        }
    }
    if let Some(idx) = current_target
        && let Some(t) = enemies.get(idx)
        && t.ttk < next_step
    {
        next_step = t.ttk;
    }
    next_step
}

fn sim_wave_advance(enemies: &mut Vec<SimEnemy>, mob_damage: &mut f64) {
    let target = sim_wave_choose_next_target(enemies);
    let time = sim_wave_choose_sim_time(enemies, target);
    if let Some(t) = target {
        // Total per-second damage of the arrived enemies. Matches the shipped
        // legacy `reduce(|sum| sum + this.eff_damage, 0)` script — in that
        // language's array closures `this` binds to the CURRENT ELEMENT, so the
        // original did compute this exact per-enemy sum (the #2046 note calling
        // it broken misread that binding; the code below was already parity).
        let dmg: f64 = enemies
            .iter()
            .filter(|e| e.delay <= 0.0)
            .map(|e| e.eff_damage)
            .sum();
        *mob_damage += dmg * time;
        enemies[t].ttk -= time;
        if enemies[t].ttk <= 0.0 {
            enemies.remove(t);
        }
    }
    for e in enemies.iter_mut() {
        if e.delay > 0.0 {
            e.delay = (e.delay - time).max(0.0);
        }
    }
}

/// Native: the `prepare_fight` interpreter. Computes normalised enemy stats from
/// the chapter power curve + the typed wave blob, then emits spawn events for the
/// current wave. RNG is consumed once per spawned enemy (the spawn-entity uuid),
/// in iteration order — identical to the original. `fight` supplies
/// `current_wave` + the live `entities` (for the multi-wave x-offset).
#[allow(clippy::too_many_arguments)]
pub fn spawn_wave(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    config: &GameConfig,
    lookups: &ContentLookups,
    fight: &ActiveFight,
    fight_data: &WaveFightData,
    base_power: f64,
    current_chapter: i64,
    fight_type: &str,
) -> Result<(), anyhow::Error> {
    const POWER_EFF_HP: f64 = 0.75;
    const POWER_ATTACK: f64 = 1.0 - POWER_EFF_HP;

    // Campaign enemy power follows the geometric curve past the hand-made
    // chapters, via `balance::enemy_power_scalar` — shared with the battle-end
    // analytics so the report stamps exactly what spawned. The `eff` divide below
    // is float (no integer truncation).
    let is_dungeon = lookups
        .fight_template_is_dungeon
        .get(&fight.fight_id)
        .copied()
        .unwrap_or(false);
    let power = balance::enemy_power_scalar(base_power, current_chapter, fight_type, is_dungeon);

    let hp_k = balance::hp_k_for_chapter(config, current_chapter);
    let eff = power / balance::BASE_POWER as f64;
    let mut eff_hp = balance::BASE_HP * (eff * hp_k).powf(0.5);
    let mut eff_attack = balance::BASE_ATTACK * (eff / hp_k).powf(0.5);

    eff_hp *= 2.0_f64.powf(0.5);
    eff_attack /= 2.0_f64.powf(0.5);

    let player_dps = eff_attack * balance::BASE_SPELL_EFF * balance::DMG_K;

    // `min_power` over all readable powers (the original ignored `entity_id`
    // here, so an entry with a power but no id can still lower the minimum).
    let mut min_power: Option<f64> = None;
    for ent in &fight_data.entities {
        if let Some(p) = ent.power {
            min_power = Some(min_power.map(|mp| mp.min(p)).unwrap_or(p));
        }
    }
    let min_power = min_power.unwrap_or(1.0);

    // `entity_powers` keyed by id (entries with no id are skipped); a missing
    // power defaults to 1.0.
    let mut entity_powers: std::collections::HashMap<String, f64> =
        std::collections::HashMap::new();
    for ent in &fight_data.entities {
        let Some(id) = &ent.entity_id else {
            continue;
        };
        let p = ent.power.unwrap_or(1.0);
        entity_powers.insert(id.clone(), p / min_power);
    }

    let mut mobs_eff_hp = 0.0f64;
    for wave in &fight_data.waves {
        for spawn in wave {
            let enemy_power = entity_powers.get(&spawn.entity_id).copied().unwrap_or(1.0);
            mobs_eff_hp += enemy_power.powf(POWER_EFF_HP);
        }
    }

    let time = fight_data.time;
    let player_damage = player_dps * time;
    let mob_hp_norm = if mobs_eff_hp > 0.0 {
        player_damage / mobs_eff_hp
    } else {
        0.0
    };
    let mob_norm_ttk = if player_dps > 0.0 {
        mob_hp_norm / player_dps
    } else {
        0.0
    };

    let mut overall_damage = 0.0f64;
    for wave in &fight_data.waves {
        let mut sim_enemies: Vec<SimEnemy> = Vec::new();
        for spawn in wave {
            let enemy_power = entity_powers.get(&spawn.entity_id).copied().unwrap_or(1.0);
            let delay = spawn.delay.unwrap_or(0.0);
            sim_enemies.push(SimEnemy {
                eff_damage: enemy_power.powf(POWER_ATTACK),
                ttk: mob_norm_ttk * enemy_power.powf(POWER_EFF_HP),
                delay,
            });
        }
        let mut mob_damage = 0.0f64;
        let mut iter = 0;
        while !sim_enemies.is_empty() && iter < 200 {
            iter += 1;
            sim_wave_advance(&mut sim_enemies, &mut mob_damage);
        }
        overall_damage += mob_damage;
    }

    let mob_dps_norm = if overall_damage > 0.0 {
        eff_hp / overall_damage
    } else {
        0.0
    };
    let mob_attack_norm = mob_dps_norm / balance::BASE_SPELL_EFF / balance::DMG_K;

    let wave_idx = (fight.current_wave - 1) as usize;
    let mut offset_x = 0i64;
    if wave_idx > 0 {
        let mut max_ally_x: Option<i64> = None;
        for e in &fight.entities {
            if e.team == EntityTeam::Ally && e.hp > 0 {
                max_ally_x = Some(
                    max_ally_x
                        .map(|m| m.max(e.coordinates.x))
                        .unwrap_or(e.coordinates.x),
                );
            }
        }
        if let Some(m) = max_ally_x {
            offset_x = m - 1 + 6;
        }
    }

    let Some(current_wave) = fight_data.waves.get(wave_idx) else {
        return Ok(());
    };

    for spawn in current_wave {
        let enemy_tpl_id = match Uuid::parse_str(&spawn.entity_id) {
            Ok(u) => u,
            Err(_) => continue,
        };
        let enemy_power = entity_powers.get(&spawn.entity_id).copied().unwrap_or(1.0);
        let enemy_hp_norm = enemy_power.powf(POWER_EFF_HP);
        let enemy_attack_norm = enemy_power.powf(POWER_ATTACK);
        let enemy_hp = enemy_hp_norm * mob_hp_norm;
        let enemy_attack = enemy_attack_norm * mob_attack_norm;
        let delay = spawn.delay.unwrap_or(0.0) as i64;

        let mut attrs = EntityAttributes::default();
        attrs.add("attack", enemy_attack.floor() as i64);
        attrs.add("hp", enemy_hp.floor() as i64);
        attrs.add("speed", 10000);
        if delay > 0 {
            attrs.add("wake_up_delay", delay);
        }

        let base_position = spawn
            .position
            .clone()
            .ok_or_else(|| anyhow::anyhow!("spawn_wave: spawn entry has no readable position"))?;
        let position = Coordinates {
            x: base_position.x + offset_x,
            y: base_position.y,
        };

        let has_big_hp_bar = lookups
            .entity_template_is_boss
            .get(&enemy_tpl_id)
            .copied()
            .unwrap_or(false);

        let spawn_evt = OverlordEventSpawnEntity {
            id: uuid::Builder::from_random_bytes(rng.random_bytes()).into_uuid(),
            entity_template_id: enemy_tpl_id,
            position,
            entity_team: EntityTeam::Enemy,
            has_big_hp_bar,
            entity_attributes: attrs,
        };
        let entity_id = spawn_evt.id;
        push_event(sink, spawn_evt)?;

        if delay > 0 {
            // `wake_up_delay` is already set on the spawn attrs above; the
            // `wake_up` effect counts it down 1/sec until the enemy wakes. (The
            // pre-migration code incremented it a SECOND time here, doubling the
            // sleep duration so delayed enemies stayed transparent ~2x as long as
            // configured — dropped.)
            incr_attr(sink, entity_id, "sleep", 1)?;
            push_event(
                sink,
                OverlordEventEntityApplyEffect {
                    entity_id,
                    effect_id: Uuid::parse_str(SLEEP_EFFECT_ID).unwrap(),
                },
            )?;
        }
    }
    Ok(())
}

/// Convert the typed config mirror (`prepare_fight_waves`) into the runtime
/// [`WaveFightData`] consumed by [`spawn_wave`]. This is the native data
/// source for the prepare_fight interpreter.
pub fn wave_data_from_config(cfg: &essences::fighting::PrepareFightWaves) -> WaveFightData {
    WaveFightData {
        entities: cfg
            .entities
            .iter()
            .map(|e| WaveEntityPower {
                entity_id: e.entity_id.clone(),
                power: e.power,
            })
            .collect(),
        waves: cfg
            .waves
            .iter()
            .map(|wave| {
                wave.iter()
                    .map(|s| WaveSpawn {
                        entity_id: s.entity_id.clone(),
                        // The deployed prepare_fight always carried an explicit
                        // `delay: 0` for spawns that omit it; mirror that default
                        // here (the typed config omits the 0s).
                        delay: Some(s.delay.unwrap_or(0.0)),
                        position: s.position.clone(),
                    })
                    .collect()
            })
            .collect(),
        time: cfg.time,
        power: Some(cfg.power),
    }
}

// ---------------------------------------------------------------------------
// Casts and movement
// ---------------------------------------------------------------------------

fn is_valid_target(
    lookups: &ContentLookups,
    target: &Entity,
    ability: &Ability,
    caster: &Entity,
) -> bool {
    let target_type = lookups
        .ability_target_type
        .get(&ability.template_id)
        .map(|s| s.as_str())
        .unwrap_or("");
    let by_team = match target_type {
        "Enemy" => target.team != caster.team,
        "Ally" => target.team == caster.team,
        _ => false,
    };
    let range = lookups
        .ability_range
        .get(&ability.template_id)
        .copied()
        .unwrap_or(0);
    by_team && get_distance_to(caster, target) <= range
}

/// Native: queue `casts` attack actions for `caster` against `valid_targets`.
/// Consumes `multicast_chance` from `rng`, then (per cast after the first, when
/// there are multiple targets) a `randint` for target selection. `_ability` is
/// unused, matching the original signature.
#[allow(clippy::too_many_arguments)]
pub fn cast(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    config: &GameConfig,
    lookups: &ContentLookups,
    caster: &Entity,
    _ability: &Ability,
    valid_targets: &[Entity],
    natural_casts_number: i64,
) -> Result<(), anyhow::Error> {
    let mut casts_number = natural_casts_number;
    let is_multicast = stat_throw(rng, lookups, caster, "multicast_chance", 0.0);
    if is_multicast {
        casts_number *= 2;
    }
    let base_cast_time = entity_get_tpl_cast_time(config, caster) as f64;
    let cast_time = (base_cast_time / casts_number as f64).floor() as i64;
    for i in 0..casts_number {
        let target = if valid_targets.len() > 1 {
            if i == 0 {
                get_target(caster, valid_targets)
                    .cloned()
                    .unwrap_or_else(|| valid_targets[0].clone())
            } else {
                let idx = rng.random_index(valid_targets.len());
                valid_targets[idx].clone()
            }
        } else {
            valid_targets[0].clone()
        };
        sink.push_attack(
            (i * cast_time).max(0) as u64,
            cast_time.max(0) as u64,
            target.id,
        )?;
    }
    Ok(())
}

/// Native: the ability `on_cast` hook. Rolls `bravery`; on success applies a
/// random buff (`protection`/`empower`). Consumes `bravery` then (if it lands)
/// a `randint(0,2)` from `rng`. Effect `on_apply` reactions dispatch via
/// `effects`.
pub fn on_cast(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    caster: &Entity,
) -> Result<(), anyhow::Error> {
    if stat_throw(rng, lookups, caster, "bravery", 0.0) {
        let pool = ["protection", "empower"];
        let idx = rng.random_index(pool.len());
        let code = pool[idx];
        apply_entity_effect(
            sink,
            lookups,
            effects,
            caster,
            code,
            balance::BRAVERY_BUFF_DURATION,
        )?;
    }
    Ok(())
}

/// Native: move `entity` toward the enemy line in a single multi-cell run
/// (one `StartMove` instead of one per cell — every per-cell seam quantizes
/// to the 100ms game tick and gives the client a chance to stutter).
///
/// Movement is fixed-direction (allies always advance +x, enemies −x), so we
/// only ever advance toward the nearest opponent *ahead* — never chase one we
/// have already reached or passed, which would march us away from the fight
/// forever. Against a mobile opponent we cover **half the gap** and against a
/// static one the **whole gap** (see the `max_steps` comment): both produce one
/// `StartMove`, so an approach is a single smooth run, not one per cell.
///
/// Two mutually-approaching mobile runners meet in the middle without landing
/// on or crossing each other: at fight start both plan on the same tick, each
/// covers its half, and they end adjacent. A `Run` lowers to an *immediate*
/// `StartMove` and the event loop is depth-first LIFO, so the first planner's
/// `handle_start_move` sets its `move_target` reservation BEFORE the second
/// plans this tick; the second's probe routes every cell through
/// `cell_exists_and_free` (checks coordinates AND reserved `move_target`), so
/// when both aim at the same midpoint the second takes the cell beside it.
///
/// (The entrance "run onto the screen → run in the fight" seam is a separate,
/// client-side concern — Unity's run-in tween must flow into the first
/// `StartMove` instead of force-settling to Idle; no server distance can cover
/// it.)
///
/// The walk also stops on the first cell where `ability` gains a valid target,
/// and never steps onto a cell occupied or reserved by another entity.
///
/// Neither team may cross the other's front line. A mover advances at most to
/// the column directly in front of the opposing team's frontmost LIVING unit and
/// never onto or past it, so the two sides meet exactly one column apart instead
/// of stacking on the same column (an enemy standing right under the hero). The
/// opposing front is taken over both current cells AND reserved `move_target`s,
/// so two mutual approachers don't both land on the same midpoint column on an
/// even gap: the depth-first / LIFO second planner sees the first's reservation
/// and stops one column short. This is the hard guarantee layered on top of the
/// half-gap / `max_steps` heuristic and the in-range stop.
pub fn advance_entity(
    sink: &mut dyn FightSink,
    config: &GameConfig,
    lookups: &ContentLookups,
    fight: &ActiveFight,
    entity: &Entity,
    ability: &Ability,
) -> Result<(), anyhow::Error> {
    let direction: i64 = if entity.team == EntityTeam::Ally {
        1
    } else {
        -1
    };

    // Current x-distance ahead; opponents behind (already passed) are ignored.
    let forward = |opp: &Entity| (opp.coordinates.x - entity.coordinates.x) * direction;

    let Some(opponent) = fight
        .entities
        .iter()
        .filter(|ent| ent.team != entity.team)
        .filter(|ent| forward(ent) > 0)
        .min_by_key(|ent| forward(ent))
    else {
        return Ok(());
    };

    let gap = forward(opponent);
    // Half the gap toward a mobile opponent (it advances too, so both cover
    // their half and meet in the middle — at fight start both plan on the same
    // tick, so it is ONE run each), and the whole gap against a static one
    // (which never closes, so creeping in half-at-a-time would chain runs).
    // Full-gap toward a *mobile* opponent is wrong: both would commit a run to
    // adjacent of the other's current cell and pass through each other on
    // different rows. The reservation keeps two mid-meeters off the same cell.
    let max_steps = if attr_present(opponent, "static") {
        (gap - 1).max(0)
    } else {
        gap / 2
    };

    // Front line of the opposing team facing this mover: the extreme x in the
    // mover's travel direction (the MIN opposing x for a +x mover, the MAX for a
    // -x mover), taken over both current cells AND reserved `move_target`s. The
    // mover may approach to one column in front of it (`front - direction`) and
    // no closer, so the two sides meet one column apart and never share a column.
    let opp_team = match entity.team {
        EntityTeam::Ally => EntityTeam::Enemy,
        EntityTeam::Enemy => EntityTeam::Ally,
    };
    let mut opp_front: Option<i64> = None;
    for e in &fight.entities {
        if e.team != opp_team || e.hp == 0 {
            continue;
        }
        for x in std::iter::once(e.coordinates.x).chain(e.move_target.as_ref().map(|t| t.x)) {
            opp_front = Some(match (opp_front, direction > 0) {
                (Some(cur), true) => cur.min(x),
                (Some(cur), false) => cur.max(x),
                (None, _) => x,
            });
        }
    }
    let front_limit = opp_front.map(|front| front - direction);

    let mut probe = entity.clone();
    for _ in 0..max_steps {
        let Some(next) = find_advance_coordinates(&probe, &fight.entities, config) else {
            break;
        };
        // Stop one column short of the opposing front — never cross it.
        if let Some(limit) = front_limit
            && (next.x - limit) * direction > 0
        {
            break;
        }
        probe.coordinates = next;
        if fight
            .entities
            .iter()
            .any(|ent| is_valid_target(lookups, ent, ability, &probe))
        {
            break;
        }
    }

    if probe.coordinates == entity.coordinates {
        return Ok(());
    }
    entity_run(sink, lookups, entity, probe.coordinates)
}

/// Native: emit a run action moving `entity` to `to` (no-op if speed is 0 or
/// the move covers no distance).
pub fn entity_run(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    entity: &Entity,
    to: Coordinates,
) -> Result<(), anyhow::Error> {
    const DEFAULT_TIME_PER_CELL: f64 = 500.0;
    let speed = get_entity_stat(lookups, entity, "speed");
    if speed == 0.0 {
        return Ok(());
    }
    let speed_norm = speed / 10000.0;
    // Euclidean, not |dx|: a diagonal sidestep covers √2 cells and must take
    // √2× the time, otherwise the unit visibly speeds up on lane changes.
    let dx = (to.x - entity.coordinates.x) as f64;
    let dy = (to.y - entity.coordinates.y) as f64;
    let distance = (dx * dx + dy * dy).sqrt();
    if distance == 0.0 {
        return Ok(());
    }
    let time_per_cell = DEFAULT_TIME_PER_CELL / speed_norm;
    let duration = (time_per_cell * distance).floor() as u64;
    sink.push_run(to, duration)
}

/// Native: attempt to cast `ability_id` from `caster`. Picks valid targets and
/// delegates to `cast`; if there are none and the caster is not `static`,
/// advances toward the enemy. `casts` is the natural cast count (default 1).
/// Consumes RNG only via `cast` / `advance_entity`.
#[allow(clippy::too_many_arguments)]
pub fn try_cast(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    config: &GameConfig,
    lookups: &ContentLookups,
    fight: &ActiveFight,
    caster: &Entity,
    ability_id: Uuid,
    casts: i64,
) -> Result<(), anyhow::Error> {
    if attr_present(caster, "sleep") {
        return Ok(());
    }
    if config.ability_template(ability_id).is_none() {
        return Err(anyhow::anyhow!("try_cast: unknown ability {ability_id}"));
    }
    let target_type = lookups
        .ability_target_type
        .get(&ability_id)
        .cloned()
        .unwrap_or_default();
    let ability_val = Ability {
        template_id: ability_id,
        level: 1,
        shards_amount: 0,
    };
    if target_type == "Self" {
        cast(
            sink,
            rng,
            config,
            lookups,
            caster,
            &ability_val,
            std::slice::from_ref(caster),
            casts,
        )?;
        return Ok(());
    }
    let mut valid_targets = Vec::new();
    for ent in &fight.entities {
        if is_valid_target(lookups, ent, &ability_val, caster) {
            valid_targets.push(ent.clone());
        }
    }
    if !valid_targets.is_empty() {
        cast(
            sink,
            rng,
            config,
            lookups,
            caster,
            &ability_val,
            &valid_targets,
            casts,
        )?;
        return Ok(());
    }
    if !attr_present(caster, "static") {
        advance_entity(sink, config, lookups, fight, caster, &ability_val)?;
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn entity_at(team: EntityTeam, x: i64) -> Entity {
        Entity {
            id: uuid::Uuid::new_v4(),
            team,
            coordinates: Coordinates { x, y: 1 },
            ..Default::default()
        }
    }

    /// `target_type` / `range` must reach `ContentLookups`. When they are absent
    /// (the bug), `target_type` resolves to "" → `by_team` is always false → no
    /// ability ever has a valid target → entities advance every tick and run
    /// through the enemy line without attacking.
    #[test]
    fn is_valid_target_requires_populated_target_type_and_range() {
        let ability_id = uuid::Uuid::new_v4();
        let ability = Ability {
            template_id: ability_id,
            level: 1,
            shards_amount: 0,
        };
        let caster = entity_at(EntityTeam::Ally, 0);
        let enemy_in_range = entity_at(EntityTeam::Enemy, 1);
        let enemy_out_of_range = entity_at(EntityTeam::Enemy, 5);
        let ally = entity_at(EntityTeam::Ally, 1);

        // The bug: empty lookups (target_type "" → by_team false) — never valid.
        let empty = ContentLookups::default();
        assert!(
            !is_valid_target(&empty, &enemy_in_range, &ability, &caster),
            "empty lookups must yield no valid target (this was the run-through bug)"
        );

        // Fixed: target_type "Enemy" + range 1 sourced from the typed config.
        let mut populated = ContentLookups::default();
        populated
            .ability_target_type
            .insert(ability_id, "Enemy".to_string());
        populated.ability_range.insert(ability_id, 1);

        assert!(
            is_valid_target(&populated, &enemy_in_range, &ability, &caster),
            "an in-range enemy must be a valid target once lookups are populated"
        );
        assert!(
            !is_valid_target(&populated, &enemy_out_of_range, &ability, &caster),
            "an out-of-range enemy must not be targetable (caster should advance)"
        );
        assert!(
            !is_valid_target(&populated, &ally, &ability, &caster),
            "an ally must not be a valid target for an Enemy-typed ability"
        );
    }

    fn lookups_with_speed(speed: f64) -> ContentLookups {
        let speed_id = uuid::Uuid::new_v4();
        let mut lookups = ContentLookups::default();
        lookups
            .attribute_by_code
            .insert("speed".to_string(), speed_id);
        lookups.attribute_base_value.insert(speed_id, speed);
        lookups
    }

    fn advance_lookups(ability_id: uuid::Uuid, range: i64) -> ContentLookups {
        let mut lookups = lookups_with_speed(10000.0);
        lookups
            .ability_target_type
            .insert(ability_id, "Enemy".to_string());
        lookups.ability_range.insert(ability_id, range);
        lookups
    }

    fn advance_against_enemy_at(enemy_x: i64, range: i64) -> NativeSink {
        let ability_id = uuid::Uuid::new_v4();
        let ability = Ability {
            template_id: ability_id,
            level: 1,
            shards_amount: 0,
        };
        let caster = entity_at(EntityTeam::Ally, 0);
        let enemy = entity_at(EntityTeam::Enemy, enemy_x);
        let lookups = advance_lookups(ability_id, range);
        let fight = ActiveFight {
            entities: vec![caster.clone(), enemy],
            ..Default::default()
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();

        let mut sink = NativeSink::default();
        advance_entity(&mut sink, &config, &lookups, &fight, &caster, &ability).unwrap();
        sink
    }

    /// A mobile opponent will advance to meet us, so the run covers half the
    /// gap (meet-in-the-middle) in ONE `StartMove` — both sides keep moving
    /// rather than one charging all the way in while the other stands. Same-cell
    /// overlap between two mid-approachers is prevented by the `move_target`
    /// reservation. Enemy at x=5, mobile → ally runs to the midpoint x=2.
    #[test]
    fn advance_entity_meets_a_mobile_opponent_in_the_middle() {
        let sink = advance_against_enemy_at(5, 1);
        assert_eq!(sink.casts.len(), 1, "the advance must be a single run");
        let run = &sink.casts[0];
        assert_eq!(
            run.coordinates,
            Some(Coordinates { x: 2, y: 1 }),
            "must cover half the 5-cell gap (meet in the middle)"
        );
        assert_eq!(
            run.run_duration_ticks,
            Some(1000),
            "2 cells × 500ms at baseline speed"
        );
    }

    /// A *static* opponent will never close the distance, so the approach must
    /// cover the whole gap in one smooth run (one cell short), not creep in
    /// half-at-a-time (which would stutter). Enemy at x=5 with the `static`
    /// attribute → ally runs all the way to x=4.
    #[test]
    fn advance_entity_full_approach_against_static_opponent() {
        let caster = entity_at(EntityTeam::Ally, 0);
        let mut enemy = entity_at(EntityTeam::Enemy, 5);
        enemy.attributes.0.insert("static".to_string(), 1);

        let sink = advance_in_fight(&caster, vec![enemy], 1);
        assert_eq!(sink.casts.len(), 1);
        assert_eq!(
            sink.casts[0].coordinates,
            Some(Coordinates { x: 4, y: 1 }),
            "must approach a static enemy all the way to x=4 in one run"
        );
    }

    /// The walk stops as soon as the ability gains a valid target, even
    /// before the half-gap budget is spent.
    #[test]
    fn advance_entity_stops_when_target_comes_into_range() {
        let sink = advance_against_enemy_at(4, 3);
        assert_eq!(sink.casts.len(), 1);
        assert_eq!(
            sink.casts[0].coordinates,
            Some(Coordinates { x: 1, y: 1 }),
            "one step puts the enemy within range 3 — stop there"
        );
    }

    /// Adjacent to the opponent's column (gap 1) there is nowhere to go —
    /// every shipped ability has range >= 1, so no run must be emitted and
    /// the entity must never enter the opponent's column.
    #[test]
    fn advance_entity_never_enters_the_opponent_column() {
        let sink = advance_against_enemy_at(1, 1);
        assert!(
            sink.casts.is_empty(),
            "gap 1 must produce no run (entity would land on the enemy)"
        );
    }

    fn entity_at_xy(team: EntityTeam, x: i64, y: i64) -> Entity {
        Entity {
            id: uuid::Uuid::new_v4(),
            team,
            coordinates: Coordinates { x, y },
            ..Default::default()
        }
    }

    fn advance_in_fight(caster: &Entity, others: Vec<Entity>, range: i64) -> NativeSink {
        let ability_id = uuid::Uuid::new_v4();
        let ability = Ability {
            template_id: ability_id,
            level: 1,
            shards_amount: 0,
        };
        let lookups = advance_lookups(ability_id, range);
        let mut entities = vec![caster.clone()];
        entities.extend(others);
        let fight = ActiveFight {
            entities,
            ..Default::default()
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let mut sink = NativeSink::default();
        advance_entity(&mut sink, &config, &lookups, &fight, caster, &ability).unwrap();
        sink
    }

    /// The "run inside each other" fix: under full-gap the ally's probe from
    /// (0,1) toward the enemy at x=4 walks through x=2, but the enemy has
    /// reserved (2,1) via its `move_target`, so the probe must route around it
    /// (sidestep) and never land on the reserved cell.
    #[test]
    fn advance_entity_does_not_land_on_a_reserved_midpoint() {
        let caster = entity_at(EntityTeam::Ally, 0); // (0, 1)
        let mut enemy = entity_at_xy(EntityTeam::Enemy, 4, 1);
        enemy.move_target = Some(Coordinates { x: 2, y: 1 });

        let sink = advance_in_fight(&caster, vec![enemy], 1);
        assert_eq!(sink.casts.len(), 1);
        assert_ne!(
            sink.casts[0].coordinates,
            Some(Coordinates { x: 2, y: 1 }),
            "must not land on the cell the enemy reserved for its run"
        );
    }

    /// INV-5 + INV-1 (SCN-2/SCN-3): when two mobile entities plan in the same
    /// tick, the LIFO first planner reserves its full-gap destination before the
    /// second plans. The second planner must still MOVE (a real, non-zero run) —
    /// it must NOT stand — and must not land on or cross the reserved cell. Here
    /// the enemy at (6,1) has reserved (3,1) on the ally's forward lane; the
    /// ally at (0,1) probes forward, is blocked at the reserved (3,1), and
    /// sidesteps around it, emitting a real run that never sits on the
    /// reservation and never reaches the enemy's column.
    #[test]
    fn advance_entity_second_mid_meeter_runs_short_not_stand() {
        let caster = entity_at(EntityTeam::Ally, 0); // (0, 1)
        let mut enemy = entity_at_xy(EntityTeam::Enemy, 6, 1);
        enemy.move_target = Some(Coordinates { x: 3, y: 1 });

        let sink = advance_in_fight(&caster, vec![enemy], 1);
        assert_eq!(sink.casts.len(), 1, "the second planner must emit one run");
        let dest = sink.casts[0].coordinates.clone().unwrap();
        // It MOVED (not a stand): destination differs from the start cell.
        assert_ne!(
            dest,
            Coordinates { x: 0, y: 1 },
            "second planner must move, not stand"
        );
        // It did not land on the reserved cell (no overlap with the reservation).
        assert_ne!(
            dest,
            Coordinates { x: 3, y: 1 },
            "must not land on the reserved cell"
        );
        // It stayed on its own side of the enemy (never onto/past x=6).
        assert!(
            dest.x < 6,
            "must not reach or cross the enemy's column (x=6)"
        );
    }

    /// SCN-2 (even gap, no shared cell): with the enemy's full-gap destination
    /// reserved, the ally's emitted run must not collide with that reserved cell
    /// on an even gap (the classic half-gap same-midpoint overlap). Ally (0,1)
    /// vs enemy (6,1) reserving its own full-gap target (1,1) on the -x side.
    #[test]
    fn advance_entity_even_gap_no_shared_cell() {
        let caster = entity_at(EntityTeam::Ally, 0); // (0, 1)
        let mut enemy = entity_at_xy(EntityTeam::Enemy, 6, 1);
        // Enemy (moving -x) reserves its full-gap destination one cell short of
        // the ally: gap 6 → x = 6 - 5 = 1.
        enemy.move_target = Some(Coordinates { x: 1, y: 1 });

        let sink = advance_in_fight(&caster, vec![enemy], 1);
        assert_eq!(sink.casts.len(), 1);
        let dest = sink.casts[0].coordinates.clone().unwrap();
        assert_ne!(
            dest,
            Coordinates { x: 1, y: 1 },
            "ally must not land on the enemy's reserved cell (no same-cell on even gaps)"
        );
    }

    /// When every reachable forward cell is taken, the entity must emit NO run
    /// rather than overlap — even though a distant enemy means it "wants" to
    /// advance. Three same-team allies fill the whole forward column.
    #[test]
    fn advance_entity_emits_no_run_when_boxed_in() {
        let caster = entity_at(EntityTeam::Ally, 0); // (0, 1)
        let block_fwd = entity_at_xy(EntityTeam::Ally, 1, 1);
        let block_up = entity_at_xy(EntityTeam::Ally, 1, 2);
        let block_down = entity_at_xy(EntityTeam::Ally, 1, 0);
        let enemy = entity_at_xy(EntityTeam::Enemy, 4, 1); // far → wants to advance

        let sink = advance_in_fight(&caster, vec![block_fwd, block_up, block_down, enemy], 1);
        assert!(
            sink.casts.is_empty(),
            "no free forward cell → no run (must not overlap)"
        );
    }

    /// Symmetric-occupancy fix: an ally moving +x must now respect a cell that
    /// is already occupied (before the fix `width_offset = -direction*width`
    /// was <= 0 for allies, so the x-occupancy check was skipped entirely and
    /// allies walked straight onto occupied cells).
    #[test]
    fn advance_entity_ally_respects_occupied_forward_cell() {
        let caster = entity_at(EntityTeam::Ally, 0); // (0, 1)
        let blocker = entity_at_xy(EntityTeam::Ally, 1, 1); // sits on the forward cell
        let enemy = entity_at_xy(EntityTeam::Enemy, 2, 1); // gives gap 2

        let sink = advance_in_fight(&caster, vec![blocker, enemy], 1);
        assert_eq!(sink.casts.len(), 1);
        assert_eq!(
            sink.casts[0].coordinates,
            Some(Coordinates { x: 1, y: 2 }),
            "must sidestep the occupied (1,1), not stack onto it"
        );
    }

    /// Covering only half the gap toward a mobile opponent keeps a runner
    /// strictly on its own side — it can never cross to the other side and then
    /// (fixed-direction) march away forever, the "run past each other and run
    /// indefinitely" bug. Enemy at x=8 vs ally at x=1, gap 7 → enemy covers half
    /// (3 cells) to x=5, well short of the ally. Tests the enemy (−x) direction.
    #[test]
    fn advance_entity_half_gap_stays_on_its_own_side() {
        let caster = entity_at_xy(EntityTeam::Enemy, 8, 1);
        let mut ally = entity_at_xy(EntityTeam::Ally, 1, 1);
        // A *living* ally (hp>0) so the front-line clamp actually engages here:
        // the floor is x=2, and the half-gap destination (x=5) is well clear of
        // it — half-gap and the clamp coexist, the clamp does not bind.
        ally.hp = 100;

        let sink = advance_in_fight(&caster, vec![ally], 1);
        assert_eq!(sink.casts.len(), 1);
        let dest = sink.casts[0].coordinates.clone().unwrap();
        assert_eq!(
            dest,
            Coordinates { x: 5, y: 1 },
            "enemy covers half the 7-cell gap (8 → 5)"
        );
        assert!(dest.x > 1, "must stay on its own side of the ally");
    }

    /// An entity must never chase an opponent that is *behind* it (lower x for
    /// an ally). Movement is fixed-direction, so advancing toward a passed
    /// opponent would only widen the gap forever — the runaway the players saw.
    /// With no opponent ahead, no run is emitted.
    #[test]
    fn advance_entity_does_not_chase_an_opponent_behind_it() {
        let caster = entity_at_xy(EntityTeam::Ally, 5, 1); // ally already past
        let enemy = entity_at_xy(EntityTeam::Enemy, 2, 1); // enemy behind (lower x)

        let sink = advance_in_fight(&caster, vec![enemy], 1);
        assert!(
            sink.casts.is_empty(),
            "ally must not advance further away from an opponent behind it"
        );
    }

    /// Front-line clamp: an enemy may advance at most to the column directly in
    /// front of the frontmost living ally and no further. Enemy at x=6 vs a live
    /// static hero at x=1 → stops at x=2 (one column in front), never on/past the
    /// hero's column.
    #[test]
    fn advance_entity_enemy_stops_one_column_in_front_of_player() {
        let enemy = entity_at_xy(EntityTeam::Enemy, 6, 1);
        let mut hero = entity_at_xy(EntityTeam::Ally, 1, 1);
        hero.hp = 100; // a *living* ally defines the front line (hp>0 filter)
        hero.attributes.0.insert("static".to_string(), 1);

        let sink = advance_in_fight(&enemy, vec![hero], 1);
        assert_eq!(sink.casts.len(), 1);
        assert_eq!(
            sink.casts[0].coordinates,
            Some(Coordinates { x: 2, y: 1 }),
            "enemy stops one column in front of the player (x=2), never on/past x=1"
        );
    }

    /// The clamp's real bite: a living forward ally (pet/summon/party unit) sits
    /// at or ahead of the enemy's column on another row, so it is filtered out of
    /// the "nearest opponent ahead" check and the enemy would otherwise dive past
    /// it toward the backline hero — ending up *inside* the player's formation.
    /// The front-line floor (frontmost living ally x + 1) forbids that step.
    ///
    /// Enemy at (3,1); a live summon ahead at (5,0); the static hero back at
    /// (1,1). Without the clamp the enemy advances to x=2 (past the summon, next
    /// to the hero); with it the enemy may not go below x=6 and emits no run.
    #[test]
    fn advance_entity_enemy_does_not_dive_past_a_forward_ally() {
        let enemy = entity_at_xy(EntityTeam::Enemy, 3, 1);
        let mut summon = entity_at_xy(EntityTeam::Ally, 5, 0);
        summon.hp = 100;
        let mut hero = entity_at_xy(EntityTeam::Ally, 1, 1);
        hero.hp = 100;
        hero.attributes.0.insert("static".to_string(), 1);

        let sink = advance_in_fight(&enemy, vec![summon, hero], 1);
        assert!(
            sink.casts.is_empty(),
            "enemy must not dive past the frontmost ally (x=5) into the formation"
        );
    }

    /// The front line is the frontmost *living* ally: a dead forward ally must
    /// not hold enemies out at its column. Enemy at (3,1); a dead summon at (5,0)
    /// (hp 0); a live static hero at (1,1) → the line is the hero, so the enemy
    /// advances to x=2 (one column in front of the hero).
    #[test]
    fn advance_entity_front_line_ignores_dead_allies() {
        let enemy = entity_at_xy(EntityTeam::Enemy, 3, 1);
        let summon = entity_at_xy(EntityTeam::Ally, 5, 0); // hp 0 (default) → dead
        let mut hero = entity_at_xy(EntityTeam::Ally, 1, 1);
        hero.hp = 100;
        hero.attributes.0.insert("static".to_string(), 1);

        let sink = advance_in_fight(&enemy, vec![summon, hero], 1);
        assert_eq!(sink.casts.len(), 1);
        assert_eq!(
            sink.casts[0].coordinates,
            Some(Coordinates { x: 2, y: 1 }),
            "dead forward ally is ignored; enemy stops one column in front of the live hero"
        );
    }

    /// The clamp is symmetric: an ALLY advancing +x also stops one column in
    /// front of the opposing line. Ally at x=0 vs a live static enemy at x=6 →
    /// stops at x=5, never on/past the enemy's column.
    #[test]
    fn advance_entity_ally_stops_one_column_in_front_of_enemy() {
        let caster = entity_at_xy(EntityTeam::Ally, 0, 1);
        let mut enemy = entity_at_xy(EntityTeam::Enemy, 6, 1);
        enemy.hp = 100;
        enemy.attributes.0.insert("static".to_string(), 1);

        let sink = advance_in_fight(&caster, vec![enemy], 1);
        assert_eq!(sink.casts.len(), 1);
        assert_eq!(
            sink.casts[0].coordinates,
            Some(Coordinates { x: 5, y: 1 }),
            "ally stops one column in front of the enemy (x=5), never on/past x=6"
        );
    }

    /// Mutual approach must meet ONE COLUMN APART, not pile onto the same column
    /// (the "enemy right under the hero" overlap on an even gap). The clamp folds
    /// the opposing team's reserved `move_target`s into the front line, so the
    /// LIFO-second planner stops one column short of the first's reservation.
    /// Here the ally has already reserved a forward move to (3,1); the enemy
    /// planning second (gap 4, even) must stop at x=4, not share the ally's x=3.
    #[test]
    fn advance_entity_mutual_meet_keeps_one_column_gap_enemy_second() {
        let enemy = entity_at_xy(EntityTeam::Enemy, 5, 1);
        let mut ally = entity_at_xy(EntityTeam::Ally, 1, 1);
        ally.hp = 100;
        ally.move_target = Some(Coordinates { x: 3, y: 1 });

        let sink = advance_in_fight(&enemy, vec![ally], 1);
        assert_eq!(sink.casts.len(), 1);
        let dest = sink.casts[0].coordinates.clone().unwrap();
        assert_eq!(
            dest.x, 4,
            "enemy must stop one column in front of the ally's reserved x=3, not on it"
        );
    }

    /// Symmetric to the above: the ALLY planning second yields to the enemy's
    /// reservation. Enemy reserved a forward move to (3,1); the ally (gap 4) must
    /// stop at x=2, one column short of x=3.
    #[test]
    fn advance_entity_mutual_meet_keeps_one_column_gap_ally_second() {
        let ally = entity_at_xy(EntityTeam::Ally, 1, 1);
        let mut enemy = entity_at_xy(EntityTeam::Enemy, 5, 1);
        enemy.hp = 100;
        enemy.move_target = Some(Coordinates { x: 3, y: 1 });

        let sink = advance_in_fight(&ally, vec![enemy], 1);
        assert_eq!(sink.casts.len(), 1);
        let dest = sink.casts[0].coordinates.clone().unwrap();
        assert_eq!(
            dest.x, 2,
            "ally must stop one column in front of the enemy's reserved x=3, not on it"
        );
    }

    /// Diagonal sidesteps must take √2× a straight step — duration comes from
    /// the euclidean distance, not |Δx| (which made lane changes visibly fast).
    #[test]
    fn entity_run_duration_uses_euclidean_distance() {
        let entity = entity_at(EntityTeam::Ally, 0); // at (0, 1)
        let lookups = lookups_with_speed(10000.0);

        let mut sink = NativeSink::default();
        entity_run(&mut sink, &lookups, &entity, Coordinates { x: 1, y: 2 }).unwrap();

        assert_eq!(sink.casts.len(), 1);
        assert_eq!(
            sink.casts[0].run_duration_ticks,
            Some(707),
            "√2 cells × 500ms, floored"
        );
    }

    /// TC-2: `get_entity_stat` floors the `.mod` multiplier at
    /// `MIN_STAT_MOD_MULT`, so a stacking debuff (weakness on attack, protection
    /// on received_damage) can't drive a stat to ≤0 (zero-damage / unkillable).
    #[test]
    fn get_entity_stat_mod_floor_prevents_zeroing() {
        let attack_id = uuid::Uuid::new_v4();
        let mut lookups = ContentLookups::default();
        lookups
            .attribute_by_code
            .insert("attack".to_string(), attack_id);
        lookups.attribute_base_value.insert(attack_id, 600.0);

        // −500% `.mod` would be ×(−4) pre-floor → must clamp to ×0.05.
        let mut weak = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        weak.attributes.add("attack.mod", -50_000);
        let v = get_entity_stat(&lookups, &weak, "attack");
        assert!(v > 0.0, "floored stat must stay positive, got {v}");
        assert!(
            (v - 600.0 * balance::MIN_STAT_MOD_MULT).abs() < 1e-9,
            "attack.mod must floor at MIN_STAT_MOD_MULT (×0.05), got {v}"
        );

        // No mod → unaffected (base, mult 1.0).
        let neutral = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        assert!((get_entity_stat(&lookups, &neutral, "attack") - 600.0).abs() < 1e-9);
    }

    /// TC-6 / CM-2: `touch_enemy` dodge follows the DR curve `ev/(ev+K)` with the
    /// non-inverted comparison `roll ≥ dodge`, and asymptotes below 100% (no
    /// evasion cliff). Pins the direction so a future `>=`→`<` flip FAILS here.
    #[test]
    fn touch_enemy_dodge_direction_and_asymptote() {
        let k = balance::tuning().k_dodge;
        // evasion == K ⇒ dodge prob = 0.5. touched ⇔ roll ≥ 0.5.
        let mut target = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        target.attributes.add("evasion", k as i64);

        let rng = GameRng::from_values(vec![0.4]);
        assert!(
            !touch_enemy(&rng, &ContentLookups::default(), &target),
            "roll 0.4 < dodge 0.5 ⇒ dodged (not touched)"
        );
        let rng = GameRng::from_values(vec![0.6]);
        assert!(
            touch_enemy(&rng, &ContentLookups::default(), &target),
            "roll 0.6 ≥ dodge 0.5 ⇒ touched (direction must not be inverted)"
        );

        // Asymptote < 100%: even enormous evasion can't guarantee a dodge — a
        // near-1 roll still lands. (dodge = 1e7/(1e7+K) ≈ 0.99985 < 1.)
        let mut glass = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        glass.attributes.add("evasion", 10_000_000);
        let rng = GameRng::from_values(vec![0.999_999]);
        assert!(
            touch_enemy(&rng, &ContentLookups::default(), &glass),
            "dodge asymptotes below 100% — a 0.999999 roll still touches"
        );

        // No evasion ⇒ always touched, no rng draw consumed (dummy value unused).
        let no_ev = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        let rng = GameRng::from_values(vec![0.0]);
        assert!(
            touch_enemy(&rng, &ContentLookups::default(), &no_ev),
            "no evasion ⇒ always touched"
        );
    }

    /// Regression guard for the "fight works but no damage" break AND the v2
    /// anti-unkillable floor. `received_damage` is a ×10000 multiplier whose base
    /// value (10000 == 100% taken) lives in `attribute_base_value`:
    /// * base lookup ENTIRELY ABSENT (content-extraction regression) →
    ///   `damage_entity` returns `None` (loud: fights visibly stall) — preserved
    ///   so the missing-base bug still surfaces.
    /// * base PRESENT but mitigated to ≤0 by a huge negative `received_damage.mod`
    ///   (e.g. stacked `protection`) → floored at `MIN_RECEIVED_DAMAGE_K`, so the
    ///   entity stays killable (`godmode` is the only true invuln).
    #[test]
    fn damage_requires_received_damage_base_value() {
        use rand::SeedableRng;

        let target = Entity {
            id: uuid::Uuid::new_v4(),
            hp: 1000,
            max_hp: 1000,
            ..Default::default()
        };
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));

        // Missing base: empty lookups → no received_damage base → all damage
        // cancelled (the loud content-regression guard).
        let empty = ContentLookups::default();
        let mut sink = NativeSink::default();
        let res = damage_entity(
            &mut sink,
            &rng,
            &empty,
            &target,
            100.0,
            CustomEventData::default(),
        )
        .unwrap();
        assert!(
            res.is_none(),
            "missing attribute_base_value cancels all damage (loud no-damage guard)"
        );

        // Base present (10000 = 100% taken, sourced from config) → a hit lands.
        let rd_id = uuid::Uuid::new_v4();
        let mut lookups = ContentLookups::default();
        lookups
            .attribute_by_code
            .insert("received_damage".to_string(), rd_id);
        lookups.attribute_base_value.insert(rd_id, 10000.0);

        let mut sink = NativeSink::default();
        let res = damage_entity(
            &mut sink,
            &rng,
            &lookups,
            &target,
            100.0,
            CustomEventData::default(),
        )
        .unwrap();
        assert!(
            res.is_some_and(|d| d > 0),
            "with received_damage base populated, a hit must deal damage"
        );

        // Anti-unkillable (TC-1): base present but stacked `protection` drives
        // `received_damage.mod` hugely negative — the entity must STILL take
        // positive damage (floored), never become invulnerable.
        let mut tank = target.clone();
        tank.attributes.add("received_damage.mod", -50_000); // −500% ⇒ ≤0 pre-floor
        let mut sink = NativeSink::default();
        let res = damage_entity(
            &mut sink,
            &rng,
            &lookups,
            &tank,
            100.0,
            CustomEventData::default(),
        )
        .unwrap();
        assert!(
            res.is_some_and(|d| d > 0),
            "stacked protection must not make an entity unkillable (received_damage floor)"
        );
    }

    /// Builds a minimal single-wave / single-spawn [`WaveFightData`] with the
    /// given reference `power`, runs [`spawn_wave`], and returns the `hp`
    /// attribute of the emitted `SpawnEntity` (the enemy that wave produced).
    fn spawn_wave_enemy_hp(power: Option<f64>) -> i64 {
        use rand::SeedableRng;

        let enemy_id = uuid::Uuid::new_v4();
        let fight_data = WaveFightData {
            entities: vec![WaveEntityPower {
                entity_id: Some(enemy_id.to_string()),
                power: Some(1.0),
            }],
            waves: vec![vec![WaveSpawn {
                entity_id: enemy_id.to_string(),
                delay: Some(0.0),
                position: Some(Coordinates { x: 3, y: 3 }),
            }]],
            time: 1.0,
            power,
        };

        // `spawn_wave` reads only `current_wave` + `entities` off the
        // fight; the fight kind is supplied separately via the `fight_type` arg.
        let fight = ActiveFight {
            current_wave: 1,
            ..Default::default()
        };

        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let mut sink = NativeSink::default();

        spawn_wave(
            &mut sink,
            &rng,
            &config,
            &lookups,
            &fight,
            &fight_data,
            fight_data.power.unwrap_or(0.0),
            1,
            "CampaignFight",
        )
        .unwrap();

        let spawn = sink
            .events
            .iter()
            .find_map(|ev| match ev {
                OverlordEvent::SpawnEntity {
                    entity_attributes, ..
                } => Some(entity_attributes),
                _ => None,
            })
            .expect("spawn_wave must emit a SpawnEntity for the current wave");

        // `hp == 0` is stored as an absent key by `EntityAttributes::add`.
        spawn.0.get("hp").copied().unwrap_or(0)
    }

    /// Regression guard for the "wave enemies spawn with 0 HP" bug: the typed
    /// config extraction dropped the per-fight reference `power`, so both
    /// `spawn_wave` call sites passed `base_power = 0.0`. With `base_power
    /// = 0`, `eff = 0` → `player_dps = 0` → `mob_hp_norm = 0` → every spawned
    /// enemy got `hp: 0` (instant death, no HP bar). Restoring a non-zero
    /// reference power must yield positive enemy HP.
    #[test]
    fn spawn_wave_enemy_hp_requires_nonzero_base_power() {
        // The bug: base_power 0 → zero player DPS → zero-HP enemies.
        assert_eq!(
            spawn_wave_enemy_hp(Some(0.0)),
            0,
            "base_power 0 must reproduce the zero-HP bug"
        );

        // Fixed: a non-zero reference power yields a positive enemy HP / HP bar.
        assert!(
            spawn_wave_enemy_hp(Some(100.0)) > 0,
            "a non-zero reference power must produce wave enemies with positive HP"
        );
    }

    /// Regression guard for over-long enemy transparency: a delayed wave spawn
    /// must set `wake_up_delay` exactly ONCE (= the configured spawn delay). The
    /// pre-migration code set it on the spawn attrs AND again via a post-spawn
    /// incr, doubling it so delayed enemies stayed asleep (transparent) ~2x as
    /// long as configured.
    #[test]
    fn delayed_spawn_sets_wake_up_delay_once() {
        use rand::SeedableRng;

        let enemy_id = uuid::Uuid::new_v4();
        let delay = 5i64;
        let fight_data = WaveFightData {
            entities: vec![WaveEntityPower {
                entity_id: Some(enemy_id.to_string()),
                power: Some(1.0),
            }],
            waves: vec![vec![WaveSpawn {
                entity_id: enemy_id.to_string(),
                delay: Some(delay as f64),
                position: Some(Coordinates { x: 3, y: 3 }),
            }]],
            time: 1.0,
            power: Some(100.0),
        };
        let fight = ActiveFight {
            current_wave: 1,
            ..Default::default()
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let mut sink = NativeSink::default();
        spawn_wave(
            &mut sink,
            &rng,
            &config,
            &lookups,
            &fight,
            &fight_data,
            100.0,
            1,
            "CampaignFight",
        )
        .unwrap();

        // The spawned entity carries wake_up_delay == the configured delay.
        let attrs = sink
            .events
            .iter()
            .find_map(|ev| match ev {
                OverlordEvent::SpawnEntity {
                    entity_attributes, ..
                } => Some(entity_attributes),
                _ => None,
            })
            .expect("must emit a SpawnEntity");
        assert_eq!(attrs.0.get("wake_up_delay").copied(), Some(delay));

        // No post-spawn IncrAttribute should re-add wake_up_delay (the 2x bug).
        let wake_incrs = sink
            .events
            .iter()
            .filter(|ev| {
                matches!(ev, OverlordEvent::EntityIncrAttribute { attribute, .. } if attribute == "wake_up_delay")
            })
            .count();
        assert_eq!(
            wake_incrs, 0,
            "wake_up_delay must not be incremented a second time (doubles sleep duration)"
        );
    }
}