Struct HookCtx 

pub struct HookCtx<'a> {

    pub(crate) program: &'a CombatProgram,
    pub(crate) instance: &'a mut CombatInstance,
    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) pet_stat_inheritance: PetStatInheritance,
    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

program: &'a CombatProgram

instance: &'a mut CombatInstance

sink: &'a mut TelemetrySink

now: SimTime

source_damage_flags: DamageFlags

source_npc_id: Option<u32>

pet_stat_inheritance: PetStatInheritance

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_npc_id(self, npc_id: Option<u32>) -> Self

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_pet_stat_inheritance( self, inheritance: PetStatInheritance, ) -> Self

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

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

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.

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_action: LocalDamageActionIdx, 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 with_resolved_spell_effect_targets<T>( &mut self, geometry_effect: DamageEffectId, impact_action: DamageActionId, max_targets: Option<u8>, use_targets: impl FnOnce(&mut Self, &[EnemyIdx]) -> T, ) -> T

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

Finalized target scratch is restored after the callback, including nested resolution.

pub fn program(&self) -> HookProgramView<'_>

pub fn buff_totals(&self) -> BuffTotals

Sum the current player’s finalized buff contributions for this hook target.

pub fn instance(&self) -> &CombatInstance

pub fn talent_rank(&self, talent: DamageActionId) -> u8

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

pub fn talent_selected(&self, talent: DamageActionId) -> bool

Whether a decoded talent is selected at any rank.

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) -> &BoundDenseBuffer

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<'_>

fn spell_identity(&self, local: LocalSpellIdx) -> LocalSpellIdx

fn aura_identity(&self, local: LocalAuraIdx) -> LocalAuraIdx

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: LocalAuraIdx)

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

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

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

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

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

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

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

fn add_aura_stack(&mut self, local: LocalAuraIdx)

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

fn add_owner_aura_stack(&mut self, local: LocalAuraIdx)

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

fn add_residual_damage(&mut self, local: LocalAuraIdx, 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: LocalAuraIdx, amount: f64)

Add damage to an aura-local delayed accumulator.

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

Add companion damage to a player-owned delayed accumulator.

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

Drain an aura-local delayed accumulator.

fn expire_owner_aura(&mut self, local: LocalAuraIdx)

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

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

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

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

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

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

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

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

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

fn aura_remaining_ms(&self, local: LocalAuraIdx) -> 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: LocalAuraIdx) -> Option<f64>

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

fn now(&self) -> SimTime

fn apply_aura(&mut self, local: LocalAuraIdx)

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

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

fn expire_aura(&mut self, local: LocalAuraIdx)

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

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

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

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

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

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

impl CooldownOps for HookCtx<'_>

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

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

fn reset_cooldown(&mut self, spell: LocalSpellIdx)

fn start_cooldown(&mut self, spell: LocalSpellIdx)

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

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

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

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

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

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

impl DamageOps for HookCtx<'_>

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

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

fn deal_damage_from_result( &mut self, action: DamageActionId, 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, action: DamageActionId, profile: DamageActionId, 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, action: DamageActionId, coef: f64, flags: DamageFlags, )

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

fn deal_pet_damage_ap_with_inheritance( &mut self, action: DamageActionId, coefficient: f64, inheritance_multiplier: f64, )

Deal pet AP damage using a construction-resolved NPC inheritance scalar.

fn deal_damage_sp_to_target( &mut self, target: EnemyIdx, action: DamageActionId, coef: f64, flags: DamageFlags, )

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

fn deal_resolved_damage(&mut self, action: DamageActionId, amount: f64)

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

fn deal_triggered_damage( &mut self, effect: DamageEffectId, multiplier: f64, flags: DamageFlags, ) -> bool

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

fn deal_item_damage_sp(&mut self, action: DamageActionId)

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

fn deal_damage_ap( &mut self, action: DamageActionId, coef: f64, flags: DamageFlags, )

