AbilityExecutor

AbilityExecutor runs validated ability graphs against Combatant / Stats instances.

Constructor

new AbilityExecutor(optionsopt)

Parameters:
NameTypeAttributesDescription
optionsObject<optional>
Properties
NameTypeAttributesDefaultDescription
maxOperationsPerTicknumber<optional>
1000

Operation budget per tick to prevent infinite processing

eventBusObject<optional>
null

Optional event bus for emitting presentation and lifecycle cues

actorsArray<optional>
[]

Default actor collection for target resolution

Classes

AbilityExecutor

Members

_cooldowns

Cooldowns map: Map<string, Map<string, number>> (casterId -> abilityId -> remainingSeconds)

_instances

Active execution instances: Map<number, Object>

_listeners

Event listeners: Map<string, Set>

Methods

_advanceSequence()

Advance a pending sequence until completion or until paused by an active delay.

_cancelInstance(instance, reason)

Internal helper to cancel an instance cleanly.

Parameters:
NameTypeDescription
instanceObject
reasonstring

_consumeOperation(instance)

Consume an operation from the execution budget.

Parameters:
NameTypeDescription
instanceObject

_emit(event, payload)

Emit an event to local listeners and optional external event bus.

Parameters:
NameTypeDescription
eventstring
payloadObject

_executeAreaEffectNode()

Execute 'area_effect' node: finds targets within radius and triggers onHit on them.

_executeConditionNode()

Execute 'condition' node: branches to onTrue or onFalse based on check result.

_executeDamageNode()

Execute 'damage' node: applies damage to target Combatant / Stats.

_executeFilterNode()

Execute 'filter' node: filters current targets by faction, type, and maxTargets.

_executeHealNode()

Execute 'heal' node: applies healing to target Combatant / Stats.

_executeKnockbackNode()

Execute 'knockback' node: applies knockback to targets.

_executeNode(instance, nodeId)

Execute a single node in the ability graph.

Parameters:
NameTypeDescription
instanceObject
nodeIdstring

_executePresentationNode()

Execute 'presentation' node: emits presentation cues via event bus.

_executeProjectileNode()

Execute 'projectile' node: launches a simulated projectile traveling toward cursor/target.

_executeSequenceNode()

Execute 'sequence' node: steps through child nodes sequentially, pausing on delays.

_executeStatusNode()

Execute 'status' node: applies status effect to targets.

_executeTargetNode()

Execute 'target' node: resolves target actors (caster, enemies, allies, cursor, cone, radius).

_executeTimedActionNode()

Execute 'timed_action' node: registers a delay and pauses execution flow.

_getCandidateActors(instance) → {Array}

Collect candidate actors for targeting from context and executor defaults.

Parameters:
NameTypeDescription
instanceObject
Returns:
Type: 
Array

_isInstanceFinished(instance) → {boolean}

Helper to determine whether an execution instance has completed all active work.

Parameters:
NameTypeDescription
instanceObject
Returns:
Type: 
boolean

cancelAll(reasonopt) → {number}

Cancel all running executions across all casters.

Parameters:
NameTypeAttributesDefaultDescription
reasonstring<optional>
"cancelled"
Returns:

Number of instances cancelled

Type: 
number

cancelByCaster(casterId, reasonopt) → {number}

Cancel all running executions for a specific caster.

Parameters:
NameTypeAttributesDefaultDescription
casterIdstring
reasonstring<optional>
"cancelled"
Returns:

Number of instances cancelled

Type: 
number

cast(abilityDef, contextopt) → {Object}

Alias for execute().

Parameters:
NameTypeAttributesDescription
abilityDefObject
contextObject<optional>
Returns:
Type: 
Object

execute(abilityDef, contextopt) → {Object}

Execute an ability graph definition against an execution context. Validates the graph, enforces cooldowns and caster survival, and steps execution.

Parameters:
NameTypeAttributesDefaultDescription
abilityDefObject

Validated or validatable ability definition graph

contextObject<optional>
{}

Execution context (caster, target, targets, cursor, world, actors)

Returns:

Execution result { success, instance, status, reason }

Type: 
Object

getActiveInstances(casterIdopt) → {Array}

Get all active execution instances, optionally filtered by caster ID.

Parameters:
NameTypeAttributesDescription
casterIdstring<optional>
Returns:
Type: 
Array

getCooldown(casterId, abilityId) → {number}

Get the remaining cooldown time for an ability and caster in seconds.

Parameters:
NameTypeDescription
casterIdstring
abilityIdstring
Returns:

Remaining cooldown in seconds, or 0

Type: 
number

isOnCooldown(casterId, abilityId) → {boolean}

Check if an ability is currently on cooldown for a given caster.

Parameters:
NameTypeDescription
casterIdstring
abilityIdstring
Returns:
Type: 
boolean

off(event, listener) → {boolean}

Remove an event listener.

Parameters:
NameTypeDescription
eventstring
listenerfunction
Returns:
Type: 
boolean

on(event, listener) → {function}

Subscribe to executor events.

Parameters:
NameTypeDescription
eventstring
listenerfunction
Returns:

Unsubscribe function

Type: 
function

resetAllCooldowns()

Reset all tracked cooldowns across all casters.

resetCooldown(casterId, abilityId)

Reset cooldown for a specific caster and ability.

Parameters:
NameTypeDescription
casterIdstring
abilityIdstring

setCooldown(casterId, abilityId, duration)

Set a cooldown duration for a caster and ability.

Parameters:
NameTypeDescription
casterIdstring
abilityIdstring
durationnumber

Cooldown in seconds

update(deltaTime)

Advance simulation time for all active executions and cooldowns. Enforces caster death cancellation and operation budgets.

Parameters:
NameTypeDefaultDescription
deltaTimenumber0

Time step in seconds