wowlab_engine_combat/systems/

guardians.rs

//! Temporary guardian lifecycle and action scheduling.

use wowlab_engine_ports::Event;
use wowlab_engine_telemetry::TelemetrySink;
use wowlab_types::sim::{ActorId, SimTime};

use super::buffs::current_haste_mult_for;
use crate::{
    DamageFlags,
    context::{ActorView, CombatCtx, HookCtx},
    state::{
        CombatInstance, GuardianAbilityState, GuardianEvent, GuardianHandle, GuardianInstance,
        GuardianSpec, GuardianSummonError,
    },
};

pub(crate) fn reproject_guardian_action_speeds(
    program: &crate::state::CombatProgram,
    state: &mut CombatInstance,
    now: SimTime,
) {
    for visit in 0..state.runtime.companions.active_guardian_slots.len() {
        wowlab_types::bench_metrics::record_planned_guardian_slot_visit();
        // BOUNDS: visit remains below the active-slot list length captured by this loop.
        let guardian_index = usize::from(state.runtime.companions.active_guardian_slots[visit]);
        let ability_count = state
            .runtime
            .companions
            .guardians
            .get(guardian_index)
            .and_then(Option::as_ref)
            .map_or(0, |guardian| guardian.spec.ability_count());

        for ability_index in 0..ability_count {
            let Some((handle, source, target, expires_at, definition, runtime)) = state
                .runtime
                .companions
                .guardians
                .get(guardian_index)
                .and_then(Option::as_ref)
                .and_then(|guardian| {
                    Some((
                        guardian.handle,
                        guardian.source,
                        guardian.target,
                        guardian.expires_at,
                        *guardian.spec.abilities().get(ability_index)?,
                        *guardian.abilities.get(ability_index)?,
                    ))
                })
            else {
                continue;
            };

            if runtime
                .next_action_at
                .is_none_or(|scheduled| scheduled <= now)
            {
                continue;
            }

            let (base_delay, hasted) = if runtime.actions_executed == 0 {
                (
                    definition.first_action_delay_ms,
                    definition.hasted_first_action,
                )
            } else {
                (
                    definition.action_interval_ms,
                    definition.hasted_action_interval,
                )
            };

            if !hasted {
                continue;
            }

            let delay =
                scaled_delay_ms(ActorView::new(program, state, source), base_delay, hasted).max(1);
            let next = now.saturating_add(SimTime::from_millis(delay));

            if next > expires_at {
                continue;
            }

            if let Some(guardian) = state
                .runtime
                .companions
                .guardians
                .get_mut(guardian_index)
                .and_then(Option::as_mut)
                && guardian.handle == handle
                && let Some(ability) = guardian.abilities.get_mut(ability_index)
            {
                ability.next_action_at = Some(next);
            }

            state.schedule(Event::GuardianAction {
                t: next,
                guardian: program.runtime_events.guardian(
                    handle.0,
                    handle.1,
                    u16::try_from(ability_index).ok(),
                ),
                source,
                target,
            });
        }
    }
}

fn scaled_delay_ms(view: ActorView<'_>, delay_ms: u32, hasted: bool) -> u32 {
    if delay_ms == 0 || !hasted {
        return delay_ms;
    }

    wowlab_types::numeric::f64_to_u32_saturating_round(
        f64::from(delay_ms) / current_haste_mult_for(view),
    )
    .max(1)
}

