@aura3d/engine 1.5.1 → 2.0.0

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

@@ -1,6 +1,20 @@
-import { type Collider, type ColliderDescriptor, type CollisionEvent, type Constraint, type ConstraintDescriptor, type Contact, type DebugLine, type PhysicsBackendSelection, type PhysicsShape, type PhysicsSnapshot, type PhysicsWorldDescriptor, type RaycastHit, type RaycastOptions, type RigidBody, type RigidBodyDescriptor, type RigidBodyType, type ScenePhysicsNode, type SphereCastHit } from "@aura3d/physics";
+import type { Collider, ColliderDescriptor, CollisionEvent, Constraint, ConstraintDescriptor, Contact, DebugLine, PhysicsBackendSelection, PhysicsShape, PhysicsSnapshot, PhysicsWorldDescriptor, RaycastHit, RaycastOptions, RigidBody, RigidBodyDescriptor, RigidBodyType, ScenePhysicsNode, SphereCastHit } from "@aura3d/physics";
 import { type ProjectedLabel } from "./WorldLabelRenderer.js";
+import { defineAuraCustomGeometry, type AuraCustomGeometrySpec, type AuraText3DGeometry, type AuraText3DOptions } from "./RootGeometry.js";
+export * from "./RootGeometry.js";
 export * from "./SpatialAnchoring.js";
+export * from "./PhysicsRuntime.js";
+/**
+ * WS-2.4: mesh surface queries on the public surface.
+ *
+ * Re-exported from `@aura3d/physics` so grounding anything to a mesh is a one-liner for any
+ * genre, from `@aura3d/engine` alone. Without this a route wanting real per-point ground
+ * height had to either deep-import `@aura3d/physics/src` (banned by the lint rule) or
+ * hand-roll an analytic approximation — which is exactly what every racing route did, and
+ * why wheels sank through visible road.
+ */
+export { buildMeshBVH, createMeshSurfaceQuery, raycastMesh, type MeshBVH, type MeshRayHit, type MeshSurfaceQuery, type MeshSurfaceQueryOptions, type SurfaceSample } from "@aura3d/physics/solverless";
+import { type AuraCollisionLayers, type AuraPhysicsRuntime } from "./PhysicsRuntime.js";
 export * from "./FocusSelection.js";
 export * from "./WorldLabelRenderer.js";
 export * from "./VehicleChassis.js";
@@ -13,16 +27,12 @@ export * from "./FrameEncoder.js";
 export * from "./BrowserFrameCaptureAdapter.js";
 export * from "./MediaRecorderFrameEncoder.js";
 export * from "./WebCodecsFrameEncoder.js";
-export * from "./FfmpegFrameEncoder.js";
-export * from "./PngSequenceEncoder.js";
-export * from "./AudioMuxer.js";
 export { GameInspector, createGameInspector } from "./GameInspector.js";
 export type { GameInspectorRuntimeInput, GameInspectorSnapshot } from "./GameInspector.js";
 import { createGameInspector } from "./GameInspector";
 export { createGameAudio } from "../game/GameAudio.js";
 export type { GameAudio, GameAudioBusDefinition, GameAudioBusId, GameAudioContextLike, GameAudioCueDefinition, GameAudioCueEvent, GameAudioEvidence, GameAudioOptions } from "../game/GameAudio.js";
 export * from "./RenderProgressTracker.js";
-export * from "./VideoExportPipeline.js";
 export * from "./AudioVisemeAnalyzer.js";
 export * from "./ExternalPhonemeAnalyzer.js";
 export * from "./WaveformVisualizer.js";
@@ -34,12 +44,7 @@ export * from "./CameraPresetLibrary.js";
 export * from "./ShotCompositionRules.js";
 export * from "./CameraChoreographer.js";
 export * from "./CameraPathEditor.js";
-export * from "./CaptionExporter.js";
 export * from "./ThumbnailGenerator.js";
