@woosh/meep-engine 2.138.20 → 2.140.0

package/src/engine/control/first-person/TODO.md

@@ -0,0 +1,173 @@
+# First-person controller — TODO
+
+Working notes. Things we've identified as worth doing but haven't pulled
+the trigger on yet. Companion to DESIGN.md (base) and DESIGN_EXTENSIONS.md
+(abilities + mastery roadmap).
+
+## Mastery evaluators — additional
+
+We ship StrideTimingJump, FootAsymmetryTurn, BreathRhythm, and
+SlideInitiationTiming today. The remaining ones from the
+DESIGN_EXTENSIONS Phase 10 list, ordered by what would give the most
+texture per unit of work:
+
+### WallRunEntryTimingEvaluator
+Decision point: `WallRunGravity` (currently un-wired — Wall-run reads
+`cfg.wallRun.gravityFactor` straight, no mastery hook). Wire it.
+
+Input: angle-of-attack against the wall at activation. Lower angle of
+attack (entering near-parallel) is the canonical "good" entry — converts
+forward momentum into the run smoothly. High angle of attack (entering
+near-perpendicular) is "bad" — you're crashing into the wall.
+
+Curve shape: peak at small angle (1.0 → 0.8, less effective gravity =
+more hang time); penalty at high angle (1.0 → 1.15, gravity ramped =
+shorter run). Symmetric in behaviour, asymmetric in magnitude.
+
+Estimated effort: 0.5 day. Capture entry angle in WallRun.onActivate,
+stash it on the evaluator's per-instance state OR on a new
+`runtime.wallRunEntryAngle` field. Curve + spec.
+
+### WallRunTakeoffTimingEvaluator
+Decision point: `WallJumpImpulse` (already wired — base WallJump runs
+mastery on it).
+
+Input: how late in the wall-run the wall-jump is fired. Late in the
+run (near the timer expiry) is the "explosive last-second push-off"
+— bonus. Right at activation is "panicked early jump" — penalty.
+
+Curve shape: time-based, normalized to [0, 1] over wall-run duration.
+Peak at 0.6–0.9 (committed but not desperate). Trough near 0.0
+(panicked).
+
+Estimated effort: 0.5 day. WallJump needs to read how long WallRun was
+active when it preempted. Simplest: track `runtime.wallRunElapsedAt
+Takeoff` in WallRun.onDeactivate (or via a signal).
+
+### WallJumpEntryAngleEvaluator
+Decision point: `WallJumpImpulse`.
+
+Input: angle between the player's velocity vector and the wall normal
+at the moment of jump press. A near-perpendicular push-off (velocity
+along normal at impact) converts the most into the impulse — bonus.
+A near-tangent push (sliding along) is "weak push-off" — penalty.
+
+Curve shape: peak at dot(velocity, normal) approaching 1.0 (head-on);
+penalty near 0 (parallel skim).
+
+Composes multiplicatively with the takeoff-timing evaluator above —
+both fire on `WallJumpImpulse`. That's the point of the multiplicative
+composition rule.
+
+Estimated effort: 0.5 day.
+
+### LedgeCatchTimingEvaluator
+Decision point: NEW — would need `LedgeCatchExertionScale` or similar.
+Currently LedgeGrab uses a flat `cfg.ledgeGrab.exertionRiseRate`.
+
+Input: |velocityY| at the moment of catch. A gentle catch (low vy) is
+forgiving — low exertion rise (longer hang). A desperate save (high
+|vy|) is harder — higher exertion rise (shorter hang).
+
+Curve shape: identity 1.0 at low |vy| (≤ 2 m/s), ramping up to ~1.5×
+at high |vy| (≥ 8 m/s).
+
+Estimated effort: 0.5 day, plus adding the new decision point.
+
+### MantleExitSpeedEvaluator
+Decision point: `MantleExitSpeed` (currently un-wired).
+
+Input: stride-phase at the moment of mantle completion. Landing on a
+midstance push-off bonus the exit velocity (player runs off the mantle
+into the next surface); landing on footfall takes a small penalty.
+
+Currently Mantle's exit doesn't set any forward velocity — the player
+lands at rest. To make this evaluator meaningful, we'd also need
+Mantle to apply a small forward push on completion, which the
+evaluator then scales. Two-step change.
+
+Estimated effort: 1 day (more wiring than the others).
+
+## Move-and-slide follow-ups
+
+### Slide along non-axis-aligned walls
+**Landed.** `PhysicsSystem.shapeCast` now writes the true contact
+normal (narrowphase-refined via GJK + EPA at TOI), and `_moveAndSlide`
+uses the canonical iterative slide: stop at first contact, project the
+residual onto the contact tangent, sweep again, repeat up to 4 times.
+Multi-contact corners stop cleanly; diagonal approaches slide along
+both axis-aligned and oblique surfaces.
+
+### Vertical sweep (anti-tunnel for floors and ceilings)
+`_moveAndSlide` is currently called for horizontal motion only. The
+vertical phase still does a direct position add. For fast falls past
+the ground-resolver's 0.1 m raycast lift, the player can sink through
+the floor in one tick; for vertical wall-jumps into a ceiling, no
+contact is detected.
+
+Wiring a vertical sweep into `_integrateVerticalAndResolveGround`
+needs to be coordinated with the SKIN clearance — landing at
+`floor + SKIN` would re-flag the player as airborne by the resolver,
+which would re-apply gravity and bounce. Either drop SKIN on
+floor-normal contacts, or have the resolver use a tolerance instead
+of strict `position.y <= testY`.
+
+### Ability motion routing
+Slide and WallRun integrate position manually (slide friction in the
+ability tick; wall-run reduced-gravity integration). Once the slide-
+along-walls work above lands, threading those through `_moveAndSlide`
+would prevent wall-runners from drifting into the wall and sliders
+from penetrating obstacles in their path. The controller-side change
+is a few lines per ability; the gating issue is having a usable
+surface normal.
+
+## Other open notes
+
+### Horizontal-capsule Prone collider
+The posture → collider sync uses a vertical capsule for Prone, sized
+to `cfg.body.proneHeight`. When that's below `2·radius` (the default)
+the capsule degenerates to a sphere of `radius` — Y extent
+`2·radius ≈ 0.68 m`. That fits "low-profile shape" honestly but it
+doesn't reflect what a sliding body actually looks like: long along
+the direction of travel, narrow in the cross-section. A horizontal
+capsule (Y-axis cylinder rotated 90° around X via TransformedShape3D
+matrix, oriented along body-local +Z) would let the player fit
+under 0.4-m ledges while still occupying the full body length
+horizontally. Tracked because the Prone test currently asserts the
+vertical-capsule extent — see PostureCollider.spec.js geometry note.
+
+### Refactor `pose.crouchAmount` away
+Now redundant with `pose.postureAmount`. Leave for one or two builds so
+any external consumers can migrate, then delete.
+
+### Stride-mastery score telemetry
+`MasterySet` records EMA scores per decision point. We never surface
+these to the HUD or any feedback system. A simple debug overlay
+showing the running scores (a sparkline per decision point?) would be
+helpful when tuning curves.
+
+### Tune the slide bob fade-out
+`bobIntensityHalfLife` controls how fast the lateral bob fades when
+posture changes to Prone. May be too slow — feels like a brief wobble
+before the slide settles into "pure motion". Worth play-test tuning.
+
+### Posture-aware footstep audio
+Surface tag is on `state.surfaceTag`. The footstep signal carries
+side + speed + surfaceTag, but emission is gated on
+`feetStriking` (Stand or Crouch posture). When other postures want
+audio cues (a slide-along-pavement sound, a hang-grip creak), they
+need their own signal channels — not piggyback on `onFootStep`.
+
+### WallRun direction sense (push-back behaviour)
+Currently WallRun projects velocity onto the wall tangent each tick.
+If the player turns AWAY from the wall mid-run, the wall-tangent
+projection still keeps them pinned. Might want a "lean-away exits the
+run" condition: if `intent.move` rotates more than X degrees from the
+wall tangent, exit the wall-run.
+
+### Animation track for Hang posture
+The eye stays at body height while hanging (we don't drop the eye
+height in Hang because the body root is already below the ledge). But
+the rig should probably show arms reaching up. That's a skeleton
+concern, not a controller one — just flagging that `pose.posture =
+Hang` is the signal the rig should branch on.