pub(crate) fn summon_guardian(
    program: &crate::state::CombatProgram,
    state: &mut CombatInstance,
    spec: &GuardianSpec,
    now: SimTime,
) -> Result<GuardianHandle, GuardianSummonError> {
    let Some(target) = state.current_target() else {
        return Ok(GuardianHandle::new(0, 0));
    };
    let handle = allocate_guardian_handle(state)?;
    let Some(source) = handle.actor() else {
        return Err(GuardianSummonError::saturated());
    };
    let stat_snapshot =
        super::pet_actions::snapshot_owner_stats(program, state, spec.owner_coefficients);
    let expires_at = now.saturating_add(SimTime::from_millis(spec.duration_ms));
    let mut abilities = [GuardianAbilityState {
        next_action_at: None,
        actions_executed: 0,
    }; crate::state::defs::guardians::MAX_GUARDIAN_ABILITIES];

    for (ability_state, ability) in abilities.iter_mut().zip(spec.abilities()) {
        let first_delay = scaled_delay_ms(
            ActorView::new(program, state, source),
            ability.first_action_delay_ms,
            ability.hasted_first_action,
        );

        *ability_state = GuardianAbilityState {
            next_action_at: ability
                .self_scheduled
                .then(|| now.saturating_add(SimTime::from_millis(first_delay))),
            actions_executed: 0,
        };
    }

    let tag = spec.tag;

    let guardian = GuardianInstance {
        handle,
        spec: *spec,
        spawned_at: now,
        expires_at,
        abilities,
        source,
        target,
        stat_snapshot,
    };
    let slot = handle.0 as usize;

    if let Some(entry) = state.runtime.companions.guardians.get_mut(slot) {
        *entry = Some(guardian);
    }

    let Ok(active_slot) = u16::try_from(slot) else {
        return Err(GuardianSummonError::saturated());
    };

    state
        .runtime
        .companions
        .active_guardian_slots
        .push(active_slot);

    super::pet_actions::refresh_pet_stat_snapshots(program, state);
    let ability_count = state
        .runtime
        .companions
        .guardians
        .get(handle.0 as usize)
        .and_then(Option::as_ref)
        .map_or(0, |guardian| guardian.spec.ability_count());

    for ability_index in 0..ability_count {
        let next = state
            .runtime
            .companions
            .guardians
            .get(handle.0 as usize)
            .and_then(Option::as_ref)
            .and_then(|guardian| {
                guardian
                    .abilities
                    .get(ability_index)
                    .and_then(|ability| ability.next_action_at)
            });

        if let Some(t) = next {
            state.schedule(Event::GuardianAction {
                t,
                guardian: program.runtime_events.guardian(
                    handle.0,
                    handle.1,
                    u16::try_from(ability_index).ok(),
                ),
                source,
                target,
            });
        }
    }

    state.schedule(Event::GuardianExpire {
        t: expires_at,
        guardian: program.runtime_events.guardian(handle.0, handle.1, None),
    });
    tracing::trace!(
        tag,
        slot = handle.0,
        now_ms = now.as_millis(),
        expires_at_ms = expires_at.as_millis(),
        active = active_guardian_count(state, tag),
        "guardian summoned"
    );

    Ok(handle)
}

fn allocate_guardian_handle(
    state: &mut CombatInstance,
) -> Result<GuardianHandle, GuardianSummonError> {
    let slot = state
        .runtime
        .companions
        .free_guardian_slots
        .pop()
        .map(usize::from)
        .ok_or_else(GuardianSummonError::saturated)?;

    let Some(guardian) = state.runtime.companions.guardians.get(slot) else {
        return Err(GuardianSummonError::saturated());
    };

    assert!(
        guardian.is_none(),
        "free guardian slot {slot} must not contain a live guardian"
    );

    let Some(generation) = state.runtime.companions.guardian_generations.get_mut(slot) else {
        return Err(GuardianSummonError::saturated());
    };

    *generation = generation.wrapping_add(1).max(1);
    let generation = *generation;
    let Ok(slot) = u32::try_from(slot) else {
        return Err(GuardianSummonError::saturated());
    };

    Ok(GuardianHandle::new(slot, generation))
}

pub(crate) fn active_guardian_count(state: &CombatInstance, tag: u32) -> usize {
    state
        .runtime
        .companions
        .active_guardian_slots
        .iter()
        .filter_map(|slot| {
            // BOUNDS: active slots are inserted only after allocating this guardian arena.
            state.runtime.companions.guardians[usize::from(*slot)].as_ref()
        })
        .filter(|guardian| guardian.spec.tag == tag)
        .count()
}

