@aura3d/engine 1.5.0 → 1.5.2

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

@@ -3,6 +3,16 @@ import { createExternalParityEnvironmentLighting, Geometry, IndexBuffer, PBRMate
 import { DirectionalLight, PointLight, SpotLight } from "../../scene/index.js";
 import { createTypedGLBActor } from "../production-runtime/TypedGLBActor.js";
 import { AURA_NORMALIZED_MODEL_MAX_DIMENSION, boundsFromAsset, boundsHeight, boundsMaxDimension, boundsSize } from "./SceneGroundingUtils.js";
+import { createWorldLabelLayer } from "./WorldLabelRenderer.js";
+export * from "./SpatialAnchoring.js";
+export * from "./FocusSelection.js";
+export * from "./WorldLabelRenderer.js";
+export * from "./VehicleChassis.js";
+export * from "./VehicleDriverAi.js";
+export * from "./PlatformerMotion.js";
+export * from "./CombatFrameData.js";
+export * from "./SceneQueries.js";
+export * from "./ApplicationKits.js";
 export * from "./FrameEncoder.js";
 export * from "./BrowserFrameCaptureAdapter.js";
 export * from "./MediaRecorderFrameEncoder.js";
@@ -1052,6 +1062,50 @@ export const camera = {
         easing: options.easing ?? "easeInOut",
         captureTime: options.captureTime
     }),