-export * from "./YouTubeMetadataGenerator.js";
-export * from "./YouTubeUploadAdapter.js";
-export * from "./PublishingPipeline.js";
-export * from "./CloudRenderAdapter.js";
 export * from "./BatchEpisodeRenderer.js";
 export * from "./AnimationAssetManifest.js";
 export * from "./SceneGroundingUtils.js";
@@ -123,7 +128,7 @@ export * from "./TouchControlBinding.js";
 export * from "./AssetLibraryBrowser.js";
 export type AuraVec3 = readonly [number, number, number];
 export type AuraColor = `#${string}` | string;
-export type AuraAssetType = "model" | "texture" | "environment" | "audio";
+export type AuraAssetType = "model" | "texture" | "environment" | "audio" | "navigation";
 export type AuraModelFormat = "glb" | "gltf";
 export type AuraTextureFormat = "png" | "jpg" | "jpeg" | "webp" | "ktx2";
 export type AuraProceduralTextureKind = "fabric-normal" | "rubber-roughness" | "brushed-metal-anisotropy" | "plastic-micro-scratch";
@@ -160,6 +165,11 @@ export interface AuraAssetMetadata {
     };
     readonly thumbnailUrl?: string;
     readonly license?: string;
+    readonly author?: string;
+    readonly provenance?: {
+        readonly sourceUrl?: string;
+        readonly [key: string]: unknown;
+    };
 }
 declare const auraAssetRefBrand: unique symbol;
 export type AuraAssetRef<TType extends AuraAssetType = AuraAssetType, TId extends string = string> = AuraAssetDefinition & {
@@ -303,6 +313,8 @@ export interface AuraModelOptions extends AuraTransformSpec {
     readonly targetMaxDimension?: number;
     readonly targetLength?: number;
     readonly physics?: AuraNodePhysicsSpec;
+    /** Exact glTF node names to suppress when composing a typed model into a route. */
+    readonly hiddenNodeNames?: readonly string[];
 }
 export interface AuraPrimitiveOptions extends AuraTransformSpec {
     readonly name?: string;
@@ -311,6 +323,23 @@ export interface AuraPrimitiveOptions extends AuraTransformSpec {
     readonly castShadow?: boolean;
     readonly receiveShadow?: boolean;
     readonly physics?: AuraNodePhysicsSpec;
+    readonly instances?: readonly AuraTransformSpec[];
+    readonly instanceColors?: readonly AuraColor[];
+    readonly geometry?: AuraCustomGeometrySpec;
+    readonly text3D?: Omit<AuraText3DGeometry, "geometry">;
+    readonly lod?: AuraRootLodSpec;
+}
+export type AuraBuiltinPrimitive = "box" | "sphere" | "plane" | "cylinder" | "capsule" | "torus";
+export interface AuraRootLodLevelSpec {
+    readonly name: string;
+    readonly maxDistance?: number;
+    readonly primitive?: AuraBuiltinPrimitive;
+    readonly geometry?: AuraCustomGeometrySpec;
+    readonly material?: AuraMaterialSpec;
+}
+export interface AuraRootLodSpec {
+    readonly levels: readonly AuraRootLodLevelSpec[];
+    readonly hysteresis?: number;
 }
 export interface AuraAnimationSpec {
     readonly clip?: string;
@@ -449,11 +478,12 @@ export interface AuraModelNode extends AuraTransformSpec {
     readonly animation?: AuraAnimationSpec;
     readonly interaction?: AuraInteractionSpec;
     readonly physics?: AuraNodePhysicsSpec;
+    readonly hiddenNodeNames?: readonly string[];
     readonly runtime?: AuraRuntimeNodeSpec;
 }
 export interface AuraPrimitiveNode extends AuraTransformSpec {
     readonly kind: "primitive";
-    readonly primitive: "box" | "sphere" | "plane" | "cylinder" | "capsule" | "torus";
+    readonly primitive: AuraBuiltinPrimitive | "custom";
     readonly name?: string;
     readonly material?: AuraMaterialSpec;
     readonly size?: number | AuraVec3;
@@ -463,6 +493,11 @@ export interface AuraPrimitiveNode extends AuraTransformSpec {
     readonly interaction?: AuraInteractionSpec;
     readonly physics?: AuraNodePhysicsSpec;
     readonly runtime?: AuraRuntimeNodeSpec;
+    readonly instances?: readonly AuraTransformSpec[];
+    readonly instanceColors?: readonly AuraColor[];
+    readonly geometry?: AuraCustomGeometrySpec;
+    readonly text3D?: Omit<AuraText3DGeometry, "geometry">;
+    readonly lod?: AuraRootLodSpec;
 }
 export interface AuraGroupNode extends AuraTransformSpec {
     readonly kind: "group";
@@ -673,6 +708,8 @@ export interface AuraRendererDiagnosticReport {
         readonly requestedPasses: readonly string[];
         readonly actualPasses: readonly string[];
         readonly fallbackPasses: readonly string[];
+        /** Device-observed render-target format used by the mounted composer. */
+        readonly targetFormat?: "rgba8" | "rgba16f" | "rgba32f";
         readonly evidence: string;
     };
     readonly runtime: {
@@ -681,6 +718,16 @@ export interface AuraRendererDiagnosticReport {
         readonly postprocessVerified: boolean;
         readonly passNames: readonly string[];
         readonly warnings: readonly string[];
+        readonly nativeInstancedSubmissions: number;
+        readonly submittedObjects: number;
+        readonly visibleObjects: number;
+        readonly culledObjects: number;
+        readonly frustumTestedObjects: number;
+        readonly lodSelections: readonly {
+            readonly nodeName: string;
+            readonly levelIndex: number;
+            readonly levelName: string;
+        }[];
     };
     readonly environment: {
         readonly enabled: boolean;
@@ -811,6 +858,41 @@ export declare const primitives: {
     readonly capsule: (options?: AuraPrimitiveOptions) => AuraNodeBuilder<AuraPrimitiveNode>;
     readonly torus: (options?: AuraPrimitiveOptions) => AuraNodeBuilder<AuraPrimitiveNode>;
 };
+export declare const instances: {
+    readonly box: (options: AuraPrimitiveOptions & {
+        readonly transforms: readonly AuraTransformSpec[];
+        readonly colors?: readonly AuraColor[];
+    }) => AuraNodeBuilder<AuraPrimitiveNode>;
+    readonly sphere: (options: AuraPrimitiveOptions & {
+        readonly transforms: readonly AuraTransformSpec[];
+        readonly colors?: readonly AuraColor[];
+    }) => AuraNodeBuilder<AuraPrimitiveNode>;
+    readonly plane: (options: AuraPrimitiveOptions & {
+        readonly transforms: readonly AuraTransformSpec[];
+        readonly colors?: readonly AuraColor[];
+    }) => AuraNodeBuilder<AuraPrimitiveNode>;
+    readonly cylinder: (options: AuraPrimitiveOptions & {
+        readonly transforms: readonly AuraTransformSpec[];
+        readonly colors?: readonly AuraColor[];
+    }) => AuraNodeBuilder<AuraPrimitiveNode>;
+    readonly capsule: (options: AuraPrimitiveOptions & {
+        readonly transforms: readonly AuraTransformSpec[];
+        readonly colors?: readonly AuraColor[];
+    }) => AuraNodeBuilder<AuraPrimitiveNode>;
+    readonly torus: (options: AuraPrimitiveOptions & {
+        readonly transforms: readonly AuraTransformSpec[];
+        readonly colors?: readonly AuraColor[];
+    }) => AuraNodeBuilder<AuraPrimitiveNode>;
+};
+export declare const geometry: {
+    readonly define: typeof defineAuraCustomGeometry;
+    readonly custom: (spec: AuraCustomGeometrySpec, options?: Omit<AuraPrimitiveOptions, "geometry">) => AuraNodeBuilder<AuraPrimitiveNode>;
+};
+export declare function text3D(text: string, options?: AuraText3DOptions & Omit<AuraPrimitiveOptions, "geometry" | "text3D">): AuraNodeBuilder<AuraPrimitiveNode>;
+export declare function distanceLod(options: Omit<AuraPrimitiveOptions, "lod" | "geometry"> & {
+    readonly levels: readonly AuraRootLodLevelSpec[];
+    readonly hysteresis?: number;
+}): AuraNodeBuilder<AuraPrimitiveNode>;
 export declare const groups: {
     readonly create: typeof group;
     readonly flatten: (nodes: readonly AuraSceneNode[]) => readonly AuraSceneNode[];
@@ -908,7 +990,7 @@ export declare const lights: {
         readonly intensity?: number;
     }) => AuraNodeBuilder<AuraLightNode>;
 };
-export type AuraCameraMode = "perspective" | "orbit" | "dolly" | "follow" | "path" | "flythrough";
+export type AuraCameraMode = "perspective" | "orbit" | "dolly" | "follow" | "path" | "flythrough" | "orthographic" | "isometric";
 export interface AuraCameraSpec {
     readonly mode: AuraCameraMode;
     readonly position?: AuraVec3;
@@ -926,6 +1008,16 @@ export interface AuraCameraSpec {
     readonly captureTime?: number;
     readonly smoothing?: number;
     readonly subjectEmphasis?: number;
+    /**
+     * Half-height of the orthographic frustum, in world units.
+     *
+     * Orthographic projection has no field of view, so this is what sets image
+     * scale: the camera sees `orthographicSize` units above and below its target
+     * regardless of how far away it sits. Horizontal extent follows from the
+     * viewport aspect, which keeps the image square-on rather than stretched.
+     * Ignored by every perspective mode.
+     */
+    readonly orthographicSize?: number;
 }
 export interface AuraBoundsSpec {
     readonly min: AuraVec3;
@@ -962,6 +1054,28 @@ export declare const camera: {
         readonly from?: AuraVec3;
         readonly to?: AuraVec3;
     }) => AuraCameraSpec;
+    /**
+     * A parallel-projection camera: no foreshortening, so equal world lengths
+     * occupy equal screen lengths wherever they sit in depth.
+     *
+     * Reach for this when the projection is part of the meaning rather than a
+     * stylistic choice — CAD and engineering views, floor plans, technical
+     * diagrams, sprite and texture bakes, chart axes, and product shots that must
+     * read as measurable. A long-lens perspective camera approximates it but
+     * still converges, which is visible on long straight edges.
+     */
+    readonly orthographic: (options?: Omit<AuraCameraSpec, "mode">) => AuraCameraSpec;
+    /**
+     * The conventional isometric view: an orthographic camera on a 45-degree
+     * azimuth and a ~35.264-degree elevation.
+     *
+     * That elevation is `atan(1 / sqrt(2))`, the angle at which the three world
+     * axes project to equal screen lengths and 120 degrees apart. Authoring it as
+     * a preset matters because the value is not memorable and an approximation
+     * such as 30 or 45 degrees produces the subtly-wrong grid alignment that
+     * isometric tile art immediately reveals.
+     */
+    readonly isometric: (options?: Omit<AuraCameraSpec, "mode">) => AuraCameraSpec;
     readonly autoFrame: (options?: {
         readonly bounds?: AuraBoundsSpec;
         readonly target?: AuraVec3;
@@ -1179,11 +1293,13 @@ export interface AuraCityStateChangeEvidence {
 }
 export interface AuraCityInstancingPlan {
     readonly kind: "aura-city-instancing-plan";
-    readonly rendererPath: "auraWebGL2PrimitiveBatches";
+    readonly rendererPath: "productionRuntimeNativeInstancing";
     readonly windows: number;
     readonly props: number;
     readonly roadMarkings: number;
     readonly lights: number;
+    readonly nativeInstanceGroups: number;
+    readonly nativeInstances: number;
     readonly groups: readonly string[];
     readonly instanced: boolean;
 }
@@ -2243,6 +2359,16 @@ export declare const promptRecipes: {
     readonly "mini-game": (asset: AuraAssetRef<"model">, plan: AuraPromptPlan) => AuraSceneBuilder;
     readonly "material-studio": (asset: AuraAssetRef<"model">, plan: AuraPromptPlan) => AuraSceneBuilder;
 };
+/**
+ * Which backend a mounted app is drawing with.
+ *
+ * `"canvas2d"` is **internal and diagnostic-only** (WS-2.5). It is never selected for a scene that
+ * declares renderable content: such a scene either renders through WebGL2/WebGPU or raises a diagnosable
+ * error. It appears here because `diagnostics().backend` can still report it for a scene with nothing to
+ * render, and hiding that would make the diagnostic less useful, not more honest.
+ *
+ * Do not treat a `"canvas2d"` reading as a render. See `renderDiagnosticPreviewToCanvas`.
+ */
 export type AuraBackend = "webgl2" | "webgpu" | "canvas2d" | "headless";
 export interface AuraDiagnostics {
     readonly backend: AuraBackend;
@@ -2459,12 +2585,71 @@ export interface AuraApp {
     readonly backend: AuraBackend;
     readonly nodes: AuraRuntimeNodeRegistry;
     readonly runtime: AuraRuntimeState;
+    /**
+     * The live physics simulation for this app.
+     *
+     * This is the seam that makes `@aura3d/engine` a game engine rather than a scene
+     * declaration format. Before it existed, `.physics({ type: "dynamic" })` let a developer
+     * watch a box fall and nothing else: no force, no collision callback, no raycast, no
+     * joint. Every genre outside the four bundled kits had no path at all.
+     *
+     * Bodies declared on scene nodes are registered here under their node name, so
+     * `app.physics.bodies.require("crate").applyImpulse([4, 0, 0])` works with no extra setup.
+     */
+    readonly physics: AuraPhysicsRuntime;
     setScene(scene: AuraSceneBuilder | AuraSceneSnapshot): void;
     onFrame(callback: AuraFrameCallback): () => void;
     offFrame(callback: AuraFrameCallback): void;
     input(options: GameInputOptions): ReturnType<typeof createGameInput>;
     pause(): void;
     resume(): void;
+    /**
+     * Resolves once the renderer has finished mounting and a frame can be drawn.
+     *
+     * WS-2.9. The production WebGL renderer mounts asynchronously, so immediately after
+     * `createAuraApp` returns there is a window in which nothing can be drawn yet. `step(dt)` used to
+     * fall through to a Canvas-2D path in that window and render nothing, with no warning — a blank
+     * image for anyone writing a headless capture or a deterministic test.
+     *
+     * Awaiting this is the fix, and it exists because a warning that says "wait for the mount" is
+     * useless without a way to wait:
+     *
+     * ```ts
+     * const app = createAuraApp(canvas, { scene, autoStart: false });
+     * await app.ready();
+     * app.step(1 / 60);           // now renders
+     * ```
+     *
+     * Resolves immediately for a scene with no async mount, and resolves — rather than rejecting — if
+     * the mount fails, because the failure is already reported through `diagnostics().errors` and a
+     * rejection here would make the common `await app.ready()` line throw for a diagnosable condition.
+     */
+    ready(): Promise<void>;
+    /**
+     * Subscribe to WebGL context loss. Returns an unsubscribe function.
+     *
+     * WS-2.6. A lost context is not something a developer can prevent — the browser reclaims GPU
+     * resources under memory pressure, on driver reset, or when a tab is backgrounded too long. What they
+     * can do is be told, and until 1.6 they could not be: `WebGL2Device` has tracked and handled
+     * `webglcontextlost` for a long time, but nothing surfaced it, so the only symptom reaching a
+     * developer was a canvas that stopped updating.
+     *
+     * That distinction is why the parity table listed this as a gap while the listeners existed. The
+     * device layer was never the gap; the absence of a public signal was.
+     *
+     * ```ts
+     * app.onDeviceLost(() => showReconnectingOverlay());
+     * app.onDeviceRestored(() => hideReconnectingOverlay());
+     * ```
+     *
+     * Registering before the renderer has mounted is safe: the subscription is held and attached when the
+     * device arrives, so a caller does not have to await `ready()` first.
+     */
+    onDeviceLost(listener: () => void): () => void;
+    /** Subscribe to WebGL context restoration. Returns an unsubscribe function. See {@link onDeviceLost}. */
+    onDeviceRestored(listener: () => void): () => void;
+    /** True while the WebGL context is lost, so a caller can check state rather than only react to events. */
+    deviceLost(): boolean;
     step(dt?: number): void;
     diagnostics(): AuraDiagnostics;
     evidence(options?: GameRuntimeEvidenceOptions): ReturnType<typeof collectGameRuntimeEvidenceV105>;
@@ -2473,6 +2658,21 @@ export interface AuraApp {
 }
 export interface AuraCreateAppOptions {
     readonly scene: AuraSceneBuilder | AuraSceneSnapshot;
+    /**
+     * Configuration for {@link AuraApp.physics}.
+     *
+     * `layers` has to be supplied here rather than per body, because a collision mask is only
+     * meaningful relative to the complete set of layers: building the bitmask for "bullet"
+     * requires knowing every layer that exists. Without this option a developer could call
+     * `createCollisionLayers` and then have nowhere to put the result — which is exactly the
+     * hole the clean-room top-down shooter hit, since "bullets hit enemies but not each other"
+     * is the first thing any shooter needs.
+     */
+    readonly physics?: {
+        readonly layers?: AuraCollisionLayers | undefined;
+        /** World gravity. Defaults to `[0, -9.81, 0]`; top-down games usually want zero. */
+        readonly gravity?: readonly [number, number, number] | undefined;
+    };
     readonly diagnostics?: boolean | AuraDiagnosticsOptions;
     readonly renderer?: AuraCreateAppRendererOptions;
     readonly pixelRatio?: number;
@@ -2501,6 +2701,31 @@ export declare class AuraRuntimeError extends Error {
     constructor(code: AuraRuntimeError["code"], message: string);
 }
 export declare function createAuraApp(target: AuraAppTarget, options: AuraCreateAppOptions): AuraApp;
+/**
+ * Control surface for every app mounted on this page.
+ *
+ * Exposed on `globalThis.__AURA3D_LIVE_APPS__` as well as being exported, so a Playwright
+ * `page.evaluate` can reach it without the route having to opt in.
+ */
+export interface AuraAppRegistry {
+    readonly kind: "aura3d-live-app-registry";
+    /** Number of apps currently mounted. */
+    count(): number;
+    /** Pause every app's frame loop. Returns how many were paused. */
+    pauseAll(): number;
+    /** Resume every app's frame loop. */
+    resumeAll(): number;
+    /**
+     * Pause every app and advance each by a fixed number of fixed-size steps.
+     *
+     * This is what makes a capture reproducible: rather than photographing an arbitrary moment of a
+     * live loop, a caller settles every scene to a *named* frame — the same `steps` and `dt` always
+     * produce the same state, so a screenshot hash becomes a stable thing to approve.
+     */
+    settle(steps?: number, dt?: number): number;
+    all(): readonly AuraApp[];
+}
+export declare const auraAppRegistry: AuraAppRegistry;
 export declare function createGameApp(target: AuraAppTarget, options: AuraCreateGameAppOptions): GameAppRuntime<AuraApp>;
 export declare function createAuraRouteHealthSnapshot(app: AuraApp): {
     readonly status: "ready" | "error";
@@ -2538,4 +2763,5 @@ interface ProductionBoundsProbe {
  * silently producing mismatched framing.
  */
 export declare function auraProductionBoundsProbes(): readonly ProductionBoundsProbe[];
+export declare function isOrthographicCameraMode(mode: AuraCameraMode): boolean;
 //# sourceMappingURL=index.d.ts.map