package/src/engine/control/first-person/abilities/Ability.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Base class for movement abilities (wall-run, mantle, slide, ledge-grab,
+ * wall-jump, etc.). Each ability is a small state machine that:
+ *
+ *   1. Reports whether it wants to activate ({@link canActivate})
+ *   2. Owns the player's motion while active ({@link tick})
+ *   3. Reports whether it can be preempted right now ({@link canInterrupt})
+ *   4. Cleans up when control is released ({@link onDeactivate})
+ *
+ * Abilities are owned by an {@link AbilitySet}. At most one ability is
+ * active at a time. Preemption and queueing are handled by the set — see
+ * its docs for the hybrid policy.
+ *
+ * Subclasses should set:
+ *   - `priority` — used to order preemption attempts
+ *   - `name` — for telemetry / debugging
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Ability {
+    /**
+     * Higher priority preempts lower. Defaults:
+     *   slide=10, mantle=30, ledgeGrab=40, wallRun=50, wallJump=60.
+     * Wall-jump is highest because it's the most input-direct response
+     * (button press) and should fire reliably regardless of what else
+     * is going on.
+     * @type {number}
+     */
+    priority: number;
+    /**
+     * Stable string identifier for telemetry / debugging overlays.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Ask: do you want to take control RIGHT NOW?
+     *
+     * Read controller state and sensor data; return true iff conditions
+     * are met. Side-effect-free; called every tick when no ability is
+     * active, and once on each tick when this ability is queued behind
+     * another.
+     *
+     * @param {*} controller  FirstPersonPlayerController
+     * @param {*} runtime     per-entity runtime
+     * @param {*} sensors     FirstPersonSensors (may be null in stub mode)
+     * @returns {boolean}
+     */
+    canActivate(controller: any, runtime: any, sensors: any): boolean;
+    /**
+     * Called once when this ability acquires control. Use for one-shot
+     * setup (kicking impulses, capturing entry velocity, etc.).
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     */
+    onActivate(controller: any, runtime: any): void;
+    /**
+     * Runs each fixed step while active. The ability OWNS body motion
+     * during this window — writes directly to runtime.velocity*, the body
+     * Transform position, springs, etc. Returning false releases control
+     * back to the AbilitySet (which will run base locomotion or the next
+     * queued ability in the same tick).
+     *
+     * The `system` parameter is the {@link FirstPersonPlayerControllerSystem}
+     * itself, passed through so abilities can call shared helpers like
+     * vertical-integration-and-ground-resolution without re-implementing
+     * them. Use it sparingly — the cleaner the ability's tick is, the
+     * easier it is to reason about ownership.
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     * @param {*} bodyTransform
+     * @param {number} dt
+     * @param {*} system  the FirstPersonPlayerControllerSystem instance
+     * @returns {boolean} true = stay active; false = release control
+     */
+    tick(controller: any, runtime: any, bodyTransform: any, dt: number, system: any): boolean;
+    /**
+     * Ask: can a higher-priority ability preempt you right now?
+     *
+     * Defaults to true (interruptible). Override to declare windows where
+     * this ability *must* finish what it's doing — e.g. mantle returns
+     * false while on its scripted path; slide returns false for the
+     * first ~150ms after entry.
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     * @returns {boolean}
+     */
+    canInterrupt(controller: any, runtime: any): boolean;
+    /**
+     * Called once when control is released (either tick returned false,
+     * or a higher-priority ability preempted). Clean up internal state.
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     */
+    onDeactivate(controller: any, runtime: any): void;
+}
+//# sourceMappingURL=Ability.d.ts.map

