Struct HookCtx 

pub struct HookCtx<'a> {

    pub(crate) state: &'a mut CombatState,
    pub(crate) buf: &'a mut DenseBuffer,
    pub(crate) sink: &'a mut TelemetrySink,
    pub(crate) now: SimTime,
    pub(crate) source_damage_flags: DamageFlags,
    pub(crate) source_npc_id: Option<u32>,
    pub(crate) source: ActorId,
    pub(crate) target: Option<EnemyIdx>,
    pub(crate) effect_target: Option<ActorId>,
    pub(crate) rng: &'a mut dyn FnMut() -> f64,
    driver_spell_id: u32,
    empower_rank: u8,
    free_action_source: Option<FreeActionSource>,
}

Constrained context exposing only the operations cast hooks may perform.

Fields

state: &'a mut CombatState

buf: &'a mut DenseBuffer

sink: &'a mut TelemetrySink

now: SimTime

source_damage_flags: DamageFlags

source_npc_id: Option<u32>

source: ActorId

target: Option<EnemyIdx>

effect_target: Option<ActorId>

rng: &'a mut dyn FnMut() -> f64

driver_spell_id: u32

Spell or aura that invoked this hook; provenance for resource gains and telemetry.

empower_rank: u8

free_action_source: Option<FreeActionSource>

Implementations

impl HookCtx<'_>

pub(crate) fn with_source_damage_flags(self, flags: DamageFlags) -> Self

pub(crate) fn with_effect_target(self, target: ActorId) -> Self

pub(crate) fn with_source_npc_id(self, npc_id: Option<u32>) -> Self

pub(super) fn source_flags(&self, flags: DamageFlags) -> DamageFlags

pub(super) fn resolved_pet_coefficient( &self, flags: DamageFlags, stat: PetStatKind, coefficient: f64, ) -> f64

fn aura_local(&self, aura_id: u32) -> Option<LocalAuraIdx>

impl HookCtx<'_>

pub const fn active_channel_ticks_remaining(&self) -> u8

Number of scheduled ticks still belonging to the active channel.

pub const fn is_last_channel_tick(&self) -> bool

Whether the channel tick being processed is the channel’s final one, as SimC’s last_tick().

The signal is the channel’s own remaining-tick count rather than a timestamp comparison.

pub fn multiply_active_channel_damage(&mut self, multiplier: f64) -> bool

Multiply damage dealt by every tick of the channel currently being started.

Cast hooks can snapshot cast-start mechanics without projecting them into a temporary aura. Returns false outside an active channel or for an invalid multiplier.

impl HookCtx<'_>

pub(crate) fn schedule_periodic_driver( &mut self, delay_ms: u32, driver_index: usize, expires_at: Option<SimTime>, target: Option<EnemyIdx>, )

pub(crate) fn schedule_effect_program( &mut self, delay_ms: u32, effects: SpellEffectRange, profile_spell_id: u32, flags: DamageFlags, originating_proc_driver_spell_id: u32, )

impl<'a> HookCtx<'a>

