/**
* Larissa RPG System - Ability Graph Executor
* ABILITY-02: Budgeted execution, cancellation, targeting, timing,
* and presentation dispatch for validated ability definition graphs.
*/
import { AbilityValidator } from "./abilityValidator.js";
/**
* Error thrown when an ability execution exceeds its per-tick operation budget.
*/
export class AbilityBudgetExceededError extends Error {
/**
* @param {string} [message]
*/
constructor(message = "Execution operation budget exceeded") {
super(message);
this.name = "AbilityBudgetExceededError";
}
}
/**
* General error thrown during ability execution failures.
*/
export class AbilityExecutionError extends Error {
/**
* @param {string} [message]
* @param {Object} [context]
*/
constructor(message = "Ability execution failed", context = {}) {
super(message);
this.name = "AbilityExecutionError";
this.context = context;
}
}
/**
* Helper to check whether an actor is alive.
* @param {Object} actor
* @returns {boolean}
*/
function isActorAlive(actor) {
if (!actor) return false;
if (typeof actor.isAlive === "boolean") return actor.isAlive;
if (typeof actor.isAlive === "function") return actor.isAlive();
if (actor.isDestroyed) return false;
if (typeof actor.health === "number") return actor.health > 0;
if (typeof actor._health === "number") return actor._health > 0;
return true;
}
/**
* Helper to get 2D position from an actor or position object.
* @param {Object} actor
* @returns {{ x: number, y: number }}
*/
function getActorPosition(actor) {
if (!actor) return { x: 0, y: 0 };
if (actor.position && Number.isFinite(actor.position.x) && Number.isFinite(actor.position.y)) {
return { x: actor.position.x, y: actor.position.y };
}
if (Number.isFinite(actor.x) && Number.isFinite(actor.y)) {
return { x: actor.x, y: actor.y };
}
return { x: 0, y: 0 };
}
/**
* Helper to normalize an angle between -PI and PI.
* @param {number} angle
* @returns {number}
*/
function normalizeAngle(angle) {
while (angle > Math.PI) angle -= 2 * Math.PI;
while (angle < -Math.PI) angle += 2 * Math.PI;
return angle;
}
/**
* Lookup a node in ability definition nodes by id.
* Supports both Map/Object map and Array schemas.
* @param {Object} abilityDef
* @param {string} nodeId
* @returns {Object|null}
*/
function getNode(abilityDef, nodeId) {
if (!abilityDef || !abilityDef.nodes || !nodeId) return null;
if (Array.isArray(abilityDef.nodes)) {
return abilityDef.nodes.find(function (item) {
return item && item.id === nodeId;
}) || null;
}
if (typeof abilityDef.nodes === "object") {
return abilityDef.nodes[nodeId] || null;
}
return null;
}
/**
* AbilityExecutor runs validated ability graphs against Combatant / Stats instances.
*/
export class AbilityExecutor {
/**
* @param {Object} [options]
* @param {number} [options.maxOperationsPerTick=1000] - Operation budget per tick to prevent infinite processing
* @param {Object} [options.eventBus=null] - Optional event bus for emitting presentation and lifecycle cues
* @param {Array} [options.actors=[]] - Default actor collection for target resolution
*/
constructor(options = {}) {
this.maxOperationsPerTick = Number.isFinite(options.maxOperationsPerTick) && options.maxOperationsPerTick > 0
? options.maxOperationsPerTick
: 1000;
this.eventBus = options.eventBus || null;
this.actors = Array.isArray(options.actors) ? options.actors : [];
/** Active execution instances: Map<number, Object> */
this._instances = new Map();
/** Cooldowns map: Map<string, Map<string, number>> (casterId -> abilityId -> remainingSeconds) */
this._cooldowns = new Map();
/** Event listeners: Map<string, Set<Function>> */
this._listeners = new Map();
this._serial = 1;
this._operationsInCurrentTick = 0;
}
/**
* Subscribe to executor events.
* @param {string} event
* @param {Function} listener
* @returns {Function} Unsubscribe function
*/
on(event, listener) {
if (typeof event !== "string" || !event || typeof listener !== "function") {
throw new TypeError("AbilityExecutor.on requires an event string and a listener function");
}
if (!this._listeners.has(event)) {
this._listeners.set(event, new Set());
}
this._listeners.get(event).add(listener);
const self = this;
return function () {
const set = self._listeners.get(event);
if (set) set.delete(listener);
};
}
/**
* Remove an event listener.
* @param {string} event
* @param {Function} listener
* @returns {boolean}
*/
off(event, listener) {
const set = this._listeners.get(event);
if (!set) return false;
return set.delete(listener);
}
/**
* Emit an event to local listeners and optional external event bus.
* @param {string} event
* @param {Object} payload
*/
_emit(event, payload = {}) {
const listeners = this._listeners.get(event);
if (listeners && listeners.size > 0) {
for (const listener of Array.from(listeners)) {
try {
listener(payload);
} catch (err) {
console.error(`Error in AbilityExecutor listener for '${event}':`, err);
}
}
}
if (this.eventBus && typeof this.eventBus.emit === "function") {
try {
this.eventBus.emit(event, payload);
} catch (err) {
console.error(`Error emitting to eventBus for '${event}':`, err);
}
}
}
/**
* Consume an operation from the execution budget.
* @param {Object} instance
*/
_consumeOperation(instance) {
this._operationsInCurrentTick++;
if (this._operationsInCurrentTick > this.maxOperationsPerTick) {
if (instance) {
instance.status = "failed";
instance.cancelReason = "budget_exceeded";
this._instances.delete(instance.id);
}
throw new AbilityBudgetExceededError(
`Execution operation budget of ${this.maxOperationsPerTick} exceeded in tick`
);
}
}
/**
* Check if an ability is currently on cooldown for a given caster.
* @param {string} casterId
* @param {string} abilityId
* @returns {boolean}
*/
isOnCooldown(casterId, abilityId) {
return this.getCooldown(casterId, abilityId) > 0;
}
/**
* Get the remaining cooldown time for an ability and caster in seconds.
* @param {string} casterId
* @param {string} abilityId
* @returns {number} Remaining cooldown in seconds, or 0
*/
getCooldown(casterId, abilityId) {
if (!casterId || !abilityId) return 0;
const casterMap = this._cooldowns.get(casterId);
if (!casterMap) return 0;
return casterMap.get(abilityId) || 0;
}
/**
* Set a cooldown duration for a caster and ability.
* @param {string} casterId
* @param {string} abilityId
* @param {number} duration - Cooldown in seconds
*/
setCooldown(casterId, abilityId, duration) {
if (!casterId || !abilityId) return;
if (typeof duration !== "number" || !Number.isFinite(duration) || duration <= 0) {
this.resetCooldown(casterId, abilityId);
return;
}
if (!this._cooldowns.has(casterId)) {
this._cooldowns.set(casterId, new Map());
}
this._cooldowns.get(casterId).set(abilityId, duration);
}
/**
* Reset cooldown for a specific caster and ability.
* @param {string} casterId
* @param {string} abilityId
*/
resetCooldown(casterId, abilityId) {
const casterMap = this._cooldowns.get(casterId);
if (casterMap) {
casterMap.delete(abilityId);
if (casterMap.size === 0) {
this._cooldowns.delete(casterId);
}
}
}
/**
* Reset all tracked cooldowns across all casters.
*/
resetAllCooldowns() {
this._cooldowns.clear();
}
/**
* Get all active execution instances, optionally filtered by caster ID.
* @param {string} [casterId]
* @returns {Array}
*/
getActiveInstances(casterId) {
const list = Array.from(this._instances.values());
if (casterId) {
return list.filter(function (inst) {
return inst.casterId === casterId;
});
}
return list;
}
/**
* Cancel all running executions across all casters.
* @param {string} [reason="cancelled"]
* @returns {number} Number of instances cancelled
*/
cancelAll(reason = "cancelled") {
let count = 0;
for (const instance of Array.from(this._instances.values())) {
this._cancelInstance(instance, reason);
count++;
}
return count;
}
/**
* Cancel all running executions for a specific caster.
* @param {string} casterId
* @param {string} [reason="cancelled"]
* @returns {number} Number of instances cancelled
*/
cancelByCaster(casterId, reason = "cancelled") {
if (!casterId) return 0;
let count = 0;
for (const instance of Array.from(this._instances.values())) {
if (instance.casterId === casterId) {
this._cancelInstance(instance, reason);
count++;
}
}
return count;
}
/**
* Internal helper to cancel an instance cleanly.
* @param {Object} instance
* @param {string} reason
*/
_cancelInstance(instance, reason) {
instance.status = "cancelled";
instance.cancelReason = reason;
instance.activeTimedActions = [];
instance.activeProjectiles = [];
instance.pendingSequences = [];
this._instances.delete(instance.id);
this._emit("ability:cancelled", { instance, reason, casterId: instance.casterId, abilityId: instance.abilityDef.id });
}
/**
* Execute an ability graph definition against an execution context.
* Validates the graph, enforces cooldowns and caster survival, and steps execution.
* @param {Object} abilityDef - Validated or validatable ability definition graph
* @param {Object} [context={}] - Execution context (caster, target, targets, cursor, world, actors)
* @returns {Object} Execution result { success, instance, status, reason }
*/
execute(abilityDef, context = {}) {
// 1. Validate ability definition graph
AbilityValidator.assertValid(abilityDef);
const caster = context.caster || null;
const casterId = caster && caster.id
? caster.id
: (typeof caster === "string" ? caster : (context.casterId || "caster"));
// 2. Caster death check
if (caster && !isActorAlive(caster)) {
return {
success: false,
reason: "caster_dead",
status: "failed",
instance: null
};
}
// 3. Cooldown check
const cooldownDuration = Number.isFinite(abilityDef.cooldown) && abilityDef.cooldown > 0
? abilityDef.cooldown
: (Number.isFinite(context.cooldown) && context.cooldown > 0 ? context.cooldown : 0);
if (cooldownDuration > 0 && this.isOnCooldown(casterId, abilityDef.id)) {
return {
success: false,
reason: "cooldown",
status: "blocked",
remainingCooldown: this.getCooldown(casterId, abilityDef.id),
instance: null
};
}
// Apply cooldown
if (cooldownDuration > 0) {
this.setCooldown(casterId, abilityDef.id, cooldownDuration);
if (caster && caster.cooldowns instanceof Map) {
caster.cooldowns.set(abilityDef.id, cooldownDuration);
}
}
// Reset operation budget counter for this tick
this._operationsInCurrentTick = 0;
// 4. Create execution instance
const initialTargets = context.targets
? context.targets.filter(Boolean)
: (context.target ? [context.target] : []);
const instance = {
id: this._serial++,
abilityDef,
caster,
casterId,
context: { ...context },
status: "running",
cancelReason: null,
currentTargets: initialTargets,
cursor: context.cursor ? { x: context.cursor.x, y: context.cursor.y } : null,
impactPoint: null,
targetPoint: null,
activeTimedActions: [],
activeProjectiles: [],
pendingSequences: []
};
this._instances.set(instance.id, instance);
this._emit("ability:start", { instance, caster, abilityId: abilityDef.id });
// 5. Begin graph execution at entry node
this._executeNode(instance, abilityDef.entryNodeId);
// Check completion status
if (this._isInstanceFinished(instance)) {
instance.status = "completed";
this._instances.delete(instance.id);
this._emit("ability:completed", { instance, caster, abilityId: abilityDef.id });
}
return {
success: true,
instance,
status: instance.status
};
}
/**
* Alias for execute().
* @param {Object} abilityDef
* @param {Object} [context]
* @returns {Object}
*/
cast(abilityDef, context) {
return this.execute(abilityDef, context);
}
/**
* Helper to determine whether an execution instance has completed all active work.
* @param {Object} instance
* @returns {boolean}
*/
_isInstanceFinished(instance) {
if (instance.status !== "running") return true;
return instance.activeTimedActions.length === 0 &&
instance.activeProjectiles.length === 0 &&
instance.pendingSequences.length === 0;
}
/**
* Execute a single node in the ability graph.
* @param {Object} instance
* @param {string} nodeId
*/
_executeNode(instance, nodeId) {
if (!nodeId || instance.status !== "running") return;
// Verify caster is still alive before executing next node
if (instance.caster && !isActorAlive(instance.caster)) {
this._cancelInstance(instance, "caster_death");
return;
}
this._consumeOperation(instance);
const node = getNode(instance.abilityDef, nodeId);
if (!node) {
// Missing node reference handled safely
return;
}
switch (node.type) {
case "target":
this._executeTargetNode(instance, node, nodeId);
break;
case "filter":
this._executeFilterNode(instance, node, nodeId);
break;
case "sequence":
this._executeSequenceNode(instance, node, nodeId);
break;
case "condition":
this._executeConditionNode(instance, node, nodeId);
break;
case "projectile":
this._executeProjectileNode(instance, node, nodeId);
break;
case "area_effect":
this._executeAreaEffectNode(instance, node, nodeId);
break;
case "damage":
this._executeDamageNode(instance, node, nodeId);
break;
case "heal":
this._executeHealNode(instance, node, nodeId);
break;
case "status":
this._executeStatusNode(instance, node, nodeId);
break;
case "knockback":
this._executeKnockbackNode(instance, node, nodeId);
break;
case "timed_action":
this._executeTimedActionNode(instance, node, nodeId);
break;
case "presentation":
this._executePresentationNode(instance, node, nodeId);
break;
default:
// Unknown node type - continue to next if available
if (node.next) this._executeNode(instance, node.next);
break;
}
}
/**
* Collect candidate actors for targeting from context and executor defaults.
* @param {Object} instance
* @returns {Array}
*/
_getCandidateActors(instance) {
const set = new Set();
const ctx = instance.context;
if (Array.isArray(ctx.actors)) {
for (const a of ctx.actors) if (a) set.add(a);
}
if (ctx.world) {
if (typeof ctx.world.getActors === "function") {
const actors = ctx.world.getActors();
if (Array.isArray(actors)) for (const a of actors) if (a) set.add(a);
} else if (Array.isArray(ctx.world.actors)) {
for (const a of ctx.world.actors) if (a) set.add(a);
}
}
if (Array.isArray(ctx.targets)) {
for (const t of ctx.targets) if (t) set.add(t);
}
if (ctx.target) set.add(ctx.target);
if (Array.isArray(this.actors)) {
for (const a of this.actors) if (a) set.add(a);
}
return Array.from(set);
}
/**
* Execute 'target' node: resolves target actors (caster, enemies, allies, cursor, cone, radius).
*/
_executeTargetNode(instance, node, nodeId) {
const mode = (node.mode || node.targetType || "cursor").toLowerCase();
const caster = instance.caster;
const casterPos = getActorPosition(caster);
const candidateActors = this._getCandidateActors(instance);
let resolvedTargets = [];
switch (mode) {
case "self":
case "caster": {
if (caster) resolvedTargets = [caster];
break;
}
case "cursor":
case "point": {
const cursor = instance.context.cursor || instance.cursor || instance.context.targetPosition || { x: 0, y: 0 };
let targetX = cursor.x;
let targetY = cursor.y;
if (Number.isFinite(node.range) && node.range > 0) {
const dx = targetX - casterPos.x;
const dy = targetY - casterPos.y;
const dist = Math.hypot(dx, dy);
if (dist > node.range && dist > 0) {
targetX = casterPos.x + (dx / dist) * node.range;
targetY = casterPos.y + (dy / dist) * node.range;
}
}
instance.cursor = { x: targetX, y: targetY };
instance.targetPoint = { x: targetX, y: targetY };
resolvedTargets = [];
break;
}
case "cone": {
const range = Number.isFinite(node.range) ? node.range : 64;
const angleDeg = Number.isFinite(node.angle) ? node.angle : 90;
const halfAngleRad = (angleDeg * Math.PI) / 360; // (deg / 2) * (PI / 180)
// Aim direction
let aimDirX = 1;
let aimDirY = 0;
if (instance.context.aim && Number.isFinite(instance.context.aim.x) && Number.isFinite(instance.context.aim.y)) {
aimDirX = instance.context.aim.x;
aimDirY = instance.context.aim.y;
} else if (instance.context.cursor || instance.cursor) {
const c = instance.context.cursor || instance.cursor;
const dx = c.x - casterPos.x;
const dy = c.y - casterPos.y;
const len = Math.hypot(dx, dy);
if (len > 0) {
aimDirX = dx / len;
aimDirY = dy / len;
}
}
const aimAngle = Math.atan2(aimDirY, aimDirX);
for (const actor of candidateActors) {
if (!isActorAlive(actor) || actor === caster) continue;
const pos = getActorPosition(actor);
const dx = pos.x - casterPos.x;
const dy = pos.y - casterPos.y;
const dist = Math.hypot(dx, dy);
if (dist <= range) {
if (dist === 0) {
resolvedTargets.push(actor);
} else {
const actorAngle = Math.atan2(dy, dx);
const diff = Math.abs(normalizeAngle(actorAngle - aimAngle));
if (diff <= halfAngleRad) {
resolvedTargets.push(actor);
}
}
}
}
break;
}
case "radius":
case "area": {
const radius = Number.isFinite(node.radius) ? node.radius : (Number.isFinite(node.range) ? node.range : 48);
const center = instance.targetPoint || instance.cursor || casterPos;
for (const actor of candidateActors) {
if (!isActorAlive(actor)) continue;
if (actor === caster && node.affectCaster !== true) continue;
const pos = getActorPosition(actor);
const dist = Math.hypot(pos.x - center.x, pos.y - center.y);
if (dist <= radius) {
resolvedTargets.push(actor);
}
}
break;
}
case "nearest_enemy":
case "enemy":
case "hostile": {
const casterFaction = caster ? (caster.faction || "player") : "player";
const range = Number.isFinite(node.range) ? node.range : Infinity;
let closest = null;
let minDist = Infinity;
for (const actor of candidateActors) {
if (!isActorAlive(actor) || actor === caster) continue;
const actorFaction = actor.faction || "neutral";
if (actorFaction !== casterFaction) {
const pos = getActorPosition(actor);
const dist = Math.hypot(pos.x - casterPos.x, pos.y - casterPos.y);
if (dist <= range && dist < minDist) {
minDist = dist;
closest = actor;
}
}
}
if (closest) resolvedTargets = [closest];
break;
}
case "nearest_ally":
case "ally":
case "friendly": {
const casterFaction = caster ? (caster.faction || "player") : "player";
const range = Number.isFinite(node.range) ? node.range : Infinity;
let closest = null;
let minDist = Infinity;
for (const actor of candidateActors) {
if (!isActorAlive(actor) || actor === caster) continue;
const actorFaction = actor.faction || "player";
if (actorFaction === casterFaction) {
const pos = getActorPosition(actor);
const dist = Math.hypot(pos.x - casterPos.x, pos.y - casterPos.y);
if (dist <= range && dist < minDist) {
minDist = dist;
closest = actor;
}
}
}
if (closest) resolvedTargets = [closest];
break;
}
case "allies": {
const casterFaction = caster ? (caster.faction || "player") : "player";
const range = Number.isFinite(node.range) ? node.range : Infinity;
for (const actor of candidateActors) {
if (!isActorAlive(actor)) continue;
const actorFaction = actor.faction || "player";
if (actorFaction === casterFaction) {
const pos = getActorPosition(actor);
const dist = Math.hypot(pos.x - casterPos.x, pos.y - casterPos.y);
if (dist <= range) resolvedTargets.push(actor);
}
}
break;
}
case "enemies": {
const casterFaction = caster ? (caster.faction || "player") : "player";
const range = Number.isFinite(node.range) ? node.range : Infinity;
for (const actor of candidateActors) {
if (!isActorAlive(actor) || actor === caster) continue;
const actorFaction = actor.faction || "neutral";
if (actorFaction !== casterFaction) {
const pos = getActorPosition(actor);
const dist = Math.hypot(pos.x - casterPos.x, pos.y - casterPos.y);
if (dist <= range) resolvedTargets.push(actor);
}
}
break;
}
default: {
// Fallback: candidate targets
resolvedTargets = candidateActors.filter(function (a) {
return a !== caster && isActorAlive(a);
});
break;
}
}
if (Number.isInteger(node.maxTargets) && node.maxTargets > 0) {
resolvedTargets = resolvedTargets.slice(0, node.maxTargets);
}
if (resolvedTargets.length > 0 || mode === "self" || mode === "caster") {
instance.currentTargets = resolvedTargets;
}
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Execute 'filter' node: filters current targets by faction, type, and maxTargets.
*/
_executeFilterNode(instance, node, nodeId) {
const caster = instance.caster;
const casterFaction = caster ? (caster.faction || "player") : "player";
const filterType = (node.targetType || "enemy").toLowerCase();
let filtered = [];
for (const target of instance.currentTargets) {
if (!isActorAlive(target)) continue;
const targetFaction = target.faction || "neutral";
if (filterType === "enemy" || filterType === "hostile" || filterType === "enemies") {
if (target !== caster && targetFaction !== casterFaction) {
filtered.push(target);
}
} else if (filterType === "ally" || filterType === "friendly" || filterType === "allies") {
if (targetFaction === casterFaction) {
filtered.push(target);
}
} else if (filterType === "self") {
if (target === caster) {
filtered.push(target);
}
} else {
filtered.push(target);
}
}
if (Number.isInteger(node.maxTargets) && node.maxTargets > 0) {
filtered = filtered.slice(0, node.maxTargets);
}
instance.currentTargets = filtered;
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Execute 'sequence' node: steps through child nodes sequentially, pausing on delays.
*/
_executeSequenceNode(instance, node, nodeId) {
if (!Array.isArray(node.children) || node.children.length === 0) {
if (node.next) this._executeNode(instance, node.next);
return;
}
const sequenceState = {
sequenceNodeId: nodeId,
children: node.children.slice(),
nextChildIndex: 0,
next: node.next || null
};
instance.pendingSequences.push(sequenceState);
this._advanceSequence(instance, sequenceState);
}
/**
* Advance a pending sequence until completion or until paused by an active delay.
*/
_advanceSequence(instance, sequenceState) {
while (sequenceState.nextChildIndex < sequenceState.children.length) {
if (instance.status !== "running") return;
const childId = sequenceState.children[sequenceState.nextChildIndex];
sequenceState.nextChildIndex++;
this._executeNode(instance, childId);
// If executing the child created an active delay, pause sequence advancement
if (instance.activeTimedActions.length > 0) {
return;
}
}
// All children executed
const idx = instance.pendingSequences.indexOf(sequenceState);
if (idx !== -1) {
instance.pendingSequences.splice(idx, 1);
}
if (sequenceState.next) {
this._executeNode(instance, sequenceState.next);
}
}
/**
* Execute 'condition' node: branches to onTrue or onFalse based on check result.
*/
_executeConditionNode(instance, node, nodeId) {
const target = instance.currentTargets[0] || instance.caster || null;
const check = (node.check || "").toLowerCase();
let result = false;
if (check === "health_below_max") {
if (target) {
const health = target.health ?? target._health ?? 100;
const maxHealth = target.maxHealth ?? target._maxHealth ?? 100;
result = health < maxHealth;
}
} else if (check === "is_alive") {
result = isActorAlive(target);
} else if (check === "health_at_max" || check === "health_full") {
if (target) {
const health = target.health ?? target._health ?? 100;
const maxHealth = target.maxHealth ?? target._maxHealth ?? 100;
result = health >= maxHealth;
}
} else if (check === "has_status") {
if (target && Array.isArray(target.effects)) {
const statusName = node.statusName || node.name || "";
result = target.effects.some(function (e) {
return e && e.name === statusName;
});
}
} else if (instance.context.conditions && typeof instance.context.conditions[node.check] === "function") {
result = Boolean(instance.context.conditions[node.check](instance, target, node));
} else if (typeof node.evaluate === "function") {
result = Boolean(node.evaluate(instance, target, node));
}
const nextNodeId = result
? (node.onTrue || node.next || null)
: (node.onFalse || node.next || null);
if (nextNodeId) {
this._executeNode(instance, nextNodeId);
}
}
/**
* Execute 'timed_action' node: registers a delay and pauses execution flow.
*/
_executeTimedActionNode(instance, node, nodeId) {
const duration = Number.isFinite(node.duration)
? node.duration
: (Number.isFinite(node.delay) ? node.delay : 0);
if (duration <= 0) {
if (node.next) this._executeNode(instance, node.next);
return;
}
instance.activeTimedActions.push({
nodeId,
remaining: duration,
next: node.next || null
});
this._emit("ability:delay_start", {
instance,
nodeId,
duration,
abilityId: instance.abilityDef.id
});
}
/**
* Execute 'projectile' node: launches a simulated projectile traveling toward cursor/target.
*/
_executeProjectileNode(instance, node, nodeId) {
const caster = instance.caster;
const origin = getActorPosition(caster);
const speed = Number.isFinite(node.speed) ? node.speed : (Number.isFinite(node.projectileSpeed) ? node.projectileSpeed : 300);
const maxRange = Number.isFinite(node.range) ? node.range : (Number.isFinite(node.maxDistance) ? node.maxDistance : 400);
const radius = Number.isFinite(node.radius) ? node.radius : (Number.isFinite(node.size) ? node.size : 8);
// Direction resolution
const cursor = instance.cursor || instance.context.cursor || { x: origin.x + 100, y: origin.y };
const dx = cursor.x - origin.x;
const dy = cursor.y - origin.y;
const distToCursor = Math.hypot(dx, dy);
let dirX = 1;
let dirY = 0;
if (distToCursor > 0) {
dirX = dx / distToCursor;
dirY = dy / distToCursor;
}
// Target flight distance: to cursor (capped by maxRange) or full maxRange
const targetFlightDistance = distToCursor > 0 ? Math.min(distToCursor, maxRange) : maxRange;
const projectile = {
id: this._serial++,
nodeId,
onHit: node.onHit || null,
next: node.next || null,
speed,
maxDistance: targetFlightDistance,
radius,
x: origin.x,
y: origin.y,
dirX,
dirY,
travelled: 0,
hitTargets: new Set()
};
instance.activeProjectiles.push(projectile);
this._emit("projectile", {
instance,
projectile,
caster,
abilityId: instance.abilityDef.id
});
this._emit("ability:projectile_spawn", {
instance,
projectile,
caster,
abilityId: instance.abilityDef.id
});
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Execute 'area_effect' node: finds targets within radius and triggers onHit on them.
*/
_executeAreaEffectNode(instance, node, nodeId) {
const radius = Number.isFinite(node.radius) ? node.radius : 48;
const center = instance.impactPoint || instance.targetPoint || instance.cursor || getActorPosition(instance.caster);
const candidateActors = this._getCandidateActors(instance);
const affectedTargets = [];
for (const actor of candidateActors) {
if (!isActorAlive(actor)) continue;
if (actor === instance.caster && node.affectCaster !== true) continue;
const pos = getActorPosition(actor);
const dist = Math.hypot(pos.x - center.x, pos.y - center.y);
if (dist <= radius) {
affectedTargets.push(actor);
}
}
instance.currentTargets = affectedTargets;
this._emit("ability:area_effect", {
instance,
center,
radius,
targets: affectedTargets,
abilityId: instance.abilityDef.id
});
if (node.onHit) {
this._executeNode(instance, node.onHit);
}
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Execute 'damage' node: applies damage to target Combatant / Stats.
*/
_executeDamageNode(instance, node, nodeId) {
const rawAmount = Number.isFinite(node.amount)
? node.amount
: (Number.isFinite(node.damage) ? node.damage : (Number.isFinite(node.value) ? node.value : 0));
const damageType = node.damageType || "physical";
const multiplier = Number.isFinite(node.multiplier) ? node.multiplier : 1;
let finalAmount = rawAmount * multiplier;
if (Number.isFinite(node.criticalChance) && node.criticalChance > 0) {
if (Math.random() < node.criticalChance) {
finalAmount *= Number.isFinite(node.criticalMultiplier) ? node.criticalMultiplier : 2;
}
}
// Missing target safety: handles empty or destroyed targets gracefully
for (const target of instance.currentTargets) {
if (!isActorAlive(target)) continue;
let damageDealt = 0;
let killed = false;
if (typeof target.receiveDamage === "function") {
const result = target.receiveDamage({ amount: finalAmount, type: damageType });
damageDealt = result?.damage ?? finalAmount;
killed = Boolean(result?.killed || !target.isAlive);
} else if (typeof target.takeDamage === "function") {
damageDealt = target.takeDamage(finalAmount);
killed = Boolean(!target.isAlive || target.health <= 0);
} else if (target && typeof target.health === "number") {
const prev = target.health;
target.health = Math.max(0, target.health - finalAmount);
damageDealt = prev - target.health;
killed = target.health === 0;
}
this._emit("damage", {
caster: instance.caster,
target,
amount: damageDealt,
damageType,
killed,
abilityId: instance.abilityDef.id
});
this._emit("ability:damage", {
caster: instance.caster,
target,
amount: damageDealt,
damageType,
killed,
abilityId: instance.abilityDef.id
});
}
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Execute 'heal' node: applies healing to target Combatant / Stats.
*/
_executeHealNode(instance, node, nodeId) {
const rawAmount = Number.isFinite(node.amount)
? node.amount
: (Number.isFinite(node.heal) ? node.heal : (Number.isFinite(node.value) ? node.value : 0));
const multiplier = Number.isFinite(node.multiplier) ? node.multiplier : 1;
const healAmount = rawAmount * multiplier;
for (const target of instance.currentTargets) {
if (!isActorAlive(target)) continue;
let healed = 0;
if (typeof target.heal === "function") {
healed = target.heal(healAmount);
} else if (target && typeof target.health === "number") {
const max = target.maxHealth ?? target._maxHealth ?? target.health;
const prev = target.health;
target.health = Math.min(max, target.health + healAmount);
healed = target.health - prev;
}
this._emit("heal", {
caster: instance.caster,
target,
amount: healed,
abilityId: instance.abilityDef.id
});
this._emit("ability:heal", {
caster: instance.caster,
target,
amount: healed,
abilityId: instance.abilityDef.id
});
}
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Execute 'status' node: applies status effect to targets.
*/
_executeStatusNode(instance, node, nodeId) {
const statusName = node.name || node.effect || node.status || "effect";
const duration = Number.isFinite(node.duration) ? node.duration : 1;
const modifiers = (node.modifiers && typeof node.modifiers === "object") ? node.modifiers : {};
const effect = {
name: statusName,
duration,
stacks: Number.isInteger(node.stacks) ? node.stacks : 1,
modifiers
};
for (const target of instance.currentTargets) {
if (!isActorAlive(target)) continue;
if (typeof target.applyEffect === "function") {
target.applyEffect(effect);
} else if (Array.isArray(target.effects)) {
const existing = target.effects.find(function (e) {
return e && e.name === statusName;
});
if (existing) {
existing.duration = Math.max(existing.duration, duration);
if (effect.modifiers) existing.modifiers = { ...existing.modifiers, ...effect.modifiers };
} else {
target.effects.push({ ...effect });
}
}
this._emit("status", {
caster: instance.caster,
target,
effect,
abilityId: instance.abilityDef.id
});
this._emit("ability:status", {
caster: instance.caster,
target,
effect,
abilityId: instance.abilityDef.id
});
}
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Execute 'knockback' node: applies knockback to targets.
*/
_executeKnockbackNode(instance, node, nodeId) {
const force = Number.isFinite(node.force)
? node.force
: (Number.isFinite(node.distance) ? node.distance : (Number.isFinite(node.speed) ? node.speed : 100));
const duration = Number.isFinite(node.duration) ? node.duration : 0.2;
const caster = instance.caster;
const casterPos = getActorPosition(caster);
const dirMode = node.direction || "away_from_caster";
for (const target of instance.currentTargets) {
if (!isActorAlive(target) || target === caster) continue;
const targetPos = getActorPosition(target);
let dirX = 1;
let dirY = 0;
if (typeof dirMode === "object" && dirMode && Number.isFinite(dirMode.x) && Number.isFinite(dirMode.y)) {
const len = Math.hypot(dirMode.x, dirMode.y);
if (len > 0) {
dirX = dirMode.x / len;
dirY = dirMode.y / len;
}
} else if (dirMode === "towards_caster") {
const dx = casterPos.x - targetPos.x;
const dy = casterPos.y - targetPos.y;
const len = Math.hypot(dx, dy);
if (len > 0) {
dirX = dx / len;
dirY = dy / len;
}
} else {
// "away_from_caster"
const dx = targetPos.x - casterPos.x;
const dy = targetPos.y - casterPos.y;
const len = Math.hypot(dx, dy);
if (len > 0) {
dirX = dx / len;
dirY = dy / len;
}
}
const kx = dirX * force;
const ky = dirY * force;
if (target.body && typeof target.body.applyKnockback === "function") {
target.body.applyKnockback(kx, ky);
} else if (typeof target.applyKnockback === "function") {
target.applyKnockback(kx, ky);
} else if (target.position && Number.isFinite(target.position.x) && Number.isFinite(target.position.y)) {
target.position.x += kx * duration;
target.position.y += ky * duration;
}
target.lastKnockback = { x: kx, y: ky, force, direction: { x: dirX, y: dirY } };
this._emit("knockback", {
caster,
target,
force,
direction: { x: dirX, y: dirY },
abilityId: instance.abilityDef.id
});
this._emit("ability:knockback", {
caster,
target,
force,
direction: { x: dirX, y: dirY },
abilityId: instance.abilityDef.id
});
}
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Execute 'presentation' node: emits presentation cues via event bus.
*/
_executePresentationNode(instance, node, nodeId) {
const cue = node.cue || node.name || nodeId;
const duration = Number.isFinite(node.duration) ? node.duration : 0;
const payload = {
type: "presentation",
nodeId,
cue,
duration,
abilityId: instance.abilityDef.id,
caster: instance.caster,
targets: instance.currentTargets.slice(),
position: instance.impactPoint || instance.targetPoint || getActorPosition(instance.caster)
};
this._emit("presentation", payload);
this._emit("presentation:cue", payload);
if (node.next) {
this._executeNode(instance, node.next);
}
}
/**
* Advance simulation time for all active executions and cooldowns.
* Enforces caster death cancellation and operation budgets.
* @param {number} deltaTime - Time step in seconds
*/
update(deltaTime = 0) {
if (typeof deltaTime !== "number" || !Number.isFinite(deltaTime) || deltaTime < 0) {
throw new TypeError("deltaTime must be a non-negative finite number");
}
this._operationsInCurrentTick = 0;
// 1. Advance cooldowns
for (const [casterId, casterMap] of Array.from(this._cooldowns.entries())) {
for (const [abilityId, remaining] of Array.from(casterMap.entries())) {
const next = Math.max(0, remaining - deltaTime);
if (next === 0) {
casterMap.delete(abilityId);
} else {
casterMap.set(abilityId, next);
}
}
if (casterMap.size === 0) {
this._cooldowns.delete(casterId);
}
}
// 2. Advance active execution instances
for (const instance of Array.from(this._instances.values())) {
if (instance.status !== "running") continue;
// Caster death cancellation: cleanly halts execution if caster is destroyed mid-cast
if (instance.caster && !isActorAlive(instance.caster)) {
this._cancelInstance(instance, "caster_death");
continue;
}
// Update timed actions
if (instance.activeTimedActions.length > 0) {
const finishedActions = [];
for (let i = instance.activeTimedActions.length - 1; i >= 0; i--) {
const action = instance.activeTimedActions[i];
action.remaining -= deltaTime;
if (action.remaining <= 0) {
instance.activeTimedActions.splice(i, 1);
finishedActions.push(action);
}
}
for (const action of finishedActions) {
if (instance.status !== "running") break;
if (action.next) {
this._executeNode(instance, action.next);
}
}
// Resume any pending sequences if active timed actions finished
if (instance.status === "running" && instance.activeTimedActions.length === 0 && instance.pendingSequences.length > 0) {
const seq = instance.pendingSequences[instance.pendingSequences.length - 1];
this._advanceSequence(instance, seq);
}
}
// Update active projectiles
if (instance.status === "running" && instance.activeProjectiles.length > 0) {
const candidateActors = this._getCandidateActors(instance);
const hitProjectiles = [];
for (let i = instance.activeProjectiles.length - 1; i >= 0; i--) {
const proj = instance.activeProjectiles[i];
const stepDist = proj.speed * deltaTime;
const remainingDist = proj.maxDistance - proj.travelled;
const actualDist = Math.min(stepDist, remainingDist);
proj.x += proj.dirX * actualDist;
proj.y += proj.dirY * actualDist;
proj.travelled += actualDist;
// Check actor contact
let hitActor = null;
for (const actor of candidateActors) {
if (!isActorAlive(actor) || actor === instance.caster) continue;
const pos = getActorPosition(actor);
const dist = Math.hypot(actor.position ? actor.position.x - proj.x : pos.x - proj.x,
actor.position ? actor.position.y - proj.y : pos.y - proj.y);
const hitThreshold = proj.radius + (actor.hurtbox && actor.hurtbox.width ? actor.hurtbox.width / 2 : 12);
if (dist <= hitThreshold) {
hitActor = actor;
break;
}
}
if (hitActor || proj.travelled >= proj.maxDistance) {
instance.activeProjectiles.splice(i, 1);
hitProjectiles.push({ proj, hitActor });
}
}
for (const { proj, hitActor } of hitProjectiles) {
if (instance.status !== "running") break;
instance.impactPoint = { x: proj.x, y: proj.y };
if (hitActor) {
instance.currentTargets = [hitActor];
}
this._emit("projectile_hit", {
instance,
projectile: proj,
hitActor,
position: instance.impactPoint,
abilityId: instance.abilityDef.id
});
this._emit("ability:projectile_hit", {
instance,
projectile: proj,
hitActor,
position: instance.impactPoint,
abilityId: instance.abilityDef.id
});
if (proj.onHit) {
this._executeNode(instance, proj.onHit);
}
if (proj.next) {
this._executeNode(instance, proj.next);
}
}
}
// Check if instance finished all work
if (this._isInstanceFinished(instance)) {
instance.status = "completed";
this._instances.delete(instance.id);
this._emit("ability:completed", {
instance,
caster: instance.caster,
abilityId: instance.abilityDef.id
});
}
}
}
}