package/src/engine/control/first-person/abilities/Ability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ability.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/Ability.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEQ;;;;;;;OAOG;IACH,UAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,MAFU,MAAM,CAEK;IAGzB;;;;;;;;;;;;OAYG;IAEH,0DAHa,OAAO,CAKnB;IAED;;;;;;OAMG;IAEH,gDAAkC;IAElC;;;;;;;;;;;;;;;;;;;OAmBG;IAEH,4DALW,MAAM,gBAEJ,OAAO,CAKnB;IAED;;;;;;;;;;;OAWG;IAEH,6CAHa,OAAO,CAKnB;IAED;;;;;;OAMG;IAEH,kDAAoC;CACvC"}

package/src/engine/control/first-person/abilities/Ability.js

@@ -0,0 +1,119 @@
+/**
+ * Base class for movement abilities (wall-run, mantle, slide, ledge-grab,
+ * wall-jump, etc.). Each ability is a small state machine that:
+ *
+ *   1. Reports whether it wants to activate ({@link canActivate})
+ *   2. Owns the player's motion while active ({@link tick})
+ *   3. Reports whether it can be preempted right now ({@link canInterrupt})
+ *   4. Cleans up when control is released ({@link onDeactivate})
+ *
+ * Abilities are owned by an {@link AbilitySet}. At most one ability is
+ * active at a time. Preemption and queueing are handled by the set — see
+ * its docs for the hybrid policy.
+ *
+ * Subclasses should set:
+ *   - `priority` — used to order preemption attempts
+ *   - `name` — for telemetry / debugging
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Ability {
+    constructor() {
+        /**
+         * Higher priority preempts lower. Defaults:
+         *   slide=10, mantle=30, ledgeGrab=40, wallRun=50, wallJump=60.
+         * Wall-jump is highest because it's the most input-direct response
+         * (button press) and should fire reliably regardless of what else
+         * is going on.
+         * @type {number}
+         */
+        this.priority = 0;
+
+        /**
+         * Stable string identifier for telemetry / debugging overlays.
+         * @type {string}
+         */
+        this.name = "Ability";
+    }
+
+    /**
+     * Ask: do you want to take control RIGHT NOW?
+     *
+     * Read controller state and sensor data; return true iff conditions
+     * are met. Side-effect-free; called every tick when no ability is
+     * active, and once on each tick when this ability is queued behind
+     * another.
+     *
+     * @param {*} controller  FirstPersonPlayerController
+     * @param {*} runtime     per-entity runtime
+     * @param {*} sensors     FirstPersonSensors (may be null in stub mode)
+     * @returns {boolean}
+     */
+    // eslint-disable-next-line no-unused-vars
+    canActivate(controller, runtime, sensors) {
+        return false;
+    }
+
+    /**
+     * Called once when this ability acquires control. Use for one-shot
+     * setup (kicking impulses, capturing entry velocity, etc.).
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     */
+    // eslint-disable-next-line no-unused-vars
+    onActivate(controller, runtime) {}
+
+    /**
+     * Runs each fixed step while active. The ability OWNS body motion
+     * during this window — writes directly to runtime.velocity*, the body
+     * Transform position, springs, etc. Returning false releases control
+     * back to the AbilitySet (which will run base locomotion or the next
+     * queued ability in the same tick).
+     *
+     * The `system` parameter is the {@link FirstPersonPlayerControllerSystem}
+     * itself, passed through so abilities can call shared helpers like
+     * vertical-integration-and-ground-resolution without re-implementing
+     * them. Use it sparingly — the cleaner the ability's tick is, the
+     * easier it is to reason about ownership.
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     * @param {*} bodyTransform
+     * @param {number} dt
+     * @param {*} system  the FirstPersonPlayerControllerSystem instance
+     * @returns {boolean} true = stay active; false = release control
+     */
+    // eslint-disable-next-line no-unused-vars
+    tick(controller, runtime, bodyTransform, dt, system) {
+        return false;
+    }
+
+    /**
+     * Ask: can a higher-priority ability preempt you right now?
+     *
+     * Defaults to true (interruptible). Override to declare windows where
+     * this ability *must* finish what it's doing — e.g. mantle returns
+     * false while on its scripted path; slide returns false for the
+     * first ~150ms after entry.
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     * @returns {boolean}
+     */
+    // eslint-disable-next-line no-unused-vars
+    canInterrupt(controller, runtime) {
+        return true;
+    }
+
+    /**
+     * Called once when control is released (either tick returned false,
+     * or a higher-priority ability preempted). Clean up internal state.
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     */
+    // eslint-disable-next-line no-unused-vars
+    onDeactivate(controller, runtime) {}
+}