fn deal_damage_ap_if_positive( &mut self, action: DamageActionId, coefficient: f64, flags: DamageFlags, )

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

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

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

fn deal_physical_damage_ap_if_positive( &mut self, action: DamageActionId, coefficient: f64, )

fn deal_pet_damage_ap(&mut self, action: DamageActionId, coefficient: f64)

fn deal_physical_pet_damage_ap( &mut self, action: DamageActionId, coefficient: f64, )

fn deal_damage_sp( &mut self, action: DamageActionId, coef: f64, flags: DamageFlags, )

fn deal_profiled_damage_sp( &mut self, action: DamageActionId, profile: DamageActionId, coef: f64, flags: DamageFlags, )

fn deal_damage_flat(&mut self, action: DamageActionId, amount: f64)

fn deal_hook_flat_damage(&mut self, action: DamageActionId) -> bool

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

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

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

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

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

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

fn effect_period_ms(&self, effect: DamageEffectId) -> u32

fn action_proc_chance(&self, action: DamageActionId) -> f64

fn action_gcd_ms(&self, action: DamageActionId) -> u32

fn action_aura_duration_ms(&self, action: DamageActionId) -> u32

fn action_aura_tick_ms(&self, action: DamageActionId) -> u32

fn action_secondary_gain(&self, action: DamageActionId) -> f64

fn action_hook_scalar(&self, action: DamageActionId) -> Option<f64>

fn action_passive_direct_damage_mult(&self, action: DamageActionId) -> f64

fn action_is_melee(&self, action: DamageActionId) -> bool

fn action_has_direct_damage(&self, action: DamageActionId) -> bool

fn action_requires_main_hand(&self, action: DamageActionId) -> bool

fn action_requires_off_hand(&self, action: DamageActionId) -> bool

fn action_suppresses_caster_procs(&self, action: DamageActionId) -> bool

fn impact_has_label(&self, impact: ImpactEvent, label: i32) -> bool

fn impact_is_physical(&self, impact: ImpactEvent) -> bool

fn impact_is_nature(&self, impact: ImpactEvent) -> bool

fn impact_generates_primary_resource(&self, impact: ImpactEvent) -> bool

fn effect_affects_impact( &self, effect: DamageEffectId, impact: ImpactEvent, ) -> bool

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, ) -> Result<GuardianHandle, GuardianSummonError>

Summons one guardian from the finalized specification.

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, binding: SystemRppmBinding) -> 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, binding: ProcCategoryBinding) -> bool

Whether a DBC proc driver is outside its ProcCategoryRecovery window.

fn start_proc_category_cooldown(&mut self, binding: ProcCategoryBinding)

Start the DBC ProcCategoryRecovery window for a proc driver.

fn roll_attempt_proc( &mut self, binding: ProcCounterBinding, 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, binding: ProcCounterBinding, amount: u32) -> u32

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

fn reset_proc_counter(&mut self, binding: ProcCounterBinding)

Clear a driver-scoped event counter.

fn proc_counter(&self, binding: ProcCounterBinding) -> u32

Read a driver-scoped event counter without changing it.

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

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

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

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

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

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

fn advance_proc_counter( &mut self, binding: ProcCounterBinding, 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_accumulating_proc( &mut self, binding: ProcCounterBinding, 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 primary_resource_max(&self) -> f64

fn primary_resource_fraction(&self) -> f64

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

fn primary_pet_resource(&self) -> Option<PetResourceBinding>

fn gain_pet_resource(&mut self, binding: PetResourceBinding, 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: LocalSpellIdx, 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: LocalSpellIdx, proc_driver: RppmBinding, 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: PeriodicDriverBinding) -> bool

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

fn trigger_periodic_driver_for( &mut self, driver: PeriodicDriverBinding, 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, effect: GroundEffectId) -> bool

Schedule a location-locked sequence of spatial damage pulses.