/// Drives one `on_demand` ability on every active guardian carrying `tag`, leaving scheduled timelines untouched.
pub(crate) fn command_guardians(ctx: &mut CombatCtx<'_>, tag: u32, ability_index: usize) -> usize {
    #[derive(Clone, Copy)]
    struct Command {
        ability: crate::state::GuardianAbility,
        event: GuardianEvent,
        source: ActorId,
        target: wowlab_types::sim::EnemyIdx,
        npc_id: Option<u32>,
        stat_inheritance: crate::state::PetStatInheritance,
    }

    let mut commands =
        Vec::with_capacity(ctx.instance.runtime.companions.active_guardian_slots.len());

    for slot in &ctx.instance.runtime.companions.active_guardian_slots {
        // BOUNDS: active slots are inserted only after allocating this guardian arena.
        let guardian = ctx.instance.runtime.companions.guardians[usize::from(*slot)]
            .as_ref()
            .expect("active guardian plan references a live slot");

        if guardian.spec.tag != tag {
            continue;
        }

        let Some(ability) = guardian.spec.abilities().get(ability_index).copied() else {
            continue;
        };

        commands.push(Command {
            ability,
            event: event_for(guardian, ability_index, 0),
            source: guardian.source,
            target: guardian.target,
            npc_id: guardian.spec.npc_id,
            stat_inheritance: guardian.spec.stat_inheritance,
        });
    }

    let count = commands.len();

    for command in commands {
        let mut hook = HookCtx::new(
            crate::context::HookCtxServices {
                program: ctx.program,
                instance: ctx.instance,
                sink: ctx.sink,
                rng: ctx.rng,
            },
            crate::context::HookCtxRequest::for_target(ctx.now, command.target)
                .with_source(command.source),
        )
        .with_source_damage_flags(DamageFlags::PET | DamageFlags::GUARDIAN)
        .with_source_npc_id(command.npc_id)
        .with_pet_stat_inheritance(command.stat_inheritance);

        (command.ability.action)(&mut hook, command.event);
    }

    count
}

pub(crate) fn guardian_combat_coordinates(
    state: &CombatInstance,
    handle: GuardianHandle,
) -> Option<(ActorId, wowlab_types::sim::EnemyIdx)> {
    state
        .runtime
        .companions
        .guardians
        .get(handle.0 as usize)?
        .as_ref()
        .filter(|guardian| guardian.handle == handle)
        .map(|guardian| (guardian.source, guardian.target))
}

pub(crate) fn extend_guardians(
    _program: &crate::state::CombatProgram,
    state: &mut CombatInstance,
    tag: u32,
    amount_ms: u32,
) {
    let extension = SimTime::from_millis(amount_ms);

    for visit in 0..state.runtime.companions.active_guardian_slots.len() {
        // BOUNDS: `visit` is bounded by the active-slot slice length.
        let slot = usize::from(state.runtime.companions.active_guardian_slots[visit]);
        // BOUNDS: active slots are inserted only after allocating this guardian arena.
        let guardian = state.runtime.companions.guardians[slot]
            .as_mut()
            .expect("active guardian plan references a live slot");

        if guardian.spec.tag == tag {
            guardian.expires_at = guardian.expires_at.saturating_add(extension);
        }
    }
}

/// Remove up to `count` matching actors without firing their natural-demise hook.
pub(crate) fn dismiss_guardians(
    _program: &crate::state::CombatProgram,
    state: &mut CombatInstance,
    tag: u32,
    count: usize,
) -> usize {
    let mut removed = 0;

    let mut visit = 0;

    while visit < state.runtime.companions.active_guardian_slots.len() {
        if removed >= count {
            break;
        }

        // BOUNDS: `visit` remains below the current active-slot slice length.

        let index = usize::from(state.runtime.companions.active_guardian_slots[visit]);

        let should_remove = state
            .runtime
            .companions
            .guardians
            .get(index)
            .and_then(Option::as_ref)
            .is_some_and(|guardian| guardian.spec.tag == tag);

        if should_remove {
            let guardian = state
                .runtime
                .companions
                .guardians
                .get_mut(index)
                .and_then(Option::take)
                .expect("matching guardian slot");

            let _ = state.deactivate_pet_health(guardian.source);

            deactivate_guardian_slot(state, index);

            removed += 1;
        } else {
            visit += 1;
        }
    }

    removed
}

const fn event_for(
    guardian: &GuardianInstance,
    ability_index: usize,
    action_index: u16,
) -> GuardianEvent {
    GuardianEvent {
        handle: guardian.handle,
        tag: guardian.spec.tag,
        ability_index,
        action_index,
        spawned_at: guardian.spawned_at,
        expires_at: guardian.expires_at,
    }
}

fn fire_demise(ctx: &mut HookCtx<'_>, guardian: &GuardianInstance) {
    let Some(hook) = guardian.spec.on_demise else {
        return;
    };

    hook(ctx, event_for(guardian, 0, 0));
}

// #t(rust_similar_structs) prepared actions and queued commands are separate lifecycle stages with distinct ownership.
struct PreparedGuardianAction {
    ability: crate::state::GuardianAbility,
    event: GuardianEvent,
    source: ActorId,
    target: wowlab_types::sim::EnemyIdx,
    npc_id: Option<u32>,
    stat_inheritance: crate::state::PetStatInheritance,
}

