@aura3d/engine 1.4.5 → 1.5.1

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

@@ -0,0 +1,127 @@
+import { createPromptAnimationIssue, promptAnimationContractVersion } from "./PromptAnimationContract.js";
+export const cartoonRouteProofSchemaVersion = "aura3d-cartoon-route-proof/v1";
+export function createCartoonRouteProof(input) {
+    const checks = createCartoonRouteReadinessChecks(input);
+    const issues = checks
+        .filter((check) => !check.passed)
+        .map((check) => createPromptAnimationIssue("error", `cartoon-route-${check.id}`, check.message));
+    for (const error of input.routeErrors ?? []) {
+        issues.push(createPromptAnimationIssue("error", "cartoon-route-error", error));
+    }
+    return {
+        artifact: "cartoon-route-proof",
+        schemaVersion: cartoonRouteProofSchemaVersion,
+        contractId: promptAnimationContractVersion,
+        episodeId: input.episodeId,
+        generatedAt: input.generatedAt,
+        route: input.route,
+        duration: input.duration,
+        frameRate: input.frameRate,
+        assets: input.assets,
+        shots: input.shots,
+        captions: input.captions ?? [],
+        visemes: input.visemes ?? [],
+        gestures: input.gestures ?? [],
+        render: input.render,
+        playback: input.playback,
+        routeErrors: input.routeErrors ?? [],
+        checks,
+        issues,
+        status: issues.some((issue) => issue.severity === "error") ? "fail" : "pass"
+    };
+}
+export function validateCartoonRouteProof(proof) {
+    const issues = [];
+    if (proof.schemaVersion !== cartoonRouteProofSchemaVersion) {
+        issues.push(createPromptAnimationIssue("error", "cartoon-route-proof-schema-version-unknown", `Unknown cartoon route proof schema "${proof.schemaVersion}".`));
+    }
+    if (proof.status !== "pass") {
+        issues.push(createPromptAnimationIssue("error", "cartoon-route-proof-status-fail", "Cartoon route proof did not pass."));
+    }
+    return [...issues, ...proof.issues];
+}
+function createCartoonRouteReadinessChecks(input) {
+    const characterAssets = input.assets.filter((asset) => asset.role === "character");
+    const setAssets = input.assets.filter((asset) => asset.role === "set");
+    const typedAssetFailures = input.assets.filter((asset) => !asset.typedAsset || !asset.ready || asset.source !== "aura-assets");
+    const missingShotCharacters = input.shots.flatMap((shot) => shot.expectedCharacterIds.filter((characterId) => !shot.visibleCharacterIds.includes(characterId)).map((characterId) => ({
+        shotId: shot.id,
+        characterId
+    })));
+    const missingRenderedCaptions = (input.captions ?? []).filter((caption) => !caption.rendered);
+    const missingRenderedVisemes = (input.visemes ?? []).filter((viseme) => !viseme.rendered || viseme.mode === "missing-mouth-motion");
+    const missingRenderedGestures = (input.gestures ?? []).filter((gesture) => !gesture.rendered);
+    return [
+        {
+            id: "route-present",
+            passed: input.route.length > 0,
+            message: "Cartoon route URL/path is required."
+        },
+        {
+            id: "typed-character-assets",
+            passed: characterAssets.length >= 2 && typedAssetFailures.filter((asset) => asset.role === "character").length === 0,
+            message: "Route proof requires at least two ready typed character assets from aura-assets."
+        },
+        {
+            id: "typed-set-assets",
+            passed: setAssets.length >= 1 && typedAssetFailures.filter((asset) => asset.role === "set").length === 0,
+            message: "Route proof requires at least one ready typed set asset from aura-assets."
+        },
+        {
+            id: "shots-present",
+            passed: input.shots.length > 0,
+            message: "Route proof requires at least one shot."
+        },
+        {
+            id: "shot-characters-visible",
+            passed: missingShotCharacters.length === 0,
+            message: `Expected characters must be visible in every shot; ${missingShotCharacters.length} missing visibility records.`
+        },
+        {
+            id: "shot-nonblank",
+            passed: input.shots.every((shot) => shot.nonblank && shot.frameCount > 0),
+            message: "Every shot must be nonblank and contain sampled frames."
+        },
+        {
+            id: "captions-rendered",
+            passed: (input.captions?.length ?? 0) > 0 && missingRenderedCaptions.length === 0,
+            message: "Route proof requires rendered captions."
+        },
+        {
+            id: "visemes-rendered",
+            passed: (input.visemes?.length ?? 0) > 0 && missingRenderedVisemes.length === 0,
+            message: "Route proof requires rendered viseme or mouth-motion cues."
+        },
+        {
+            id: "gestures-rendered",
+            passed: (input.gestures?.length ?? 0) > 0 && missingRenderedGestures.length === 0,
+            message: "Route proof requires rendered character gestures."
+        },
+        {
+            id: "render-nonblank",
+            passed: input.render.nonblank && input.render.frameCount > 0,
+            message: "Route render state must be nonblank and have frames."
+        },
+        {
+            id: "not-source-only",
+            passed: input.render.sourceOnly !== true && input.render.notTrue3D !== true,
+            message: "Source-only or not-true-3D routes cannot satisfy 1.1 cartoon route proof."
+        },
+        {
+            id: "no-export-overlays",
+            passed: input.render.debugOverlaysVisible !== true && input.render.routeChromeVisible !== true,
+            message: "Export route proof must not include debug overlays or route chrome."
+        },
+        {
+            id: "playback-controls",
+            passed: input.playback.canPlay && input.playback.canPause && input.playback.canScrub && input.playback.canJumpShots,
+            message: "Route proof requires play, pause, scrub, and shot-jump controls."
+        },
+        {
+            id: "route-errors",
+            passed: (input.routeErrors?.length ?? 0) === 0,
+            message: "Route proof must have no route errors."
+        }
+    ];
+}
+//# sourceMappingURL=CartoonRouteProof.js.map

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

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

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

