@aura3d/engine 1.4.5 → 1.5.1

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

@@ -0,0 +1,207 @@
+/**
+ * Reusable platformer motion tuning and level solvability.
+ *
+ * ## The defects this addresses
+ *
+ * Skyline Runner's jump was reported as unnatural, floaty, and unreliable to land,
+ * with a world that read as disconnected floating strips and a session that ended in
+ * about half a minute. Those are not four unrelated complaints; three of them follow
+ * from one number.
+ *
+ * The level ships `jumpVelocity: 7.4` and inherits the kit default `gravity: -22`.
+ * That gives an apex of `v^2 / 2g = 1.245` world units and an airtime of
+ * `2v / g = 0.673` seconds. The level's platforms step up by at most **0.36** units
+ * and are separated by gaps of at most **0.30** units. So every jump rises about
+ * 3.5x higher than the tallest step it needs to clear and travels well past the
+ * widest gap, with the character spending two thirds of a second in the air on a
+ * course whose obstacles need a fraction of that. The character therefore appears to
+ * float above the level rather than move through it, landings arrive long after the
+ * player expects them, and because the apex dwarfs the platform spacing the platforms
+ * read as unrelated strips rather than as a connected route.
+ *
+ * The engine defect is that nothing related jump tuning to level geometry, so a level
+ * could ship physically inconsistent with its own platforms and every gate would pass:
+ * the level is *solvable* (an over-powered jump clears everything), the screenshots
+ * look fine, and no metric compares apex to step height.
+ *
+ * This module closes that gap. {@link solvePlatformerMotion} derives gravity, jump
+ * velocity and move speed from what a level actually asks the player to do, and
+ * {@link validatePlatformerMotion} reports when a level's tuning is inconsistent with
+ * its geometry -- both over-powered (floaty) and under-powered (unclearable).
+ *
+ * Pure and dependency-free.
+ */
+/**
+ * Measure what a level asks the player to do.
+ *
+ * Consecutive platforms are taken in x order, which matches how a side-scrolling
+ * course is traversed. Gaps are measured edge to edge and rises top to top.
+ */
+export function measurePlatformerGeometry(platforms) {
+    if (platforms.length === 0) {
+        return { maxRise: 0, maxGap: 0, courseLength: 0, minPlatformWidth: 0, platformCount: 0 };
+    }
+    const ordered = [...platforms].sort((a, b) => a.x - b.x);
+    let maxRise = 0;
+    let maxGap = 0;
+    for (let index = 0; index < ordered.length - 1; index += 1) {
+        const from = ordered[index];
+        const to = ordered[index + 1];
+        const topFrom = from.y + (from.height ?? 0);
+        const topTo = to.y + (to.height ?? 0);
+        maxRise = Math.max(maxRise, topTo - topFrom);
+        maxGap = Math.max(maxGap, to.x - (from.x + from.width));
+    }
+    const start = Math.min(...ordered.map((platform) => platform.x));
+    const end = Math.max(...ordered.map((platform) => platform.x + platform.width));
+    return {
+        maxRise: round(maxRise),
+        maxGap: round(Math.max(0, maxGap)),
+        courseLength: round(end - start),
+        minPlatformWidth: round(Math.min(...ordered.map((platform) => platform.width))),
+        platformCount: ordered.length
+    };
+}
+/**
+ * Derive platformer motion from a level's own geometry.
+ *
+ * The apex is sized to the tallest step the player must clear, not chosen freely, so a
+ * jump cannot overshoot the level by 3.5x. Gravity then follows from the apex and the
+ * chosen rise time, and jump velocity from gravity and rise time. Move speed is sized
+ * so the jump clears the widest gap and the course takes a chosen amount of time.
+ */
+export function solvePlatformerMotion(platforms, request = {}) {
+    const geometry = measurePlatformerGeometry(platforms);
+    const riseSeconds = clampPositive(request.riseSeconds ?? 0.3, 0.08, 1);
+    const apexHeadroom = clampPositive(request.apexHeadroom ?? 1.6, 1, 6);
+    const gapMargin = clampPositive(request.gapMargin ?? 1.45, 1, 4);
+    const minApex = Math.max(0.05, request.minApex ?? 0.4);
+    // Apex is the tallest step plus headroom, floored so a flat level still jumps.
+    const apex = Math.max(minApex, geometry.maxRise * apexHeadroom);
+    // Projectile motion: apex = v^2 / 2g and riseSeconds = v / g, so g = 2 * apex / t^2.
+    const gravityMagnitude = (2 * apex) / (riseSeconds * riseSeconds);
+    const jumpVelocity = gravityMagnitude * riseSeconds;
+    const airtime = 2 * riseSeconds;
+    /*
+     * Move speed has two requirements, and the larger wins.
+     *
+     * It must be fast enough that a full jump clears the widest gap with margin, and it
+     * should cross the course in roughly the intended session time. Taking the maximum
+     * means a level with a wide gap is never made unclearable by a slow target pace.
+     */
+    const speedForGap = geometry.maxGap > 0 ? (geometry.maxGap * gapMargin) / airtime : 0;
+    const targetSessionSeconds = Math.max(1, request.targetSessionSeconds ?? 0);
+    const traversalFraction = clampPositive(request.traversalFraction ?? 0.45, 0.1, 1);
+    const speedForSession = targetSessionSeconds > 1 && geometry.courseLength > 0
+        ? geometry.courseLength / (targetSessionSeconds * traversalFraction)
+        : 0;
+    const moveSpeed = Math.max(0.5, speedForGap, speedForSession);
+    const traversalSeconds = moveSpeed > 0 ? geometry.courseLength / moveSpeed : 0;
+    return {
+        kind: "aura-platformer-motion",
+        gravity: -round(gravityMagnitude),
+        jumpVelocity: round(jumpVelocity),
+        moveSpeed: round(moveSpeed),
+        apex: round(apex),
+        airtime: round(airtime),
+        jumpReach: round(moveSpeed * airtime),
+        // Coyote time and jump buffer are fractions of airtime rather than fixed
+        // milliseconds: a snappy jump needs a shorter grace window than a floaty one, and a
+        // fixed 110ms window is a large fraction of a 0.44s jump but a small one of 0.9s.
+        coyoteMs: Math.round(airtime * 1000 * 0.18),
+        jumpBufferMs: Math.round(airtime * 1000 * 0.22),
+        // Terminal velocity caps a long fall at roughly twice takeoff speed, which keeps a
+        // drop readable instead of becoming an instant teleport downward.
+        terminalVelocity: -round(jumpVelocity * 2),
+        geometry,
+        traversalSeconds: round(traversalSeconds),
+        estimatedSessionSeconds: round(traversalSeconds / traversalFraction)
+    };
+}
+/**
+ * Check that a level's motion tuning is consistent with its geometry.
+ *
+ * This is the check that was missing. A level can be perfectly solvable and still feel
+ * wrong: an over-powered jump clears every obstacle, so solvability passes, while the
+ * character visibly floats. Both directions are failures.
+ */
+export function validatePlatformerMotion(platforms, motion, limits = {}) {
+    const geometry = measurePlatformerGeometry(platforms);
+    const gravityMagnitude = Math.abs(motion.gravity);
+    const apex = gravityMagnitude > 0 ? (motion.jumpVelocity * motion.jumpVelocity) / (2 * gravityMagnitude) : 0;
+    const airtime = gravityMagnitude > 0 ? (2 * motion.jumpVelocity) / gravityMagnitude : 0;
+    const jumpReach = motion.moveSpeed * airtime;
+    const apexToRiseRatio = geometry.maxRise > 0 ? apex / geometry.maxRise : Number.POSITIVE_INFINITY;
+    const reachToGapRatio = geometry.maxGap > 0 ? jumpReach / geometry.maxGap : Number.POSITIVE_INFINITY;
+    const maxApexRatio = limits.maxApexToRiseRatio ?? 2.6;
+    const minApexRatio = limits.minApexToRiseRatio ?? 1.15;
+    const maxReachRatio = limits.maxReachToGapRatio ?? 3.2;
+    const minReachRatio = limits.minReachToGapRatio ?? 1.1;
+    const maxAirtime = limits.maxAirtimeSeconds ?? 0.95;
+    const checks = [
+        {
+            id: "jump-clears-tallest-step",
+            description: `jump apex must exceed the tallest step by at least ${minApexRatio}x`,
+            passes: !Number.isFinite(apexToRiseRatio) || apexToRiseRatio >= minApexRatio,
+            detail: `apex ${round(apex)} vs tallest step ${geometry.maxRise} (ratio ${roundRatio(apexToRiseRatio)})`
+        },
+        {
+            id: "jump-not-floaty",
+            description: `jump apex must not exceed the tallest step by more than ${maxApexRatio}x`,
+            // An infinite ratio means the level has no rises at all, where any apex is fine.
+            passes: !Number.isFinite(apexToRiseRatio) || apexToRiseRatio <= maxApexRatio,
+            detail: `apex ${round(apex)} vs tallest step ${geometry.maxRise} (ratio ${roundRatio(apexToRiseRatio)})`
+        },
+        {
+            id: "jump-clears-widest-gap",
+            description: `horizontal jump reach must exceed the widest gap by at least ${minReachRatio}x`,
+            passes: !Number.isFinite(reachToGapRatio) || reachToGapRatio >= minReachRatio,
+            detail: `reach ${round(jumpReach)} vs widest gap ${geometry.maxGap} (ratio ${roundRatio(reachToGapRatio)})`
+        },
+        {
+            id: "jump-reach-proportionate",
+            description: `horizontal jump reach must not exceed the widest gap by more than ${maxReachRatio}x`,
+            passes: !Number.isFinite(reachToGapRatio) || reachToGapRatio <= maxReachRatio,
+            detail: `reach ${round(jumpReach)} vs widest gap ${geometry.maxGap} (ratio ${roundRatio(reachToGapRatio)})`
+        },
+        {
+            id: "airtime-readable",
+            description: `total airtime must stay under ${maxAirtime}s so a jump reads as a jump`,
+            passes: airtime <= maxAirtime,
+            detail: `airtime ${round(airtime)}s`
+        },
+        {
+            id: "landing-precision-achievable",
+            description: "jump reach must not exceed the narrowest platform by so much that landing is a guess",
+            // A reach far larger than the target platform means the player cannot choose where
+            // to land, only whether to jump.
+            passes: geometry.minPlatformWidth <= 0 || jumpReach <= geometry.minPlatformWidth * 4,
+            detail: `reach ${round(jumpReach)} vs narrowest platform ${geometry.minPlatformWidth}`
+        }
+    ];
+    return {
+        schema: "aura3d-platformer-motion-invariants/1.0",
+        geometry,
+        measured: {
+            apex: round(apex),
+            airtime: round(airtime),
+            jumpReach: round(jumpReach),
+            apexToRiseRatio: roundRatio(apexToRiseRatio),
+            reachToGapRatio: roundRatio(reachToGapRatio)
+        },
+        checks,
+        passes: checks.every((check) => check.passes)
+    };
+}
+function clampPositive(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, value));
+}
+function round(value) {
+    return Math.round(value * 1e4) / 1e4;
+}
+function roundRatio(value) {
+    return Number.isFinite(value) ? Math.round(value * 100) / 100 : Number.POSITIVE_INFINITY;
+}
+//# sourceMappingURL=PlatformerMotion.js.map

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

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

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

