@aura3d/engine 1.4.5 → 1.5.1

package/dist/engine/agent-api/CombatFrameData.js

@@ -0,0 +1,324 @@
+/**
+ * Reusable frame-based combat model: frame data, spacing and a credible AI.
+ *
+ * ## The defects this addresses
+ *
+ * Aura Clash's attacks were reported as unrealistic, with weak spacing, limited
+ * momentum, and animations that do not correspond convincingly to hits. Converting
+ * the shipped move table to frames at 60fps shows why:
+ *
+ * | move    | startup | active | recovery |
+ * | ------- | ------- | ------ | -------- |
+ * | light   | 4       | **12** | **4**    |
+ * | heavy   | 6       | **17** | **5**    |
+ * | special | 5       | **32** | **4**    |
+ *
+ * Real fighting-game frame data is the opposite shape: a short active window (2-5
+ * frames) and a long recovery (10-30 frames). Aura Clash's active windows are 3-8x
+ * too long and its recoveries 3-6x too short, which has three consequences:
+ *
+ * 1. **Hits do not correspond to the animation.** A 32-frame active window on the
+ *    special means the hitbox is live for over half a second, so damage lands at
+ *    moments that look nothing like contact -- the reported "attack dealing damage
+ *    before contact".
+ * 2. **No spacing game.** With a 12-frame active window and a 4-frame recovery, an
+ *    attack is nearly always safe. Whiffing costs almost nothing, so there is no
+ *    reason to respect range and no punish window to aim for. That is precisely
+ *    "weak spacing".
+ * 3. **No trades or momentum.** Blockstun and hitstun cannot create meaningful
+ *    advantage when every move recovers in four frames.
+ *
+ * The engine defect is that nothing validated frame data as frame data. A move table
+ * could declare any startup/active/recovery split and no check compared it against the
+ * shape that makes a combat system readable.
+ *
+ * This module adds that check ({@link validateCombatFrameData}), a solver that derives
+ * balanced frame data from an intended move role ({@link solveCombatFrameData}), and a
+ * reactive AI ({@link createCombatAi}) that behaves like an opponent: it respects
+ * range, reacts with a delay, blocks what it sees, and punishes what it can.
+ *
+ * Pure and dependency-free.
+ */
+/** Frame advantage for a move. */
+export function combatFrameAdvantage(move) {
+    return {
+        id: move.id,
+        onHit: move.hitstun - move.recovery,
+        onBlock: move.blockstun - move.recovery,
+        whiffPunishWindow: move.recovery,
+        totalFrames: move.startup + move.active + move.recovery
+    };
+}
+/**
+ * Validate a move table as frame data.
+ *
+ * This is the check that did not exist. It fails a table whose active windows are so
+ * long that damage cannot correspond to the animation, and one whose recoveries are so
+ * short that whiffing carries no risk.
+ */
+export function validateCombatFrameData(moves, limits = {}) {
+    const maxActive = limits.maxActiveFrames ?? 6;
+    const minActive = limits.minActiveFrames ?? 2;
+    const minRecoveryRatio = limits.minRecoveryToActiveRatio ?? 2;
+    const maxOnBlock = limits.maxOnBlock ?? 2;
+    const minWhiffWindow = limits.minWhiffPunishWindow ?? 8;
+    const minHitstop = limits.minHitstop ?? 2;
+    const checks = [];
+    const annotated = moves.map((move) => ({ ...move, advantage: combatFrameAdvantage(move) }));
+    for (const move of annotated) {
+        checks.push({
+            id: "active-window-readable",
+            moveId: move.id,
+            description: `active window must be ${minActive}-${maxActive} frames so damage corresponds to the animation`,
+            passes: move.active >= minActive && move.active <= maxActive,
+            detail: `${move.active} active frames`
+        });
+        checks.push({
+            id: "recovery-creates-risk",
+            moveId: move.id,
+            description: `recovery must be at least ${minRecoveryRatio}x the active window so whiffing is punishable`,
+            passes: move.active <= 0 || move.recovery >= move.active * minRecoveryRatio,
+            detail: `recovery ${move.recovery} vs active ${move.active} (ratio ${round(move.active > 0 ? move.recovery / move.active : Number.POSITIVE_INFINITY)})`
+        });
+        checks.push({
+            id: "not-safe-on-block",
+            moveId: move.id,
+            description: `frame advantage on block must not exceed +${maxOnBlock}, or the move carries no risk`,
+            passes: move.advantage.onBlock <= maxOnBlock,
+            detail: `${move.advantage.onBlock >= 0 ? "+" : ""}${move.advantage.onBlock} on block`
+        });
+        checks.push({
+            id: "whiff-punishable",
+            moveId: move.id,
+            description: `a whiff must leave at least ${minWhiffWindow} frames of punish window`,
+            passes: move.advantage.whiffPunishWindow >= minWhiffWindow,
+            detail: `${move.advantage.whiffPunishWindow} frame punish window`
+        });
+        checks.push({
+            id: "hitstop-sells-impact",
+            moveId: move.id,
+            description: `hitstop must be at least ${minHitstop} frames so contact reads as impact`,
+            passes: move.hitstop >= minHitstop,
+            detail: `${move.hitstop} frames of hitstop`
+        });
+        checks.push({
+            id: "startup-before-active",
+            moveId: move.id,
+            description: "a move must have startup frames, so an attack telegraphs before it can hit",
+            passes: move.startup >= 1,
+            detail: `${move.startup} startup frames`
+        });
+    }
+    // Table-level: stronger moves must be slower, or there is no reason to use a jab.
+    const byDamage = [...annotated].sort((a, b) => a.damage - b.damage);
+    for (let index = 0; index < byDamage.length - 1; index += 1) {
+        const weaker = byDamage[index];
+        const stronger = byDamage[index + 1];
+        if (weaker.damage === stronger.damage)
+            continue;
+        checks.push({
+            id: "damage-costs-speed",
+            moveId: `${weaker.id}->${stronger.id}`,
+            description: "a stronger move must be slower to start or riskier on block",
+            passes: stronger.startup >= weaker.startup || stronger.advantage.onBlock <= weaker.advantage.onBlock,
+            detail: `${weaker.id} ${weaker.damage}dmg/${weaker.startup}f vs ${stronger.id} ${stronger.damage}dmg/${stronger.startup}f`
+        });
+    }
+    return {
+        schema: "aura3d-combat-frame-data/1.0",
+        moves: annotated,
+        checks,
+        passes: checks.every((check) => check.passes)
+    };
+}
+const ROLE_PROFILES = {
+    /*
+     * Frame data shaped like a real fighting game.
+     *
+     * A jab is fast and nearly neutral on block, so it is the safe poke. Heavier moves
+     * start slower, recover longer and are clearly minus on block, so using them is a
+     * decision rather than a default. Every active window is short, which is what makes a
+     * hit correspond to the moment of contact.
+     */
+    jab: { startup: 3, active: 2, recovery: 7, hitstun: 12, blockstun: 8, hitstop: 3, knockback: 0.18 },
+    light: { startup: 5, active: 3, recovery: 10, hitstun: 15, blockstun: 10, hitstop: 4, knockback: 0.28 },
+    medium: { startup: 8, active: 3, recovery: 15, hitstun: 19, blockstun: 12, hitstop: 5, knockback: 0.42 },
+    heavy: { startup: 12, active: 4, recovery: 22, hitstun: 26, blockstun: 15, hitstop: 7, knockback: 0.7 },
+    launcher: { startup: 11, active: 3, recovery: 26, hitstun: 34, blockstun: 14, hitstop: 6, knockback: 0.55 },
+    special: { startup: 14, active: 5, recovery: 28, hitstun: 30, blockstun: 18, hitstop: 9, knockback: 1.05 }
+};
+/**
+ * Derive balanced frame data from a move's intended role.
+ *
+ * Reach adds startup, because a longer poke should be slower to commit to. Damage adds
+ * recovery, so a big hit is a bigger risk. Neither is a free parameter.
+ */
+export function solveCombatFrameData(request, options = {}) {
+    const profile = ROLE_PROFILES[request.role];
+    const referenceRange = Math.max(0.1, options.referenceRange ?? 1.4);
+    const referenceDamage = Math.max(1, options.referenceDamage ?? 10);
+    // Reach beyond the reference costs startup; damage beyond it costs recovery.
+    const rangePenalty = Math.max(0, request.range / referenceRange - 1);
+    const damagePenalty = Math.max(0, request.damage / referenceDamage - 1);
+    return {
+        id: request.id,
+        startup: Math.round(profile.startup * (1 + rangePenalty * 0.4)),
+        active: profile.active,
+        recovery: Math.round(profile.recovery * (1 + damagePenalty * 0.3)),
+        hitstun: profile.hitstun,
+        blockstun: profile.blockstun,
+        range: round(request.range),
+        damage: request.damage,
+        knockback: round(profile.knockback * (1 + damagePenalty * 0.2)),
+        hitstop: profile.hitstop
+    };
+}
+const AGGRESSION_PROFILES = {
+    defensive: { attackChance: 0.35, blockChance: 0.9, spacingTolerance: 0.3 },
+    balanced: { attackChance: 0.6, blockChance: 0.72, spacingTolerance: 0.2 },
+    aggressive: { attackChance: 0.85, blockChance: 0.5, spacingTolerance: 0.12 }
+};
+/**
+ * Create a reactive combat AI.
+ *
+ * Behaves like an opponent rather than a timer: it holds a preferred range, reacts to a
+ * telegraphed attack after a delay, blocks what it has had time to see, and punishes a
+ * move whose recovery leaves a window. Deterministic for a given seed.
+ */
+export function createCombatAi(config) {
+    const moves = new Map(config.moves.map((move) => [move.id, move]));
+    const aggression = config.aggression ?? "balanced";
+    const profile = AGGRESSION_PROFILES[aggression];
+    const reactionFrames = Math.max(0, config.reactionFrames ?? 14);
+    const cooldownFrames = Math.max(0, config.cooldownFrames ?? 18);
+    // The fastest move is the punish tool; the longest-reaching is the poke.
+    const fastest = [...moves.values()].sort((a, b) => a.startup - b.startup)[0];
+    const longest = [...moves.values()].sort((a, b) => b.range - a.range)[0];
+    /*
+     * Preferred range sits just *inside* the AI's longest poke.
+     *
+     * Setting it outside its own reach looked like good spacing discipline and was in fact
+     * a deadlock: the AI held a distance from which nothing could connect, so it never
+     * attacked and only ever adjusted position. Real fighting-game spacing is to hold the
+     * edge of your own longest threat -- close enough to poke, far enough that the
+     * opponent must commit to reach you.
+     */
+    const preferredRange = config.preferredRange ?? (longest ? longest.range * 0.92 : 1.5);
+    let seenOpponentMove;
+    let framesSinceSeen = 0;
+    let cooldown = 0;
+    let decisionCount = 0;
+    let punishAttempts = 0;
+    let blockAttempts = 0;
+    let random = (config.seed ?? 1) >>> 0 || 1;
+    const nextRandom = () => {
+        random ^= random << 13;
+        random ^= random >>> 17;
+        random ^= random << 5;
+        return (random >>> 0) / 0xffffffff;
+    };
+    let lastDecision = { moveId: undefined, block: false, approach: 0, reason: "initial" };
+    return {
+        kind: "aura-combat-ai",
+        decide(observation) {
+            decisionCount += 1;
+            cooldown = Math.max(0, cooldown - 1);
+            // Track how long the opponent's current move has been visible, so reaction is
+            // delayed rather than instant.
+            if (observation.opponentMoveId !== seenOpponentMove) {
+                seenOpponentMove = observation.opponentMoveId;
+                framesSinceSeen = 0;
+            }
+            else {
+                framesSinceSeen += 1;
+            }
+            const reacted = seenOpponentMove !== undefined && framesSinceSeen >= reactionFrames;
+            const decide = (decision) => {
+                lastDecision = decision;
+                return decision;
+            };
+            // Stunned or mid-move: nothing to decide.
+            if (observation.stunned === true || (observation.ownRecoveryFrames ?? 0) > 0) {
+                return decide({ moveId: undefined, block: false, approach: 0, reason: "recovering" });
+            }
+            const opponentMove = observation.opponentMoveId ? moves.get(observation.opponentMoveId) : undefined;
+            /*
+             * Punish. When the opponent's move is in its recovery and the AI's fastest move
+             * can start and connect inside that window, take it. This is the behaviour that
+             * makes spacing matter, and it is only possible because recovery frames exist.
+             */
+            if (reacted && opponentMove && fastest && cooldown <= 0) {
+                const opponentFrame = observation.opponentMoveFrame ?? 0;
+                const recoveryStart = opponentMove.startup + opponentMove.active;
+                const framesLeftInRecovery = recoveryStart + opponentMove.recovery - opponentFrame;
+                const inRecovery = opponentFrame >= recoveryStart && framesLeftInRecovery > 0;
+                if (inRecovery && framesLeftInRecovery > fastest.startup && observation.distance <= fastest.range) {
+                    punishAttempts += 1;
+                    cooldown = cooldownFrames;
+                    return decide({ moveId: fastest.id, block: false, approach: 0, reason: "punish-recovery" });
+                }
+            }
+            /*
+             * Block. Only after the reaction delay, and only while the attack could still
+             * reach: blocking a move that has already recovered is not defence, it is a tell
+             * that the AI is reading state it should not have.
+             */
+            if (reacted && opponentMove) {
+                const opponentFrame = observation.opponentMoveFrame ?? 0;
+                const threatening = opponentFrame < opponentMove.startup + opponentMove.active;
+                if (threatening && observation.distance <= opponentMove.range * 1.15 && nextRandom() < profile.blockChance) {
+                    blockAttempts += 1;
+                    return decide({ moveId: undefined, block: true, approach: 0, reason: "block-incoming" });
+                }
+            }
+            // Spacing. Hold the preferred range; step in to attack, step out when crowded.
+            const rangeError = observation.distance - preferredRange;
+            if (Math.abs(rangeError) > profile.spacingTolerance) {
+                const approach = rangeError > 0 ? 1 : -1;
+                // Attack on the way in when a move actually reaches.
+                const reachable = [...moves.values()].filter((move) => observation.distance <= move.range);
+                if (approach === 1 && reachable.length > 0 && cooldown <= 0 && nextRandom() < profile.attackChance) {
+                    const chosen = reachable[Math.floor(nextRandom() * reachable.length)] ?? reachable[0];
+                    cooldown = cooldownFrames;
+                    return decide({ moveId: chosen.id, block: false, approach: 0, reason: "attack-in-range" });
+                }
+                return decide({ moveId: undefined, block: false, approach, reason: approach > 0 ? "close-distance" : "create-space" });
+            }
+            // At preferred range with nothing to react to: poke when the odds are taken.
+            if (cooldown <= 0 && nextRandom() < profile.attackChance) {
+                const reachable = [...moves.values()].filter((move) => observation.distance <= move.range);
+                if (reachable.length > 0) {
+                    const chosen = reachable[Math.floor(nextRandom() * reachable.length)] ?? reachable[0];
+                    cooldown = cooldownFrames;
+                    return decide({ moveId: chosen.id, block: false, approach: 0, reason: "poke-at-range" });
+                }
+            }
+            return decide({ moveId: undefined, block: false, approach: 0, reason: "hold-range" });
+        },
+        reset() {
+            seenOpponentMove = undefined;
+            framesSinceSeen = 0;
+            cooldown = 0;
+            decisionCount = 0;
+            punishAttempts = 0;
+            blockAttempts = 0;
+            random = (config.seed ?? 1) >>> 0 || 1;
+            lastDecision = { moveId: undefined, block: false, approach: 0, reason: "reset" };
+        },
+        telemetry() {
+            return {
+                reactionFrames,
+                preferredRange: round(preferredRange),
+                aggression,
+                decisionCount,
+                punishAttempts,
+                blockAttempts,
+                lastDecision
+            };
+        }
+    };
+}
+function round(value) {
+    return Math.round(value * 1e4) / 1e4;
+}
+//# sourceMappingURL=CombatFrameData.js.map