#[derive(Clone, Copy)]
struct GuardianActionKey {
    handle: GuardianHandle,
    ability_index: usize,
    now: SimTime,
}

fn restore_guardian(state: &mut CombatInstance, guardian: GuardianInstance) {
    let handle = guardian.handle;
    let generation_is_current = state
        .runtime
        .companions
        .guardian_generations
        .get(handle.0 as usize)
        .is_some_and(|generation| *generation == handle.1);

    if generation_is_current
        && let Some(slot) = state
            .runtime
            .companions
            .guardians
            .get_mut(handle.0 as usize)
        && slot.is_none()
    {
        *slot = Some(guardian);
    }
}

fn prepare_guardian_action(
    program: &crate::state::CombatProgram,
    state: &mut CombatInstance,
    handle: GuardianHandle,
    ability_index: usize,
    now: SimTime,
) -> Option<PreparedGuardianAction> {
    let slot = state
        .runtime
        .companions
        .guardians
        .get_mut(handle.0 as usize)?;

    if slot.as_ref()?.handle != handle {
        return None;
    }

    let mut guardian = slot.take()?;
    let Some(ability) = guardian.spec.abilities().get(ability_index).copied() else {
        restore_guardian(state, guardian);

        return None;
    };

    if guardian
        .abilities
        .get(ability_index)
        .is_none_or(|ability| ability.next_action_at != Some(now))
        || now > guardian.expires_at
    {
        restore_guardian(state, guardian);

        return None;
    }

    let target = if state.is_valid_target(guardian.target) {
        guardian.target
    } else {
        state.retarget(program, now);
        let Some(target) = state.current_target() else {
            restore_guardian(state, guardian);

            return None;
        };

        target
    };

    guardian.target = target;
    let Some(ability_state) = guardian.abilities.get_mut(ability_index) else {
        restore_guardian(state, guardian);

        return None;
    };

    ability_state.next_action_at = None;
    ability_state.actions_executed = ability_state.actions_executed.saturating_add(1);
    let action_index = ability_state.actions_executed - 1;
    let prepared = PreparedGuardianAction {
        ability,
        event: event_for(&guardian, ability_index, action_index),
        source: guardian.source,
        target,
        npc_id: guardian.spec.npc_id,
        stat_inheritance: guardian.spec.stat_inheritance,
    };

    restore_guardian(state, guardian);

    Some(prepared)
}

fn finish_guardian_action(
    program: &crate::state::CombatProgram,
    state: &mut CombatInstance,
    key: GuardianActionKey,
    ability: crate::state::GuardianAbility,
    rng: &mut dyn FnMut() -> f64,
    sink: &mut TelemetrySink,
) {
    let GuardianActionKey {
        handle,
        ability_index,
        now,
    } = key;
    let Some(slot) = state
        .runtime
        .companions
        .guardians
        .get_mut(handle.0 as usize)
    else {
        return;
    };

    if slot
        .as_ref()
        .is_none_or(|guardian| guardian.handle != handle)
    {
        return;
    }

    let Some(mut guardian) = slot.take() else {
        return;
    };
    let Some(actions_executed) = guardian
        .abilities
        .get(ability_index)
        .map(|ability| ability.actions_executed)
    else {
        restore_guardian(state, guardian);

        return;
    };

    if ability.max_actions > 0 && actions_executed >= ability.max_actions {
        if ability.ends_guardian {
            let _ = state.deactivate_pet_health(guardian.source);

            deactivate_guardian_slot(state, handle.0 as usize);
            let mut ctx = HookCtx::new(
                crate::context::HookCtxServices {
                    program,
                    instance: state,
                    sink,
                    rng,
                },
                crate::context::HookCtxRequest::for_target(now, guardian.target)
                    .with_source(guardian.source),
            )
            .with_source_damage_flags(DamageFlags::PET | DamageFlags::GUARDIAN)
            .with_source_npc_id(guardian.spec.npc_id)
            .with_pet_stat_inheritance(guardian.spec.stat_inheritance);

            fire_demise(&mut ctx, &guardian);
        } else {
            restore_guardian(state, guardian);
        }

        return;
    }

    let delay = scaled_delay_ms(
        ActorView::new(program, state, guardian.source),
        ability.action_interval_ms,
        ability.hasted_action_interval,
    )
    .max(1);
    let next = now.saturating_add(SimTime::from_millis(delay));
    let Some(ability_state) = guardian.abilities.get_mut(ability_index) else {
        restore_guardian(state, guardian);

        return;
    };

    if next > guardian.expires_at {
        restore_guardian(state, guardian);

        return;
    }

    ability_state.next_action_at = Some(next);
    let source = guardian.source;
    let target = guardian.target;

    restore_guardian(state, guardian);
    state.schedule(Event::GuardianAction {
        t: next,
        guardian: program.runtime_events.guardian(
            handle.0,
            handle.1,
            u16::try_from(ability_index).ok(),
        ),
        source,
        target,
    });
}

