@aura3d/engine 1.4.5 → 1.5.1

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

@@ -0,0 +1,81 @@
+/**
+ * Reusable touch/pointer bindings for on-screen game controls.
+ *
+ * ## Why this is in the reusable layer
+ *
+ * The replicability metric's repeated-cluster detector (added in defect 113) found this code duplicated
+ * **byte-for-byte** between Skyline Runner and Turbo Drift Circuit: a `bindHoldControl` that translates
+ * pointer press/release into synthetic keyboard events, plus a `pulseKey` for momentary buttons. Two routes
+ * had independently authored the same 13 lines, and a third would have copied them again.
+ *
+ * That is precisely the duplication the brief asks the metric to surface and the reusable layer to absorb.
+ * Every public game route needs on-screen controls -- the route-primary probe gates
+ * `interactive-controls-outside-viewport` -- so this is genre-independent infrastructure, not art direction.
+ *
+ * ## Why synthetic keyboard events rather than a direct input API
+ *
+ * The routes already own a keyboard action map (`game.input({ actions: ... })`) that is the single source of
+ * truth for what a key does. Dispatching real `KeyboardEvent`s means a touch press and a physical key press
+ * travel the *same* path, so the gameplay proof that keyboard input changes state also covers the buttons.
+ * A parallel input path would need its own proof and could drift from the keyboard behaviour.
+ *
+ * Bindings are additive and idempotent per element: re-binding the same id replaces its listeners rather than
+ * stacking them, because a route that re-runs setup after a reset would otherwise fire one keydown per bind.
+ */
+/** A control that holds its key down while pressed, e.g. throttle or move-left. */
+export interface HoldControlBinding {
+    /** DOM id of the button element. Missing elements are skipped, not thrown on. */
+    readonly elementId: string;
+    /** `KeyboardEvent.code` to synthesise, e.g. `"KeyA"`. */
+    readonly code: string;
+}
+/** A control that fires one press-and-release, e.g. jump or reset. */
+export interface PulseControlBinding extends HoldControlBinding {
+    /** Milliseconds the synthetic key stays down. Defaults to 40ms. */
+    readonly holdMs?: number | undefined;
+}
+/**
+ * Minimal DOM surface this module needs.
+ *
+ * Declared structurally so the module is testable without a DOM environment. This repository runs its unit
+ * suite in plain Node with no `jsdom`, which is a deliberate convention: browser behaviour is proven in
+ * Playwright against a real browser, not against a DOM emulator. Accepting an injectable host keeps the
+ * *binding logic* -- press/release pairing, idempotence, teardown -- under fast unit coverage without
+ * pretending a shim is a browser.
+ */
+export interface TouchControlHost {
+    getElementById(id: string): TouchControlElement | null;
+    dispatchKey(code: string, type: "keydown" | "keyup"): void;
+    setTimer(callback: () => void, delayMs: number): unknown;
+    clearTimer(handle: unknown): void;
+}
+/** The element operations a control binding performs. */
+export interface TouchControlElement {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+export interface GameControlBindingSpec {
+    readonly hold?: readonly HoldControlBinding[] | undefined;
+    readonly pulse?: readonly PulseControlBinding[] | undefined;
+    /**
+     * Override the DOM/timer host. Defaults to `window`/`document`, so routes pass nothing.
+     * Exists for unit coverage of the binding logic; see `TouchControlHost`.
+     */
+    readonly host?: TouchControlHost | undefined;
+}
+export interface GameControlBindingResult {
+    /** Element ids that were found and bound. */
+    readonly bound: readonly string[];
+    /** Element ids named in the spec but absent from the DOM, so a typo is visible rather than silent. */
+    readonly missing: readonly string[];
+    /** Remove every listener this call attached. */
+    dispose(): void;
+}
+/**
+ * Bind on-screen controls to synthetic keyboard events.
+ *
+ * Returns which ids were bound and which were missing, so a route can assert its own control contract
+ * instead of discovering a typo through a failing probe.
+ */
+export declare function bindGameTouchControls(spec: GameControlBindingSpec): GameControlBindingResult;
+//# sourceMappingURL=TouchControlBinding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TouchControlBinding.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/TouchControlBinding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IACvD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,mBAAmB,EAAE,GAAG,SAAS,CAAC;IAC5D;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,wBAAwB;IACvC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sGAAsG;IACtG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gDAAgD;IAChD,OAAO,IAAI,IAAI,CAAC;CACjB;AAeD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAyE5F"}

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

@@ -0,0 +1,116 @@
+/**
+ * Reusable touch/pointer bindings for on-screen game controls.
+ *
+ * ## Why this is in the reusable layer
+ *
+ * The replicability metric's repeated-cluster detector (added in defect 113) found this code duplicated
+ * **byte-for-byte** between Skyline Runner and Turbo Drift Circuit: a `bindHoldControl` that translates
+ * pointer press/release into synthetic keyboard events, plus a `pulseKey` for momentary buttons. Two routes
+ * had independently authored the same 13 lines, and a third would have copied them again.
+ *
+ * That is precisely the duplication the brief asks the metric to surface and the reusable layer to absorb.
+ * Every public game route needs on-screen controls -- the route-primary probe gates
+ * `interactive-controls-outside-viewport` -- so this is genre-independent infrastructure, not art direction.
+ *
+ * ## Why synthetic keyboard events rather than a direct input API
+ *
+ * The routes already own a keyboard action map (`game.input({ actions: ... })`) that is the single source of
+ * truth for what a key does. Dispatching real `KeyboardEvent`s means a touch press and a physical key press
+ * travel the *same* path, so the gameplay proof that keyboard input changes state also covers the buttons.
+ * A parallel input path would need its own proof and could drift from the keyboard behaviour.
+ *
+ * Bindings are additive and idempotent per element: re-binding the same id replaces its listeners rather than
+ * stacking them, because a route that re-runs setup after a reset would otherwise fire one keydown per bind.
+ */
+/** Tracks attached listeners per element id so a re-bind replaces rather than stacks. */
+const attached = new Map();
+/** The real browser host: synthetic keyboard events on `window`, elements from `document`. */
+function browserHost() {
+    return {
+        getElementById: (id) => (typeof document === "undefined" ? null : document.getElementById(id)),
+        dispatchKey: (code, type) => window.dispatchEvent(new KeyboardEvent(type, { code, bubbles: true })),
+        setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+        clearTimer: (handle) => clearTimeout(handle)
+    };
+}
+/**
+ * Bind on-screen controls to synthetic keyboard events.
+ *
+ * Returns which ids were bound and which were missing, so a route can assert its own control contract
+ * instead of discovering a typo through a failing probe.
+ */
+export function bindGameTouchControls(spec) {
+    const host = spec.host ?? browserHost();
+    const bound = [];
+    const missing = [];
+    const teardown = [];
+    const claim = (elementId) => {
+        const element = host.getElementById(elementId);
+        if (!element) {
+            missing.push(elementId);
+            return undefined;
+        }
+        // Replace any previous binding for this id; see the note on idempotence above.
+        attached.get(elementId)?.();
+        bound.push(elementId);
+        return element;
+    };
+    for (const control of spec.hold ?? []) {
+        const element = claim(control.elementId);
+        if (!element)
+            continue;
+        const press = () => host.dispatchKey(control.code, "keydown");
+        const release = () => host.dispatchKey(control.code, "keyup");
+        element.addEventListener("pointerdown", press);
+        element.addEventListener("pointerup", release);
+        // `pointercancel` and `pointerleave` both matter: a finger sliding off a button must not latch the key on.
+        element.addEventListener("pointercancel", release);
+        element.addEventListener("pointerleave", release);
+        const remove = () => {
+            element.removeEventListener("pointerdown", press);
+            element.removeEventListener("pointerup", release);
+            element.removeEventListener("pointercancel", release);
+            element.removeEventListener("pointerleave", release);
+            // Release on teardown, so disposing mid-press cannot leave the key stuck down.
+            release();
+            attached.delete(control.elementId);
+        };
+        attached.set(control.elementId, remove);
+        teardown.push(remove);
+    }
+    for (const control of spec.pulse ?? []) {
+        const element = claim(control.elementId);
+        if (!element)
+            continue;
+        const holdMs = Math.max(1, control.holdMs ?? 40);
+        const timers = new Set();
+        const press = () => {
+            host.dispatchKey(control.code, "keydown");
+            const timer = host.setTimer(() => {
+                timers.delete(timer);
+                host.dispatchKey(control.code, "keyup");
+            }, holdMs);
+            timers.add(timer);
+        };
+        element.addEventListener("click", press);
+        const remove = () => {
+            element.removeEventListener("click", press);
+            // Clear pending release timers, or a disposed control can still dispatch after teardown.
+            for (const timer of timers)
+                host.clearTimer(timer);
+            timers.clear();
+            attached.delete(control.elementId);
+        };
+        attached.set(control.elementId, remove);
+        teardown.push(remove);
+    }
+    return {
+        bound,
+        missing,
+        dispose: () => {
+            for (const remove of teardown)
+                remove();
+        }
+    };
+}
+//# sourceMappingURL=TouchControlBinding.js.map

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

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

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

@@ -0,0 +1,192 @@
+/**
+ * Reusable vehicle chassis: contact, suspension, attitude and wheel visuals.
+ *
+ * ## The defects this addresses
+ *
+ * Turbo Drift Circuit drove a 2D kinematic point (`game.racing`) and then pinned
+ * the car's rendered Y to a single literal, `TRACK_SURFACE_Y`. That has three
+ * visible consequences:
+ *
+ * 1. **The car sinks into the tarmac.** A model grounded on a frozen plane cannot
+ *    respond to the surface it is actually over. There is no contact model, so
+ *    there is nothing to hold the tyres on the road.
+ * 2. **No suspension.** The chassis never pitches under braking, never rolls in a
+ *    corner, and the wheels never travel. A car that stays perfectly level at
+ *    111 km/h reads as a sprite sliding on a plane, which is what it is.
+ * 3. **Wheels do not turn or steer.** Nothing derived wheel spin from speed or
+ *    wheel yaw from steering input.
+ *
+ * This module is the reusable answer. It takes a planar vehicle state -- position,
+ * heading, speed, steering, lateral slip -- plus a surface query, and produces the
+ * full 3D pose a renderer needs: chassis height from four independent contact
+ * points, pitch and roll from load transfer, per-wheel suspension travel, wheel
+ * spin and steer angles, and a contact report that states whether every tyre is
+ * on the ground.
+ *
+ * It is pure: no renderer, no DOM, no asset loading. That makes vehicle behaviour
+ * unit-testable, which is the only way "the car is grounded" becomes a fact rather
+ * than an opinion about a screenshot.
+ */
+export type VehicleVec3 = readonly [number, number, number];
+/** Surface sample under one contact point. */
+export interface VehicleSurfaceSample {
+    /** World Y of the surface at the queried point. */
+    readonly height: number;
+    /** Surface normal. Defaults to world up when a track is flat. */
+    readonly normal?: VehicleVec3 | undefined;
+    /** Grip multiplier, 1 on tarmac and lower off-track. */
+    readonly grip?: number | undefined;
+}
+/**
+ * Surface the vehicle drives on.
+ *
+ * A route supplies this from its own track topology. Because the chassis asks the
+ * surface for a height at each wheel rather than being told one number, swapping
+ * the track asset cannot leave the car buried: there is no frozen plane to be
+ * wrong about.
+ */
+export interface VehicleSurface {
+    sample(x: number, z: number): VehicleSurfaceSample;
+}
+/** Flat surface at a fixed height, for prototypes and tests. */
+export declare function flatVehicleSurface(height?: number, grip?: number): VehicleSurface;
+export interface VehicleChassisSpec {
+    /** Distance between front and rear axles, world units. */
+    readonly wheelbase: number;
+    /** Distance between left and right wheels, world units. */
+    readonly trackWidth: number;
+    /** Rolling radius of a wheel, world units. Drives visual spin rate. */
+    readonly wheelRadius: number;
+    /**
+     * Ride height: distance from the wheel contact patch to the chassis origin at
+     * rest. Derived from the asset's own bounds by the caller, never guessed.
+     */
+    readonly rideHeight: number;
+    /** Suspension travel available above and below rest, world units. */
+    readonly suspensionTravel?: number | undefined;
+    /**
+     * Spring stiffness as a normalized rate. Higher is firmer: the chassis resists
+     * pitch and roll more and settles faster.
+     */
+    readonly springRate?: number | undefined;
+    /** Damping ratio. 1 is critically damped; below 1 oscillates. */
+    readonly dampingRatio?: number | undefined;
+    /** Maximum steering angle at the front wheels, radians. */
+    readonly maxSteerAngle?: number | undefined;
+    /** Maximum chassis pitch under full braking or acceleration, radians. */
+    readonly maxPitch?: number | undefined;
+    /** Maximum chassis roll at full lateral load, radians. */
+    readonly maxRoll?: number | undefined;
+}
+export interface VehiclePlanarState {
+    /** World X of the chassis centre. */
+    readonly x: number;
+    /** World Z of the chassis centre. */
+    readonly z: number;
+    /** Heading in radians, measured so that heading 0 faces +X. */
+    readonly heading: number;
+    /** Forward speed in world units per second. */
+    readonly speed: number;
+    /** Steering input, -1..1. */
+    readonly steer: number;
+    /** Throttle input, 0..1. */
+    readonly throttle?: number | undefined;
+    /** Brake input, 0..1. */
+    readonly brake?: number | undefined;
+    /** Lateral slip, 0..1, used for roll and tyre scrub. */
+    readonly slip?: number | undefined;
+}
+export type VehicleWheelId = "front-left" | "front-right" | "rear-left" | "rear-right";
+export interface VehicleWheelPose {
+    readonly id: VehicleWheelId;
+    /** World position of the wheel centre. */
+    readonly position: VehicleVec3;
+    /** Steering angle applied to this wheel, radians. Zero for rear wheels. */
+    readonly steerAngle: number;
+    /** Accumulated rolling rotation, radians. */
+    readonly spin: number;
+    /** Suspension compression, 0 at full extension and 1 at full compression. */
+    readonly compression: number;
+    /** True when this wheel's contact patch is on the surface. */
+    readonly grounded: boolean;
+    /** Distance from the contact patch to the surface. Zero when grounded. */
+    readonly contactGap: number;
+}
+export interface VehiclePose {
+    /**
+     * Chassis origin in world space: the body's centre height, as a rigid body would
+     * report it.
+     *
+     * Use this for a model whose pivot is at its own centre. For a model rendered with
+     * `scaleMode: "fit"`, use {@link groundedPosition} instead -- the safe renderer grounds
+     * a fitted model's *lowest point* on its node position, so placing the body centre
+     * there lifts the whole vehicle by its ride height. That mismatch is visible as a car
+     * hovering above the road, which is the same class of defect as the sinking it
+     * replaced, in the opposite direction.
+     */
+    readonly position: VehicleVec3;
+    /**
+     * Contact-plane position: the height the lowest tyre contact patch sits at.
+     *
+     * This is what a `scaleMode: "fit"` model's node position should be set to.
+     */
+    readonly groundedPosition: VehicleVec3;
+    /** Euler rotation: pitch on X, yaw on Y, roll on Z. */
+    readonly rotation: VehicleVec3;
+    readonly wheels: readonly VehicleWheelPose[];
+    /** Height of the lowest contact patch above the surface. */
+    readonly contactGap: number;
+    /** True when every wheel is on the ground. */
+    readonly grounded: boolean;
+    /** Mean suspension compression across all four wheels. */
+    readonly averageCompression: number;
+}
+export interface VehicleChassisTelemetry {
+    readonly speed: number;
+    readonly speedKph: number;
+    readonly pitch: number;
+    readonly roll: number;
+    readonly steerAngle: number;
+    readonly wheelSpinRate: number;
+    readonly groundedWheels: number;
+    readonly maxContactGap: number;
+    readonly averageCompression: number;
+    readonly surfaceGrip: number;
+}
+export interface VehicleChassis {
+    readonly kind: "aura-vehicle-chassis";
+    readonly spec: Required<Omit<VehicleChassisSpec, never>>;
+    /** Advance suspension and wheel state, returning the resolved 3D pose. */
+    step(dt: number, state: VehiclePlanarState): VehiclePose;
+    /** Most recent pose without advancing. */
+    pose(): VehiclePose;
+    telemetry(): VehicleChassisTelemetry;
+    /** Return to rest at a planar state, clearing suspension and spin history. */
+    reset(state: VehiclePlanarState): VehiclePose;
+}
+/**
+ * Create a vehicle chassis.
+ *
+ * `rideHeight` and `wheelRadius` should be derived from the vehicle asset's own
+ * bounds. That is the difference between this and the constant it replaces: the
+ * caller states a proportion of a measured asset, not a number that happened to
+ * look right once.
+ */
+export declare function createVehicleChassis(spec: VehicleChassisSpec, surface: VehicleSurface): VehicleChassis;
+/**
+ * Derive chassis geometry from a vehicle asset's rendered bounds.
+ *
+ * This is what removes the need for a `CAR_SCENE_HEIGHT`-style constant. Given the
+ * size the asset actually renders at, the wheelbase, track width, wheel radius and
+ * ride height follow from standard automotive proportions, so a different car
+ * produces a different chassis instead of inheriting the old one's numbers.
+ */
+export declare function vehicleChassisSpecFromBounds(size: VehicleVec3, options?: {
+    /** Fraction of the body length between the axles. Real cars sit near 0.6. */
+    readonly wheelbaseFraction?: number | undefined;
+    /** Fraction of the body width between the wheel centres. */
+    readonly trackFraction?: number | undefined;
+    /** Fraction of body height taken by wheel diameter. */
+    readonly wheelDiameterFraction?: number | undefined;
+}): VehicleChassisSpec;
+//# sourceMappingURL=VehicleChassis.d.ts.map

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

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