+    /**
+     * 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.
+     */
+    orthographic: (options = {}) => ({
+        mode: "orthographic",
+        position: options.position ?? [0, 1.4, 4],
+        target: options.target ?? [0, 0.8, 0],
+        orthographicSize: options.orthographicSize ?? 1.4
+    }),
+    /**
+     * 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.
+     */
+    isometric: (options = {}) => {
+        const target = options.target ?? [0, 0, 0];
+        const distance = options.distance ?? 12;
+        const elevation = Math.atan(1 / Math.SQRT2);
+        const azimuth = Math.PI / 4;
+        const horizontal = Math.cos(elevation) * distance;
+        return {
+            mode: "isometric",
+            target,
+            distance,
+            orthographicSize: options.orthographicSize ?? 6,
+            position: options.position ?? [
+                target[0] + Math.sin(azimuth) * horizontal,
+                target[1] + Math.sin(elevation) * distance,
+                target[2] + Math.cos(azimuth) * horizontal
+            ]
+        };
+    },
     autoFrame: (options = {}) => {
         const bounds = options.bounds ?? { min: [-1, 0, -1], max: [1, 1.6, 1] };
         const center = options.target ?? [
@@ -7073,6 +7127,66 @@ function isRenderableModelNode(node) {
 function isWebGLRenderableNode(node) {
     return isRenderableModelNode(node) || node.kind === "primitive";
 }
+/**
+ * Translate scene label nodes into world-anchored labels for the label layer.
+ *
+ * `labels.callout(...)` and friends previously reached the scene snapshot and were
+ * counted by evidence but drawn only by the canvas2d fallback. Every route with a
+ * typed GLB takes the production WebGL2 path, so every production callout was
+ * silently dropped. This is the bridge that makes the public label API real in the
+ * path public routes actually use.
+ */
+function worldLabelsFromSnapshot(snapshot, runtimeNodes) {
+    const labelNodes = groups.flatten(snapshot.nodes).filter((node) => node.kind === "label");
+    return labelNodes.map((node, index) => {
+        const runtimeId = node.runtime?.id;
+        const runtimeSnapshot = runtimeId ? runtimeNodes?.get(runtimeId)?.snapshot() : undefined;
+        if (runtimeSnapshot?.visible === false) {
+            return {
+                id: node.name ?? `${node.label}-${index + 1}`,
+                text: node.text,
+                anchor: [0, 0, 0],
+                offscreenPolicy: "hide"
+            };
+        }
+        const position = (runtimeSnapshot?.position ?? node.position ?? labelDefaultPosition(node));
+        const anchor = node.anchorWorldPosition ?? position;
+        // Screen offset is derived from the gap between the label box and its anchor,
+        // projected as a vertical nudge. A label that requests no separate anchor sits
+        // directly on its own position.
+        const separated = node.anchorWorldPosition !== undefined;
+        return {
+            id: node.name ?? `${node.label}-${index + 1}`,
+            text: node.text,
+            anchor: [position[0], position[1], position[2]],
+            leaderAnchor: [anchor[0], anchor[1], anchor[2]],
+            screenOffset: separated ? [0, 0] : [0, -26],
+            color: typeof node.color === "string" ? node.color : undefined,
+            background: typeof node.background === "string" ? node.background : undefined,
+            // `size` is authored in world units for scene labels; map it onto a legible
+            // pixel range rather than using it directly as a font size.
+            fontSize: Math.max(11, Math.min(26, Math.round((node.size ?? 0.34) * 46))),
+            leader: node.leader === true,
+            offscreenPolicy: node.offscreenPolicy ?? (node.label === "hud" ? "draw" : "clamp"),
+            ...(node.label === "hud" && node.screenAnchor ? { screenAnchor: node.screenAnchor } : {}),
+            ...(node.label === "hud" && !node.screenAnchor ? { screenAnchor: "top-left" } : {})
+        };
+    });
+}
+/**
+ * Mount the world-label layer for a canvas, if the scene has any label nodes.
+ *
+ * Returns `undefined` in headless or label-free scenes so nothing is created that
+ * would then need disposing.
+ */
+function createSceneLabelLayer(canvas, snapshot) {
+    if (!canvas || typeof document === "undefined")
+        return undefined;
+    const hasLabels = groups.flatten(snapshot.nodes).some((node) => node.kind === "label");
+    if (!hasLabels)
+        return undefined;
+    return createWorldLabelLayer({ container: canvas.parentElement ?? document.body, canvas });
+}
 async function startProductionRender(canvas, snapshot, diagnosticsState, options, overlay, beforeRender, isPaused = () => false, runtimeNodes) {
     const renderableNode = snapshot.nodes.find(isWebGLRenderableNode);
     if (!renderableNode) {
@@ -7081,6 +7195,7 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
     const renderer = await createProductionSceneRenderer(canvas, snapshot, options.renderer, runtimeNodes);
     diagnosticsState.renderer = renderer.diagnostics;
     const continuousRender = shouldContinuouslyRender(snapshot);
+    const labelLayer = createSceneLabelLayer(canvas, snapshot);
     let disposed = false;
     let animationHandle = 0;
     let lastTime = 0;
@@ -7098,6 +7213,13 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
         diagnosticsState.renderSize = [canvas.width, canvas.height];
         diagnosticsState.evidence = collectAuraSceneEvidence(snapshot);
         diagnosticsState.renderer = renderer.diagnostics;
+        if (labelLayer) {
+            // Reproject every frame against the renderer's own camera so labels track
+            // their anchors while the camera moves.
+            labelLayer.setLabels(worldLabelsFromSnapshot(snapshot, runtimeNodes));
+            labelLayer.update(renderer.viewProjection(time));
+            diagnosticsState.labels = labelLayer.snapshot();
+        }
         overlay?.update();
         if (continuousRender && options.autoStart !== false && typeof requestAnimationFrame !== "undefined") {
             animationHandle = requestAnimationFrame(renderFrame);
@@ -7112,6 +7234,7 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
             disposed = true;
             if (animationHandle && typeof cancelAnimationFrame !== "undefined")
                 cancelAnimationFrame(animationHandle);
+            labelLayer?.dispose();
             renderer.dispose();
         }
     };
@@ -7699,6 +7822,9 @@ async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOp
             latestFeatures = result.features;
             return latestDeviceDiagnostics.drawCalls;
         },
+        viewProjection(time) {
+            return createViewProjection(snapshot, canvas.width / Math.max(1, canvas.height), time, runtimeNodes);
+        },
         dispose() {
             productionRenderer.dispose();
             for (const { actor } of actorEntries)
@@ -8411,6 +8537,9 @@ async function createWebGLSceneRenderer(canvas, snapshot, rendererOptions, runti
             }
             return drawCalls;
         },
+        viewProjection(time) {
+            return createViewProjection(snapshot, canvas.width / Math.max(1, canvas.height), time, runtimeNodes);
+        },
         dispose() {
             for (const modelEntry of models) {
                 const textures = new Set();
@@ -9715,7 +9844,9 @@ function createViewProjection(snapshot, aspect, time, runtimeNodes) {
     const target = resolveCameraTarget(snapshot, cameraSpec, runtimeNodes);
     const eye = resolveCameraEye(snapshot, cameraSpec, time, runtimeNodes);
     const view = lookAt(eye, target, [0, 1, 0]);
-    const projection = perspective(((cameraSpec.fov ?? 45) * Math.PI) / 180, aspect, 0.05, 100);
+    const projection = isOrthographicCameraMode(cameraSpec.mode)
+        ? orthographic(cameraSpec.orthographicSize ?? 1.4, aspect, 0.05, 100)
+        : perspective(((cameraSpec.fov ?? 45) * Math.PI) / 180, aspect, 0.05, 100);
     return multiply4(projection, view);
 }
 function createModelMatrix(node, bounds, normalizeToUnit, time = 0) {
@@ -9792,6 +9923,20 @@ function primitiveSize(node) {
         return [node.size, node.size, node.size];
     return node.size ?? [1, 1, 1];
 }
+export function isOrthographicCameraMode(mode) {
+    return mode === "orthographic" || mode === "isometric";
+}
+function orthographic(halfHeight, aspect, near, far) {
+    const safeHalfHeight = Math.max(1e-4, halfHeight);
+    const halfWidth = Math.max(1e-4, safeHalfHeight * aspect);
+    const nf = 1 / (near - far);
+    return new Float32Array([
+        1 / halfWidth, 0, 0, 0,
+        0, 1 / safeHalfHeight, 0, 0,
+        0, 0, 2 * nf, 0,
+        0, 0, (far + near) * nf, 1
+    ]);
+}
 function perspective(fovRadians, aspect, near, far) {
     const f = 1 / Math.tan(fovRadians / 2);
     const nf = 1 / (near - far);
@@ -10110,7 +10255,8 @@ function snapshotDiagnostics(value) {
         evidence: value.evidence,
         renderer: value.renderer,
         warnings: [...value.warnings],
-        errors: [...value.errors]
+        errors: [...value.errors],
+        ...(value.labels ? { labels: value.labels } : {})
     };
 }
 function collectGeneratedCodeWarnings(snapshot) {