package/src/engine/control/first-person/abilities/AbilitySet.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Holds a set of {@link Ability} instances and runs the activation +
+ * preemption + queueing policy:
+ *
+ *   1. If an ability is active, tick it first.
+ *      - If its tick returns false → it's done. Falls through to step 2
+ *        in the SAME tick (no wasted frame).
+ *
+ *   2. If a queued ability exists (from a previous tick that was blocked),
+ *      check its canActivate() again. If still wants in → activate.
+ *
+ *   3. If no ability is active, poll all abilities in DESCENDING priority.
+ *      First that canActivate() becomes active.
+ *
+ *   4. If an active ability is still running but a higher-priority one
+ *      wants in: check the active one's canInterrupt(). If yes → preempt
+ *      now. If no → queue the higher-priority candidate; it will re-check
+ *      every tick until the current ability releases (or canInterrupt
+ *      flips to true).
+ *
+ * Returns whether base-locomotion should run this tick (true iff no
+ * ability owns motion).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AbilitySet {
+    /**
+     * Registered abilities. Order does not matter — sorted by priority
+     * on demand when polling. Set is small (typically <10) so we don't
+     * pre-sort.
+     * @type {Ability[]}
+     */
+    abilities: Ability[];
+    /**
+     * Currently-active ability, or null if base locomotion is running.
+     * @type {Ability|null}
+     */
+    active: Ability | null;
+    /**
+     * Ability waiting for the current one to release. Cleared when it
+     * activates OR when its canActivate() returns false on re-check
+     * (the conditions that wanted it might have passed).
+     * @type {Ability|null}
+     */
+    queued: Ability | null;
+    /**
+     * Add an ability.
+     * @param {Ability} ability
+     */
+    add(ability: Ability): void;
+    /**
+     * Remove an ability if present. If it's currently active or queued,
+     * deactivates / clears it first.
+     * @param {Ability} ability
+     */
+    remove(ability: Ability): void;
+    /**
+     * Execute one tick. Returns true if base locomotion should run this
+     * fixed step (no ability owns motion).
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     * @param {*} bodyTransform
+     * @param {*} sensors
+     * @param {number} dt
+     * @param {*} [system] FirstPersonPlayerControllerSystem instance,
+     *                     passed through to ability.tick() so abilities
+     *                     can delegate to shared helpers.
+     * @returns {boolean} true = run base locomotion; false = ability owned
+     */
+    tick(controller: any, runtime: any, bodyTransform: any, sensors: any, dt: number, system?: any): boolean;
+    /**
+     * @private
+     */
+    private _findHighestPriorityActivatable;
+    /**
+     * @private
+     */
+    private _activate;
+    /**
+     * @private
+     */
+    private _deactivate;
+}
+//# sourceMappingURL=AbilitySet.d.ts.map