pub(crate) fn process_guardian_action(
    ctx: &mut CombatCtx<'_>,
    handle: GuardianHandle,
    ability_index: usize,
) {
    let Some(prepared) =
        prepare_guardian_action(ctx.program, ctx.instance, handle, ability_index, ctx.now)
    else {
        return;
    };
    let mut hook = HookCtx::new(
        crate::context::HookCtxServices {
            program: ctx.program,
            instance: ctx.instance,
            sink: ctx.sink,
            rng: ctx.rng,
        },
        crate::context::HookCtxRequest::for_target(ctx.now, prepared.target)
            .with_source(prepared.source),
    )
    .with_source_damage_flags(DamageFlags::PET | DamageFlags::GUARDIAN)
    .with_source_npc_id(prepared.npc_id)
    .with_pet_stat_inheritance(prepared.stat_inheritance);

    (prepared.ability.action)(&mut hook, prepared.event);
    finish_guardian_action(
        ctx.program,
        ctx.instance,
        GuardianActionKey {
            handle,
            ability_index,
            now: ctx.now,
        },
        prepared.ability,
        ctx.rng,
        ctx.sink,
    );
}

pub(crate) fn process_guardian_expire(ctx: &mut CombatCtx<'_>, handle: GuardianHandle) {
    let guardian_id = handle.0;
    let guardian_generation = handle.1;

    let Some(slot) = ctx
        .instance
        .runtime
        .companions
        .guardians
        .get_mut(guardian_id as usize)
    else {
        return;
    };

    if slot
        .as_ref()
        .is_none_or(|guardian| guardian.handle != handle)
    {
        return;
    }

    let Some(guardian) = slot.take() else {
        return;
    };

    if ctx.now < guardian.expires_at {
        let expires_at = guardian.expires_at;

        *slot = Some(guardian);
        ctx.instance.schedule(Event::GuardianExpire {
            t: expires_at,
            guardian: ctx
                .program
                .runtime_events
                .guardian(guardian_id, guardian_generation, None),
        });

        return;
    }

    if guardian
        .ability_states()
        .iter()
        .any(|ability| ability.next_action_at == Some(ctx.now))
    {
        *slot = Some(guardian);
        ctx.instance.schedule(Event::GuardianExpire {
            t: ctx.now.saturating_add(SimTime::from_millis(1)),
            guardian: ctx
                .program
                .runtime_events
                .guardian(guardian_id, guardian_generation, None),
        });

        return;
    }

    let _ = ctx.instance.deactivate_pet_health(guardian.source);

    deactivate_guardian_slot(ctx.instance, guardian_id as usize);
    let mut hook = HookCtx::new(
        crate::context::HookCtxServices {
            program: ctx.program,
            instance: ctx.instance,
            sink: ctx.sink,
            rng: ctx.rng,
        },
        crate::context::HookCtxRequest::for_target(ctx.now, guardian.target)
            .with_source(guardian.source),
    )
    .with_source_damage_flags(DamageFlags::PET | DamageFlags::GUARDIAN)
    .with_source_npc_id(guardian.spec.npc_id)
    .with_pet_stat_inheritance(guardian.spec.stat_inheritance);

    fire_demise(&mut hook, &guardian);
}

fn deactivate_guardian_slot(state: &mut CombatInstance, slot: usize) {
    if let Some(visit) = state
        .runtime
        .companions
        .active_guardian_slots
        .iter()
        .position(|active| usize::from(*active) == slot)
    {
        state
            .runtime
            .companions
            .active_guardian_slots
            .swap_remove(visit);
        state
            .runtime
            .companions
            .free_guardian_slots
            .push(u16::try_from(slot).expect("guardian slot fits u16"));
    }
}

#[cfg(test)]
#[path = "guardians/tests.rs"]
mod tests;