pub fn new(services: HookCtxServices<'a>, request: HookCtxRequest) -> Self

pub const fn view(&self) -> HookView<'_>

pub const fn free_action_source(&self) -> Option<FreeActionSource>

Provenance for this hook’s cost-free action, if it was dispatched as one.

pub const fn source(&self) -> ActorId

pub const fn target(&self) -> Option<EnemyIdx>

pub const fn empower_rank(&self) -> Option<u8>

One-based empower rank selected for the cast whose hook is running.

pub fn set_health_fraction(&mut self, fraction: f64)

Update this friendly actor’s canonical health and fire active threshold crossings.

pub fn resolved_spell_effect_targets( &mut self, geometry_effect: (u32, u8), impact_spell_id: u32, max_targets: Option<u8>, ) -> Vec<EnemyIdx>

Resolve concrete hostile identities using parent-spell geometry and impact-spell LOS rules.

pub fn state(&self) -> &CombatState

pub fn talent_rank(&self, talent_spell_id: u32) -> u8

Selected rank for a decoded talent, or zero when it is not selected.

pub fn talent_selected(&self, talent_spell_id: u32) -> bool

Whether a decoded talent is selected at any rank.

pub fn selected_talent_proc_chance(&self, talent_spell_id: u32) -> f64

Selected talent’s authoritative SpellAuraOptions.ProcChance, or zero when unselected.

pub fn spec_config<T>(&self) -> Option<&T>

where T: SpecConfig,

pub fn spec_runtime<T>(&self) -> Option<&T>

where T: SpecRuntime,

pub fn spec_runtime_mut<T>(&mut self) -> Option<&mut T>

where T: SpecRuntime,

pub fn total_damage(&self) -> f64

pub fn buf(&self) -> &DenseBuffer

pub fn buf_mut(&mut self) -> &mut DenseBuffer

pub fn game_data(&self) -> &ResolvedGameData

pub const fn driver_spell_id(&self) -> u32

The spell or aura whose hook is running; 0 when the caller declared none.

pub fn rng(&mut self) -> &mut dyn FnMut() -> f64

Borrow the iteration’s deterministic uniform RNG.

pub(crate) const fn set_source(&mut self, source: ActorId)

pub(crate) const fn with_empower_rank(self, rank: u8) -> Self

pub(crate) const fn with_free_action_source( self, source: FreeActionSource, ) -> Self

pub(crate) const fn with_driver_spell(self, driver_spell_id: u32) -> Self

Records the spell or aura whose hook is running, so its resource gains carry provenance.

pub(crate) fn combat_ctx(&mut self, target: EnemyIdx) -> CombatCtx<'_>

pub(crate) fn combat_ctx_with_source( &mut self, source: ActorId, target: EnemyIdx, ) -> CombatCtx<'_>

const fn driver_resource_gain_source(&self) -> ResourceGainSource

fn schedule_pending_timer(&mut self, delay_ms: u32, pending: PendingHookTimer)

Trait Implementations

impl AuraOps for HookCtx<'_>

fn with_resolved_target( &mut self, target: EnemyIdx, apply: impl FnOnce(&mut Self), )

Run target-dependent hook effects against one identity from a resolved hit set.

fn apply_owner_aura(&mut self, local: u8)

Apply a player-owned aura from a pet or guardian callback.

fn apply_aura_with_duration(&mut self, local: u8, duration_ms: u32)

Apply an aura using a duration computed by the current cast.

fn apply_aura_with_rolling_multiplier(&mut self, local: u8, multiplier: f64)

Apply a rolling periodic aura while scaling the damage contributed by this application.

fn apply_pet_aura_with_duration(&mut self, local: u8, duration_ms: u32)

Apply an aura to the primary persistent pet from an owner callback.

fn add_aura_stack(&mut self, local: u8)

Add one stack without refreshing an active aura’s duration.

fn add_owner_aura_stack(&mut self, local: u8)

Add a stack to a player-owned aura from a pet or guardian callback.

fn add_residual_damage(&mut self, local: u8, amount: f64)

Add post-mitigation damage to an aura-local residual pool, applying or refreshing its draining periodic aura.

fn accumulate_damage(&mut self, local: u8, amount: f64)

Add damage to an aura-local delayed accumulator.

fn accumulate_owner_damage(&mut self, local: u8, amount: f64)

Add companion damage to a player-owned delayed accumulator.

fn take_accumulated_damage(&mut self, local: u8) -> f64

Drain an aura-local delayed accumulator.

fn expire_owner_aura(&mut self, local: u8)

Expire a player-owned aura from a pet or guardian callback.

fn consume_owner_aura_stack(&mut self, local: u8) -> bool

Consume a stack from a player-owned aura from a pet or guardian callback.

fn extend_aura(&mut self, local: u8, ms: u32)

Extend an active aura’s expiry by a flat ms (no pandemic recompute).

fn reduce_aura(&mut self, local: u8, ms: u32)

Shorten an active aura’s expiry by a flat ms, expiring it immediately when exhausted.

fn is_owner_aura_active(&self, local: u8) -> bool

Query a player-applied aura from a pet or guardian callback.

fn aura_remaining_ms(&self, local: u8) -> Option<u32>

Remaining lifetime of the exact aura instance in this hook context.

Returns None when inactive and u32::MAX for a permanent aura.

fn flat_periodic_damage_remaining(&self, local: u8) -> Option<f64>

Remaining pre-modifier damage in an active flat-damage periodic.

fn now(&self) -> SimTime

fn apply_aura(&mut self, local: u8)

fn apply_aura_n(&mut self, local: u8, n: i32)

fn residual_damage_remaining(&self, local: u8) -> f64

fn expire_aura(&mut self, local: u8)

fn consume_aura(&mut self, local: u8) -> bool

fn consume_aura_stack(&mut self, local: u8) -> bool

fn consume_aura_stacks(&mut self, local: u8, count: i32) -> i32

fn refresh_aura_snapshot_multiplier( &mut self, local: u8, multiplier: f64, ) -> bool

fn is_aura_active(&self, local: u8) -> bool

fn aura_stacks(&self, local: u8) -> i32

fn aura_local_index(&self, aura_id: u32) -> Option<u8>

fn apply_aura_id(&mut self, aura_id: u32)

fn apply_aura_id_n(&mut self, aura_id: u32, n: i32)

fn add_aura_stack_id(&mut self, aura_id: u32)

fn expire_aura_id(&mut self, aura_id: u32)

fn is_aura_active_id(&self, aura_id: u32) -> bool

fn aura_stacks_id(&self, aura_id: u32) -> i32

fn flat_periodic_damage_remaining_id(&self, aura_id: u32) -> Option<f64>

fn take_aura_stacks_id(&mut self, aura_id: u32) -> i32

impl CooldownOps for HookCtx<'_>

fn spend_spell_charge(&mut self, spell: u8) -> bool

fn reduce_cooldown(&mut self, spell: u8, amount_ms: u32)

fn reset_cooldown(&mut self, spell: u8)

fn start_cooldown(&mut self, spell: u8)

fn set_spell_gate(&mut self, spell: u8, gate: SpellGate, available: bool)

fn grant_charges(&mut self, spell: u8, amount: u8)

fn spell_cooldown_ms(&self, spell: u8) -> u32

fn spell_cooldown_remaining_ms(&self, spell: u8) -> u32

fn spell_ready(&self, spell: u8) -> bool

fn spell_current_charges(&self, spell: u8) -> i32

impl DamageOps for HookCtx<'_>

fn deal_damage_ap_result( &mut self, spell_id: u32, coef: f64, flags: DamageFlags, ) -> DamageOutcome

Deal one attack-power hit and return its post-mitigation outcome.

fn deal_damage_from_result( &mut self, spell_id: u32, parent: DamageOutcome, multiplier: f64, flags: DamageFlags, ) -> DamageOutcome

Derive a non-crit child hit from a parent’s final amount under the child’s own modifiers.

The parent amount already contains player-wide damage and versatility multipliers.

The child retains its spell-scoped and target modifiers. Those inherited terms are not applied a second time.

fn deal_profiled_damage_ap( &mut self, spell_id: u32, profile_spell_id: u32, coef: f64, flags: DamageFlags, )

Deal an AP hit under one spell’s formula while reporting a distinct combat-log identity.

fn haste_multiplier(&self) -> f64

Current outgoing spell/melee haste multiplier (1.0 means unmodified cadence).

fn deal_damage_ap_to_target( &mut self, target: EnemyIdx, spell_id: u32, coef: f64, flags: DamageFlags, )

Deal exactly one attack-power hit to a previously resolved enemy identity.

fn deal_pet_damage_ap_for_npc( &mut self, npc_id: u32, spell_id: u32, coefficient: f64, )

Deal pet AP damage for an explicitly identified NPC actor.

fn deal_damage_sp_to_target( &mut self, target: EnemyIdx, spell_id: u32, coef: f64, flags: DamageFlags, )

Deal exactly one spell-power hit to a previously resolved enemy identity.

fn deal_resolved_damage(&mut self, spell_id: u32, amount: f64)

Deal a post-mitigation redirected amount without a second modifier pass.

fn deal_triggered_damage( &mut self, source_spell_id: u32, effect_index: u8, multiplier: f64, flags: DamageFlags, ) -> bool

Follow one resolved DBC trigger edge and deal its terminal child damage.

fn deal_item_damage_sp(&mut self, spell_id: u32)

Deal an item’s spell-power damage, reading its effect-1 SP coefficient from game data.

fn deal_damage_ap(&mut self, spell_id: u32, coef: f64, flags: DamageFlags)

fn deal_damage_ap_if_positive( &mut self, spell_id: u32, coefficient: f64, flags: DamageFlags, )

fn deal_effect_damage_ap( &mut self, effect: (u32, u8), multiplier: f64, flags: DamageFlags, )

fn deal_effect_damage_ap_with_geometry( &mut self, effect: (u32, u8), geometry_effect: (u32, u8), multiplier: f64, flags: DamageFlags, )

fn deal_effect_damage_sp_with_geometry( &mut self, effect: (u32, u8), geometry_effect: (u32, u8), multiplier: f64, flags: DamageFlags, )

fn deal_physical_damage_ap_if_positive( &mut self, spell_id: u32, coefficient: f64, )

fn deal_pet_damage_ap(&mut self, spell_id: u32, coefficient: f64)

fn deal_physical_pet_damage_ap(&mut self, spell_id: u32, coefficient: f64)

fn deal_damage_sp(&mut self, spell_id: u32, coef: f64, flags: DamageFlags)

fn deal_profiled_damage_sp( &mut self, spell_id: u32, profile_spell_id: u32, coef: f64, flags: DamageFlags, )

fn deal_damage_flat(&mut self, spell_id: u32, amount: f64)

fn player_swing_period_ms(&self, hand: SwingHand) -> Option<u32>

fn effect_base_points(&self, effect: (u32, u8)) -> f64

fn effect_points(&self, effect: (u32, u8)) -> f64

fn effect_percent(&self, effect: (u32, u8)) -> f64

fn effect_ap_coefficient(&self, effect: (u32, u8)) -> f64

fn effect_sp_coefficient(&self, effect: (u32, u8)) -> f64

fn target_health_fraction(&self) -> f64

impl Debug for HookCtx<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl GuardianOps for HookCtx<'_>

fn command_guardians(&mut self, tag: u32, ability_index: usize) -> usize

Drive an on_demand ability on every active guardian with tag, returning how many fired.

fn summon_guardian(&mut self, spec: GuardianSpec) -> GuardianHandle

fn active_guardian_count(&self, tag: u32) -> usize

fn extend_guardians(&mut self, tag: u32, amount_ms: u32)

fn dismiss_guardians(&mut self, tag: u32, count: usize) -> usize

impl ProcOps for HookCtx<'_>

fn roll_threshold( &mut self, idx: LocalThresholdIdx, increment_scale: f64, ) -> bool

Add one trigger event to an accumulated-threshold proc; increment_scale multiplies the tracker’s uniform roll (plain callers pass 1.0), returning true when the threshold procs.

fn roll_system_rppm(&mut self, driver_spell_id: u32) -> bool

Roll a shared proc system’s RPPM tracker by its DBC driver spell id.

The driver also owns its optional DBC proc-category recovery.

Attempts inside that window do not advance the tracker. Successful rolls start recovery.

fn proc_category_ready(&self, driver_spell_id: u32) -> bool

Whether a DBC proc driver is outside its ProcCategoryRecovery window.

fn start_proc_category_cooldown(&mut self, driver_spell_id: u32)

Start the DBC ProcCategoryRecovery window for a proc driver.

fn roll_attempt_proc( &mut self, driver_spell_id: u32, chance_for_attempt: impl FnOnce(u32) -> f64, ) -> bool

Roll a driver-scoped proc whose chance is a function of its current attempt number.

fn add_proc_counter(&mut self, driver_spell_id: u32, amount: u32) -> u32

Add to a driver-scoped event counter and return its new value.

fn reset_proc_counter(&mut self, driver_spell_id: u32)

Clear a driver-scoped event counter.

fn proc_counter(&self, driver_spell_id: u32) -> u32

Read a driver-scoped event counter without changing it.

fn mark_proc_flags_once(&mut self, driver_spell_id: u32, flags: u32) -> bool

Mark one or more driver-scoped flags and return true only on their first occurrence.

fn consume_proc_counter(&mut self, driver_spell_id: u32, amount: u32) -> u32

Consume from a driver-scoped event counter and return the remaining value.

fn advance_proc_counter_by( &mut self, driver_spell_id: u32, amount: u32, threshold: u32, ) -> bool

Advance a driver-scoped event counter and return true at the threshold.

fn advance_proc_counter(&mut self, driver_spell_id: u32, threshold: u32) -> bool

Advance a driver-scoped event counter by one and return true at the threshold.

fn roll_rppm(&mut self, idx: LocalRppmIdx) -> bool

fn roll_item_rppm(&mut self, item_id: u32) -> bool

fn roll_enchant_rppm(&mut self, enchantment_id: u32) -> bool

fn roll_accumulating_proc( &mut self, driver_spell_id: u32, chance_per_attempt: f64, ) -> bool

impl ResourceOps for HookCtx<'_>

fn gain_resource(&mut self, amount: f64) -> f64

Gain primary resource, attributed to the hook’s driver spell. Returns wasted amount.

fn gain_resource_from(&mut self, amount: f64, source: ResourceGainSource) -> f64

Gain primary resource with explicit provenance.

fn gain_unmodified_resource_from( &mut self, amount: f64, source: ResourceGainSource, ) -> f64

Gain primary resource without applying active gain multipliers.

fn gain_secondary_resource(&mut self, amount: f64) -> f64

Gain secondary resource, attributed to the hook’s driver spell. Returns wasted amount.

fn gain_secondary_resource_from( &mut self, amount: f64, source: ResourceGainSource, ) -> f64

Gain secondary resource with explicit provenance.

fn spend_secondary_resource(&mut self, amount: f64) -> bool

fn spend_all_secondary_resource(&mut self, cost: f64) -> f64

fn secondary_resource(&self) -> f64

fn primary_resource(&self) -> f64

fn spell_resource_cost(&self, spell: u8) -> f64

fn gain_pet_resource(&mut self, npc_id: u32, amount: f64) -> f64

fn last_primary_spent(&self) -> f64

fn last_optional_primary_spent(&self) -> f64

fn last_secondary_spent(&self) -> f64

impl SchedulingOps for HookCtx<'_>

fn dispatch_free_action( &mut self, spell_id: u32, source: FreeActionSource, ) -> bool

Execute a registered spell as a cost-free child action on this hook’s locked target.

The child retains its payload, aura/effects, gains, telemetry, and spell hook. It bypasses player costs, cooldowns, GCD/history, and global player-cast hooks.

fn dispatch_proc_spell( &mut self, spell_id: u32, proc_driver_spell_id: u32, affected: ActorId, ) -> bool

Execute a registered spell spawned by a proc without player action costs.

The originating driver is retained for proc provenance and self-loop suppression.

fn schedule_hook(&mut self, delay_ms: u32, hook: CastHookFn)

Schedule a hook for delayed execution; a captured target binds the callback and cancels it if that enemy is missing, inactive, or dead when the timer fires.

fn trigger_periodic_driver(&mut self, driver_spell_id: u32) -> bool

Activate a finite periodic driver by its real spell/passive identity.

fn trigger_periodic_driver_for( &mut self, driver_spell_id: u32, duration_ms: u32, ) -> bool

Activate a finite periodic driver with a runtime-resolved lifetime.

The driver must be registered as triggered. This overrides the activation lifetime for mechanics whose duration varies per cast.

fn schedule_ground_effect(&mut self, spec: GroundEffectSpec)

Schedule a location-locked sequence of spatial damage pulses.

fn schedule_ground_effect_from_data( &mut self, driver_spell_id: u32, timing_effect_index: u8, geometry_effect: (u32, u8), damage_effect: (u32, u8), flags: DamageFlags, ) -> bool

Resolve a driver’s authored duration and pulse period, then schedule its ground payload.

Panics

Panics if the clamped pulse count does not fit in u8.

fn schedule_event(&mut self, event: Event)