@@ -156,4 +156,66 @@ export declare function groundedRenderedAssetPlacement(asset: SceneAssetLike, op
  * center is given the asset is treated as origin-centered.
  */
 export declare function boundsFromSize(size: Vec3, center?: Vec3): SceneBounds;
+/**
+ * Derived subject facts the brief's WS4 list names that had no reusable derivation.
+ *
+ * ## Why these are here rather than in each route
+ *
+ * WS4 lists 15 values a reusable typed helper should derive so "route code does not know raw asset dimensions".
+ * Ten existed. Five did not, and each is a value a route would otherwise compute inline from bounds -- which is
+ * exactly how `CAR_SCENE_HEIGHT` came to be hardcoded to one asset's ratio and survive two hero swaps.
+ *
+ * All five are derived from a scaled `SceneBounds`, so a route states intent and reads back facts.
+ */
+export interface SubjectPlacementFacts {
+    /** World-space point where the subject's lowest geometry meets the floor. */
+    readonly groundContact: Vec3;
+    /** Centre of the subject's bounds after placement, i.e. what a camera should look at. */
+    readonly visualCenter: Vec3;
+    /**
+     * Volume-weighted centroid approximation.
+     *
+     * Deliberately an approximation from the bounding box, not a mesh integral: a route framing a vehicle wants
+     * "roughly where the mass sits" for camera pitch and lean, and computing a true centre of mass would need
+     * per-triangle volume the typed manifest does not carry. Named `approximation` so no caller mistakes it for one.
+     */
+    readonly centerOfMassApproximation: Vec3;
+    /** Placed world bounds, for framing tests that must not clip the subject. */
+    readonly framingBounds: SceneBounds;
+    /**
+     * Forward axis, or `undefined` when the asset declares none.
+     *
+     * Never inferred. A symmetric body has no intrinsic front, and guessing produces a vehicle facing backwards --
+     * the same reason admission reports orientation as evidence rather than derivation.
+     */
+    readonly forwardAxis: Vec3 | undefined;
+    /** Contact patch the subject's lower silhouette occupies, for wheel/foot readability checks. */
+    readonly contactRegion: {
+        readonly min: Vec3;
+        readonly max: Vec3;
+        readonly depth: number;
+    };
+}
+export interface SubjectPlacementRequest {
+    /** Rendered scale applied to the asset's raw bounds. */
+    readonly scale: number;
+    /** Floor position, defaulting to the origin. */
+    readonly x?: number | undefined;
+    readonly z?: number | undefined;
+    readonly floorY?: number | undefined;
+    /** Declared forward axis from manifest evidence. Omit when the asset declares none. */
+    readonly forwardAxis?: Vec3 | undefined;
+    /**
+     * Fraction of subject height treated as the contact region, for wheel or foot readability.
+     * Defaults to 0.3, matching the wheel-band fraction the vehicle visibility probe measures.
+     */
+    readonly contactRegionFraction?: number | undefined;
+}
+/**
+ * Derive placement facts for a subject from its raw bounds and an intended scale.
+ *
+ * Pure: no renderer, no asset loading. A route passes bounds it already has typed access to and reads back the
+ * five WS4 values instead of computing them from dimensions it should not need to know.
+ */
+export declare function resolveSubjectPlacementFacts(bounds: SceneBounds, request: SubjectPlacementRequest): SubjectPlacementFacts;
 //# sourceMappingURL=SceneGroundingUtils.d.ts.map

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

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

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

@@ -187,4 +187,41 @@ function toVec3(value) {
     const vec = [Number(value[0]), Number(value[1]), Number(value[2])];
     return vec.every((component) => Number.isFinite(component)) ? vec : undefined;
 }
+/**
+ * Derive placement facts for a subject from its raw bounds and an intended scale.
+ *
+ * Pure: no renderer, no asset loading. A route passes bounds it already has typed access to and reads back the
+ * five WS4 values instead of computing them from dimensions it should not need to know.
+ */
+export function resolveSubjectPlacementFacts(bounds, request) {
+    const scale = Number.isFinite(request.scale) && request.scale > 0 ? request.scale : 1;
+    const x = request.x ?? 0;
+    const z = request.z ?? 0;
+    const floorY = request.floorY ?? 0;
+    const size = boundsSize(bounds).map((value) => value * scale);
+    // Scaled bounds, translated so the lowest point rests on the floor at (x, z).
+    const min = [x - size[0] / 2, floorY, z - size[2] / 2];
+    const max = [x + size[0] / 2, floorY + size[1], z + size[2] / 2];
+    const fraction = Math.min(1, Math.max(0.01, request.contactRegionFraction ?? 0.3));
+    const contactDepth = size[1] * fraction;
+    return {
+        groundContact: [x, floorY, z],
+        visualCenter: [x, floorY + size[1] / 2, z],
+        /*
+         * Biased below the geometric centre.
+         *
+         * A vehicle or character carries most of its mass low -- drivetrain and floorpan, legs and torso -- so the
+         * bounding-box centre sits above the real centroid. 0.42 of height is a standard approximation for wheeled
+         * subjects and keeps camera pitch from looking down on a subject that should read as planted.
+         */
+        centerOfMassApproximation: [x, floorY + size[1] * 0.42, z],
+        framingBounds: { min, max },
+        forwardAxis: request.forwardAxis,
+        contactRegion: {
+            min,
+            max: [max[0], floorY + contactDepth, max[2]],
+            depth: contactDepth
+        }
+    };
+}
 //# sourceMappingURL=SceneGroundingUtils.js.map

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

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

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

@@ -0,0 +1,124 @@
+/**
+ * Reusable scene queries: raycasts, shape casts and ground probes.
+ *
+ * ## Why this exists
+ *
+ * The physics audit (`tests/reports/aura3d-physics-audit.json`) classified raycasts, shape
+ * casts, penetration resolution, friction, restitution, constraints and continuous
+ * collision detection as **unused**: implemented in `@aura3d/physics`, covered by its own
+ * suites, and unreachable from the public agent API. A route needing to answer "what is
+ * under this point" therefore had two options -- reach into a package's internals, or write
+ * the query by hand. Both are the same defect class as the hardcoded contact planes this
+ * remediation removed.
+ *
+ * `PhysicsWorld` already implements `raycast`, `raycastAll`, `sphereCast` and
+ * `sphereCastAll`. This module is the public surface over them, plus the pure
+ * scene-geometry queries a route usually actually wants: a downward ground probe, and a
+ * query against declarative scene nodes rather than a constructed physics world.
+ *
+ * The pure paths are dependency-free and unit-testable; the physics-backed path adapts a
+ * `PhysicsWorld` when a route has one.
+ */
+import type { AuraSceneNode, AuraVec3 } from "./index.js";
+import { type PlacedBounds } from "./SpatialAnchoring.js";
+export interface SceneRay {
+    readonly origin: AuraVec3;
+    /** Direction; normalized internally, so a caller may pass any non-zero vector. */
+    readonly direction: AuraVec3;
+    readonly maxDistance?: number | undefined;
+}
+export interface SceneQueryHit {
+    /** Name of the node that was hit, when the target carries one. */
+    readonly nodeName: string | undefined;
+    readonly point: AuraVec3;
+    readonly normal: AuraVec3;
+    readonly distance: number;
+}
+/**
+ * Axis-aligned box a query can test against.
+ *
+ * Scene nodes are reduced to these, which is exact for boxes and planes and a conservative
+ * bound for spheres, cylinders and models. Stated rather than implied: a route needing
+ * exact mesh intersection must use a physics world with real colliders.
+ */
+export interface SceneQueryTarget {
+    readonly nodeName: string | undefined;
+    readonly bounds: PlacedBounds;
+}
+/**
+ * Reduce declarative scene nodes to query targets.
+ *
+ * Only nodes with a resolvable position and scale participate. A model's bounds are its
+ * node scale, which is a conservative approximation: the caller is told so by
+ * {@link SceneQueryTarget}'s documentation rather than discovering it from a wrong result.
+ */
+export declare function sceneQueryTargets(nodes: readonly AuraSceneNode[]): readonly SceneQueryTarget[];
+/**
+ * Cast a ray against query targets, returning the nearest hit.
+ *
+ * Slab-method AABB intersection: exact for axis-aligned boxes and correct for the
+ * conservative bounds of other node kinds.
+ */
+export declare function raycastSceneTargets(targets: readonly SceneQueryTarget[], ray: SceneRay): SceneQueryHit | undefined;
+/** Every hit along a ray, nearest first. */
+export declare function raycastSceneTargetsAll(targets: readonly SceneQueryTarget[], ray: SceneRay): readonly SceneQueryHit[];
+/**
+ * Downward ground probe.
+ *
+ * The query a route asks most often, and the one that was previously answered by a frozen
+ * constant. Returns the surface height under a point, or `undefined` when nothing is below
+ * it -- which is a meaningful answer, not a reason to substitute zero.
+ */
+export declare function groundProbe(targets: readonly SceneQueryTarget[], x: number, z: number, options?: {
+    readonly fromHeight?: number | undefined;
+    readonly maxDistance?: number | undefined;
+}): {
+    readonly height: number;
+    readonly normal: AuraVec3;
+    readonly nodeName: string | undefined;
+} | undefined;
+/**
+ * Sphere cast against query targets.
+ *
+ * Implemented by inflating each target's bounds by the sphere radius, which is the standard
+ * conservative reduction of a sphere sweep to a ray test. Corners are therefore treated as
+ * rounded by radius rather than exactly; that over-reports contact slightly near an edge and
+ * never under-reports, which is the safe direction for a clearance query.
+ */
+export declare function sphereCastSceneTargets(targets: readonly SceneQueryTarget[], ray: SceneRay, radius: number): SceneQueryHit | undefined;
+/**
+ * Structural shape of the physics world's query surface.
+ *
+ * Structural rather than a concrete import so this module does not force `@aura3d/physics`
+ * into every consumer's graph, and so a test can supply a fake.
+ */
+export interface PhysicsQueryWorld {
+    raycast(origin: AuraVec3, direction: AuraVec3, options?: {
+        readonly maxDistance?: number;
+        readonly mask?: number;
+    }): {
+        readonly point: readonly [number, number, number];
+        readonly normal: readonly [number, number, number];
+        readonly distance: number;
+        readonly colliderId: number;
+        readonly bodyId: number;
+    } | undefined;
+    sphereCast?(origin: AuraVec3, radius: number, direction: AuraVec3, options?: {
+        readonly maxDistance?: number;
+    }): {
+        readonly point: readonly [number, number, number];
+        readonly normal: readonly [number, number, number];
+        readonly distance: number;
+    } | undefined;
+}
+/**
+ * Public raycast against a physics world.
+ *
+ * The adapter that makes `PhysicsWorld.raycast` reachable without a route importing
+ * `@aura3d/physics` directly. Returns the same {@link SceneQueryHit} shape as the pure
+ * paths, so a route can move between them without changing its call sites.
+ */
+export declare function raycastPhysicsWorld(world: PhysicsQueryWorld, ray: SceneRay): SceneQueryHit | undefined;
+/** Public sphere cast against a physics world, when the world supports one. */
+export declare function sphereCastPhysicsWorld(world: PhysicsQueryWorld, ray: SceneRay, radius: number): SceneQueryHit | undefined;
+//# sourceMappingURL=SceneQueries.d.ts.map

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

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