package/src/engine/control/first-person/abilities/AbilitySet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbilitySet.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/control/first-person/abilities/AbilitySet.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEQ;;;;;OAKG;IACH,WAFU,SAAS,CAEA;IAEnB;;;OAGG;IACH,QAFU,UAAQ,IAAI,CAEJ;IAElB;;;;;OAKG;IACH,QAFU,UAAQ,IAAI,CAEJ;IAGtB;;;OAGG;IACH,4BAEC;IAED;;;;OAIG;IACH,+BAQC;IAED;;;;;;;;;;;;;OAaG;IACH,0EANW,MAAM,iBAIJ,OAAO,CA4DnB;IAED;;OAEG;IACH,wCAcC;IAED;;OAEG;IACH,kBAGC;IAED;;OAEG;IACH,oBAKC;CACJ"}

package/src/engine/control/first-person/abilities/AbilitySet.js

@@ -0,0 +1,185 @@
+/**
+ * Holds a set of {@link Ability} instances and runs the activation +
+ * preemption + queueing policy:
+ *
+ *   1. If an ability is active, tick it first.
+ *      - If its tick returns false → it's done. Falls through to step 2
+ *        in the SAME tick (no wasted frame).
+ *
+ *   2. If a queued ability exists (from a previous tick that was blocked),
+ *      check its canActivate() again. If still wants in → activate.
+ *
+ *   3. If no ability is active, poll all abilities in DESCENDING priority.
+ *      First that canActivate() becomes active.
+ *
+ *   4. If an active ability is still running but a higher-priority one
+ *      wants in: check the active one's canInterrupt(). If yes → preempt
+ *      now. If no → queue the higher-priority candidate; it will re-check
+ *      every tick until the current ability releases (or canInterrupt
+ *      flips to true).
+ *
+ * Returns whether base-locomotion should run this tick (true iff no
+ * ability owns motion).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AbilitySet {
+    constructor() {
+        /**
+         * Registered abilities. Order does not matter — sorted by priority
+         * on demand when polling. Set is small (typically <10) so we don't
+         * pre-sort.
+         * @type {Ability[]}
+         */
+        this.abilities = [];
+
+        /**
+         * Currently-active ability, or null if base locomotion is running.
+         * @type {Ability|null}
+         */
+        this.active = null;
+
+        /**
+         * Ability waiting for the current one to release. Cleared when it
+         * activates OR when its canActivate() returns false on re-check
+         * (the conditions that wanted it might have passed).
+         * @type {Ability|null}
+         */
+        this.queued = null;
+    }
+
+    /**
+     * Add an ability.
+     * @param {Ability} ability
+     */
+    add(ability) {
+        this.abilities.push(ability);
+    }
+
+    /**
+     * Remove an ability if present. If it's currently active or queued,
+     * deactivates / clears it first.
+     * @param {Ability} ability
+     */
+    remove(ability) {
+        if (this.active === ability) {
+            // Best-effort: caller-side cleanup is their responsibility.
+            this.active = null;
+        }
+        if (this.queued === ability) this.queued = null;
+        const i = this.abilities.indexOf(ability);
+        if (i !== -1) this.abilities.splice(i, 1);
+    }
+
+    /**
+     * Execute one tick. Returns true if base locomotion should run this
+     * fixed step (no ability owns motion).
+     *
+     * @param {*} controller
+     * @param {*} runtime
+     * @param {*} bodyTransform
+     * @param {*} sensors
+     * @param {number} dt
+     * @param {*} [system] FirstPersonPlayerControllerSystem instance,
+     *                     passed through to ability.tick() so abilities
+     *                     can delegate to shared helpers.
+     * @returns {boolean} true = run base locomotion; false = ability owned
+     */
+    tick(controller, runtime, bodyTransform, sensors, dt, system) {
+        // Step 1: tick the active ability if any. May release control.
+        if (this.active !== null) {
+            const stillActive = this.active.tick(controller, runtime, bodyTransform, dt, system);
+            if (!stillActive) {
+                this._deactivate(controller, runtime);
+            }
+        }
+
+        // Step 2: if something is queued, see if it can activate now (the
+        // current ability may have released in step 1, OR may be
+        // interruptible now even though it wasn't before).
+        if (this.queued !== null) {
+            if (this.active === null) {
+                if (this.queued.canActivate(controller, runtime, sensors)) {
+                    this._activate(this.queued, controller, runtime);
+                }
+                this.queued = null; // cleared whether or not it activated
+            } else if (this.queued.priority > this.active.priority
+                && this.active.canInterrupt(controller, runtime)) {
+                if (this.queued.canActivate(controller, runtime, sensors)) {
+                    const next = this.queued;
+                    this.queued = null;
+                    this._deactivate(controller, runtime);
+                    this._activate(next, controller, runtime);
+                } else {
+                    // Queued candidate no longer wants in — drop it.
+                    this.queued = null;
+                }
+            }
+            // else: still waiting on a non-interruptible current ability
+        }
+
+        // Step 3: if nothing active, poll candidates (highest priority first).
+        if (this.active === null) {
+            const best = this._findHighestPriorityActivatable(controller, runtime, sensors, -Infinity);
+            if (best !== null) {
+                this._activate(best, controller, runtime);
+            }
+        } else {
+            // Step 4: existing ability active — check if a higher-priority
+            // candidate wants in.
+            const challenger = this._findHighestPriorityActivatable(
+                controller, runtime, sensors, this.active.priority,
+            );
+            if (challenger !== null) {
+                if (this.active.canInterrupt(controller, runtime)) {
+                    this._deactivate(controller, runtime);
+                    this._activate(challenger, controller, runtime);
+                } else {
+                    // Queue it — will re-poll each tick until current releases
+                    // or becomes interruptible.
+                    this.queued = challenger;
+                }
+            }
+        }
+
+        return this.active === null;
+    }
+
+    /**
+     * @private
+     */
+    _findHighestPriorityActivatable(controller, runtime, sensors, minPriorityExclusive) {
+        let best = null;
+        let bestPriority = minPriorityExclusive;
+        const list = this.abilities;
+        for (let i = 0; i < list.length; i++) {
+            const a = list[i];
+            if (a === this.active) continue;
+            if (a.priority <= bestPriority) continue;
+            if (a.canActivate(controller, runtime, sensors)) {
+                best = a;
+                bestPriority = a.priority;
+            }
+        }
+        return best;
+    }
+
+    /**
+     * @private
+     */
+    _activate(ability, controller, runtime) {
+        this.active = ability;
+        ability.onActivate(controller, runtime);
+    }
+
+    /**
+     * @private
+     */
+    _deactivate(controller, runtime) {
+        if (this.active === null) return;
+        const prev = this.active;
+        this.active = null;
+        prev.onDeactivate(controller, runtime);
+    }
+}