@@ -0,0 +1,210 @@
+/**
+ * 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.
+ */
+export type CombatMoveRole = "jab" | "light" | "medium" | "heavy" | "launcher" | "special";
+export interface CombatFrameData {
+    readonly id: string;
+    /** Frames before the hitbox becomes active. */
+    readonly startup: number;
+    /** Frames the hitbox is live. */
+    readonly active: number;
+    /** Frames after the active window during which the attacker cannot act. */
+    readonly recovery: number;
+    /** Frames the defender is stunned on hit. */
+    readonly hitstun: number;
+    /** Frames the defender is stunned on block. */
+    readonly blockstun: number;
+    /** Horizontal reach of the hitbox, in world units. */
+    readonly range: number;
+    readonly damage: number;
+    /** Knockback impulse applied on hit. */
+    readonly knockback: number;
+    /** Frames both fighters freeze on contact, which sells the impact. */
+    readonly hitstop: number;
+}
+export interface CombatFrameAdvantage {
+    readonly id: string;
+    /**
+     * Frame advantage on hit: positive means the attacker acts first afterwards.
+     *
+     * `hitstun - recovery`. A move that is heavily plus on hit can start a combo; one
+     * that is minus on hit cannot.
+     */
+    readonly onHit: number;
+    /**
+     * Frame advantage on block. Negative means the defender can act first and punish.
+     *
+     * This is the number that creates a spacing game. When every move is plus on block
+     * there is no risk in attacking.
+     */
+    readonly onBlock: number;
+    /** Frames the attacker is helpless after a whiff: the punish window. */
+    readonly whiffPunishWindow: number;
+    /** Total frames the move occupies. */
+    readonly totalFrames: number;
+}
+/** Frame advantage for a move. */
+export declare function combatFrameAdvantage(move: CombatFrameData): CombatFrameAdvantage;
+export interface CombatFrameCheck {
+    readonly id: string;
+    readonly moveId: string;
+    readonly description: string;
+    readonly passes: boolean;
+    readonly detail: string;
+}
+export interface CombatFrameReport {
+    readonly schema: "aura3d-combat-frame-data/1.0";
+    readonly moves: readonly (CombatFrameData & {
+        readonly advantage: CombatFrameAdvantage;
+    })[];
+    readonly checks: readonly CombatFrameCheck[];
+    readonly passes: boolean;
+}
+export interface CombatFrameLimits {
+    /** Longest readable active window. Real games use 2-5 frames. */
+    readonly maxActiveFrames?: number | undefined;
+    /** Shortest active window that can still connect reliably. */
+    readonly minActiveFrames?: number | undefined;
+    /**
+     * Minimum recovery as a multiple of the active window.
+     *
+     * This is the ratio that creates risk. Below roughly 2x an attack is nearly free.
+     */
+    readonly minRecoveryToActiveRatio?: number | undefined;
+    /** Maximum frame advantage on block. Above 0 every move is safe. */
+    readonly maxOnBlock?: number | undefined;
+    /** Minimum punish window after a whiff, in frames. */
+    readonly minWhiffPunishWindow?: number | undefined;
+    /** Minimum hitstop, so contact reads as impact. */
+    readonly minHitstop?: number | undefined;
+}
+/**
+ * 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 declare function validateCombatFrameData(moves: readonly CombatFrameData[], limits?: CombatFrameLimits): CombatFrameReport;
+export interface CombatMoveRequest {
+    readonly id: string;
+    readonly role: CombatMoveRole;
+    /** Reach in world units. Longer moves are made slower to start. */
+    readonly range: number;
+    /** Damage, used to scale risk. */
+    readonly damage: number;
+}
+/**
+ * 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 declare function solveCombatFrameData(request: CombatMoveRequest, options?: {
+    readonly referenceRange?: number | undefined;
+    readonly referenceDamage?: number | undefined;
+}): CombatFrameData;
+export type CombatAiAggression = "defensive" | "balanced" | "aggressive";
+export interface CombatAiConfig {
+    readonly moves: readonly CombatFrameData[];
+    /**
+     * Reaction delay in frames.
+     *
+     * A zero-delay AI is not a credible opponent: it blocks the instant a button is
+     * pressed, which reads as cheating rather than as skill. Human reaction is roughly
+     * 12-18 frames at 60fps.
+     */
+    readonly reactionFrames?: number | undefined;
+    /** Preferred distance to hold, in world units. Defaults to just outside its best poke. */
+    readonly preferredRange?: number | undefined;
+    readonly aggression?: CombatAiAggression | undefined;
+    /** Frames to wait after acting before acting again. */
+    readonly cooldownFrames?: number | undefined;
+    /** Deterministic seed. */
+    readonly seed?: number | undefined;
+}
+export interface CombatAiObservation {
+    /** Horizontal distance to the opponent. */
+    readonly distance: number;
+    /** Opponent's current move id, or undefined when neutral. */
+    readonly opponentMoveId?: string | undefined;
+    /** Frames the opponent's current move has been running. */
+    readonly opponentMoveFrame?: number | undefined;
+    /** True when the AI is currently in hitstun or blockstun and cannot act. */
+    readonly stunned?: boolean | undefined;
+    /** Frames remaining in the AI's own current move, 0 when free. */
+    readonly ownRecoveryFrames?: number | undefined;
+    readonly ownHealthFraction?: number | undefined;
+    readonly opponentHealthFraction?: number | undefined;
+}
+export interface CombatAiDecision {
+    /** Move to start this frame, or undefined to hold. */
+    readonly moveId: string | undefined;
+    /** Whether to block. */
+    readonly block: boolean;
+    /** Movement intent: -1 retreat, 0 hold, 1 advance. */
+    readonly approach: -1 | 0 | 1;
+    /** Why this decision was made, for evidence and debugging. */
+    readonly reason: string;
+}
+export interface CombatAi {
+    readonly kind: "aura-combat-ai";
+    decide(observation: CombatAiObservation): CombatAiDecision;
+    reset(): void;
+    telemetry(): {
+        readonly reactionFrames: number;
+        readonly preferredRange: number;
+        readonly aggression: CombatAiAggression;
+        readonly decisionCount: number;
+        readonly punishAttempts: number;
+        readonly blockAttempts: number;
+        readonly lastDecision: CombatAiDecision;
+    };
+}
+/**
+ * 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 declare function createCombatAi(config: CombatAiConfig): CombatAi;
+//# sourceMappingURL=CombatFrameData.d.ts.map

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

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