package/dist/engine/agent-api/CombatFrameData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CombatFrameData.js","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/CombatFrameData.ts"],"names":[],"mappings":"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"}

package/dist/engine/agent-api/FocusSelection.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Reusable object focus and selection feedback.
+ *
+ * ## The defect this replaces
+ *
+ * The product configurator built its focus indicator by hand:
+ *
+ * ```ts
+ * primitives.torus({ ... }).position(...p).rotate(1.5708, 0, 0).scale([1.22, 0.08, 0.78])
+ * ```
+ *
+ * Aura3D's torus primitive is generated in local XY -- the ring lies in the XY
+ * plane with its tube thin on **Z** (`createTorusGeometry` sweeps `cos u, sin u`
+ * into X/Y and puts the tube's `sin v` on Z). Scaling `[1.22, 0.08, 0.78]`
+ * therefore squashes the ring's own **Y radius** to 8%, turning the circle into a
+ * flat horizontal sliver. The subsequent `rotate(pi/2, 0, 0)` tips that sliver
+ * into the ground plane, and it renders as the "random yellow/white bar" the
+ * user reported. A working ring in the same codebase uses `[0.72, 0.72, 0.028]`
+ * -- equal X/Y radii, thin on Z -- which is why the two looked unrelated.
+ *
+ * Changing those three constants would have fixed one route and left the trap in
+ * place for every other. The real defects are: primitive local axes were not
+ * documented, and no reusable focus feedback existed, so every route invented
+ * its own indicator geometry.
+ *
+ * This module removes the need to know the torus axis convention at all. A route
+ * states intent -- focus this target, with a ring and a callout -- and gets
+ * correct indicator geometry for any target size, orientation, or nonuniform
+ * scale.
+ *
+ * Pure and dependency-free: it returns scene-node JSON and camera intent, so it
+ * is unit-testable without a renderer and reusable by any route or kit.
+ */
+import type { AuraColor, AuraSceneNode, AuraVec3 } from "./index.js";
+import { type PlacedBounds, type SemanticRegion } from "./SpatialAnchoring.js";
+/**
+ * Local-axis conventions for Aura3D primitives.
+ *
+ * Published so a route that must build custom geometry can do so correctly, and
+ * so the reason for the configurator defect is discoverable rather than folklore.
+ */
+export declare const AURA_PRIMITIVE_AXES: {
+    /**
+     * A torus is a ring in the local XY plane. Its major radius spans X and Y
+     * equally; its tube thickness lies on Z. To thin a ring, scale **Z**. Scaling
+     * Y collapses the ring into a bar.
+     */
+    readonly torus: {
+        readonly ringPlane: "xy";
+        readonly tubeAxis: "z";
+        readonly thinAxis: "z";
+    };
+    /** A cylinder's height runs along Y; its circular cross-section spans X and Z. */
+    readonly cylinder: {
+        readonly heightAxis: "y";
+        readonly crossSection: "xz";
+        readonly thinAxis: "y";
+    };
+    /** A plane lies in XZ with its normal on Y. */
+    readonly plane: {
+        readonly plane: "xz";
+        readonly normalAxis: "y";
+        readonly thinAxis: "y";
+    };
+    /** Boxes, spheres and capsules are axis-symmetric about their own extents. */
+    readonly box: {
+        readonly thinAxis: undefined;
+    };
+    readonly sphere: {
+        readonly thinAxis: undefined;
+    };
+    readonly capsule: {
+        readonly heightAxis: "y";
+        readonly thinAxis: undefined;
+    };
+};
+/** Visual treatments a focus indicator can apply. */
+export type FocusIndicator = "ring" | "halo" | "bounding-box" | "outline" | "emissive-highlight";
+export interface FocusTargetBounds {
+    /** World position of the target's centre. */
+    readonly center: AuraVec3;
+    /** World-space extents of the target. */
+    readonly size: AuraVec3;
+    /**
+     * Euler rotation of the target, radians. Indicator geometry inherits it so a
+     * rotated part gets a rotated indicator rather than an axis-aligned one.
+     */
+    readonly rotation?: AuraVec3 | undefined;
+}
+export interface FocusTarget extends FocusTargetBounds {
+    readonly id: string;
+    /** Human-readable name used for the callout and accessibility text. */
+    readonly label?: string | undefined;
+}
+export interface FocusOptions {
+    /** Indicators to draw. Defaults to a ring plus a callout label. */
+    readonly indicators?: readonly FocusIndicator[] | undefined;
+    readonly color?: AuraColor | undefined;
+    /** Draw a callout label anchored to the target. Defaults to true. */
+    readonly callout?: boolean | undefined;
+    /** Text for the callout. Defaults to the target's label. */
+    readonly calloutText?: string | undefined;
+    /** Draw a leader line from the callout to the target. Defaults to true. */
+    readonly leaderLine?: boolean | undefined;
+    /** Dim non-focused geometry. Reported as intent; the route applies it. */
+    readonly dimOthers?: boolean | undefined;
+    /** Move the camera to frame the target. Defaults to true. */
+    readonly cameraFocus?: boolean | undefined;
+    /**
+     * Extra clearance between the indicator and the target surface, as a fraction
+     * of the target's largest extent. Defaults to 0.12 so a ring reads as
+     * surrounding the part rather than intersecting it.
+     */
+    readonly clearance?: number | undefined;
+    /** Node-name prefix, so indicator nodes are identifiable in evidence. */
+    readonly namePrefix?: string | undefined;
+    /**
+     * Viewport aspect ratio, used only to size camera framing distance. Defaults
+     * to 16/9.
+     */
+    readonly aspect?: number | undefined;
+    /** Mobile viewports need a wider frame; defaults to false. */
+    readonly compactViewport?: boolean | undefined;
+}
+export interface FocusCameraIntent {
+    readonly position: AuraVec3;
+    readonly target: AuraVec3;
+    readonly fov: number;
+    /** True when the target's bounds fit inside the frustum at this distance. */
+    readonly containsTarget: boolean;
+}
+export interface FocusResult {
+    readonly kind: "aura-focus-result";
+    readonly targetId: string;
+    /** Indicator geometry and labels to add to the scene. */
+    readonly nodes: readonly AuraSceneNode[];
+    readonly camera: FocusCameraIntent | undefined;
+    /** Set when `dimOthers` was requested, so the route can lower other materials. */
+    readonly dimOthers: boolean;
+    /** Machine-checkable statement that indicators surround their target. */
+    readonly invariants: FocusInvariantReport;
+    /** Screen-reader text describing the current selection. */
+    readonly accessibilityLabel: string;
+}
+export interface FocusInvariantReport {
+    readonly schema: "aura3d-focus-invariants/1.0";
+    readonly checks: readonly {
+        readonly id: string;
+        readonly description: string;
+        readonly passes: boolean;
+        readonly detail: string;
+    }[];
+    readonly passes: boolean;
+}
+/**
+ * Build focus feedback for a target.
+ *
+ * The ring is sized from the target's own extents and thinned on **Z**, the
+ * torus tube axis, then rotated to lie in the horizontal plane. Because the
+ * radius is uniform in the ring's own plane it stays a ring for any target
+ * aspect ratio -- which is what the flattened-bar defect got wrong.
+ */
+export declare function focusObject(target: FocusTarget, options?: FocusOptions): FocusResult;
+/**
+ * Focus a named region of a subject rather than a standalone object.
+ *
+ * This is how a configurator focuses "the earcups" without knowing where the
+ * earcups are in world space: the region is normalized to the subject's bounds,
+ * so it follows the asset.
+ */
+export declare function focusSemanticRegion(subject: PlacedBounds, region: SemanticRegion, options?: FocusOptions): FocusResult;
+/** Empty focus state: no indicators, no camera change, reset accessibility text. */
+export declare function clearFocus(): FocusResult;
+/**
+ * Camera pose that frames a target's bounds.
+ *
+ * Distance is derived from the vertical and horizontal half-angles so the whole
+ * target fits regardless of viewport aspect. A compact (mobile) viewport pulls
+ * back further because UI chrome takes vertical space.
+ */
+export declare function focusCameraIntent(center: AuraVec3, size: AuraVec3, options?: {
+    readonly aspect?: number | undefined;
+    readonly compactViewport?: boolean | undefined;
+    readonly fov?: number | undefined;
+}): FocusCameraIntent;
+//# sourceMappingURL=FocusSelection.d.ts.map

package/dist/engine/agent-api/FocusSelection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FocusSelection.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/FocusSelection.ts"],"names":[],"mappings":"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"}