A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(editor): a camera says where it looks
esengine9c87dda29883
diff --git a/desktop/scripts/editor-checks/camera-frustum.mjs b/desktop/scripts/editor-checks/camera-frustum.mjsnew file mode 100644index 000000000..09dd0510a--- /dev/null+++ b/desktop/scripts/editor-checks/camera-frustum.mjs@@ -0,0 +1,103 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file camera-frustum — a camera's view volume reaches the viewport.+ *+ * The geometry is unit-tested (frustumCornersWorld, cameraFrustumCorners,+ * frustumPlaneCrossings). What no unit test can say is whether the field, the+ * per-frame projection and the overlay's paths are still connected: the gizmo is+ * DOM over the canvas, so `capture_viewport` cannot see it and only the+ * composited window can.+ *+ * A perspective camera is what makes the claim testable — its near and far faces+ * are different sizes, so the volume is pixels the framing outline alone never+ * draws. Under an orthographic camera seen head-on they would coincide.+ */+import { cp } from 'node:fs/promises';+import path from 'node:path';+import { makeProject, checker, DESKTOP } from '../lib/editorDriver.mjs';++const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');++/** One perspective camera, well off the content plane, plus something to look at. */+const SCENE = JSON.stringify({+ version: 1, name: 'Main',+ entities: [+ {+ id: 0, name: 'Cam', parent: null, children: [], visible: true,+ components: [+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 400 } } },+ {+ type: 'Camera',+ data: {+ projectionType: 0, fov: 60, nearPlane: 50, farPlane: 700,+ isActive: true, priority: 0,+ },+ },+ ],+ },+ {+ id: 1, name: 'Marker', parent: null, children: [], visible: true,+ components: [+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 0 } } },+ { type: 'Sprite', data: { size: { x: 60, y: 60 }, color: { r: 0.2, g: 0.6, b: 0.3, a: 1 } } },+ ],+ },+ ],+}, null, 1);++export const name = 'camera-frustum';+export const describes = "a camera's view volume is drawn when, and only when, the camera asks";++/**+ * Pixels that differ between two captures, counted over the viewport only — the+ * title bar, the panels and a toast all change on their own schedule, and a+ * whole-window count would drown a thin dashed outline in that.+ */+function changedPixels(a, b) {+ let n = 0;+ const y1 = Math.round(Math.min(a.h, b.h) * 0.7);+ const x1 = Math.round(Math.min(a.w, b.w) * 0.55);+ for (let y = Math.round(Math.min(a.h, b.h) * 0.18); y < y1; y++) {+ for (let x = Math.round(Math.min(a.w, b.w) * 0.05); x < x1; x++) {+ const p = a.px(x, y);+ const q = b.px(x, y);+ if (Math.abs(p[0] - q[0]) > 8 || Math.abs(p[1] - q[1]) > 8 || Math.abs(p[2] - q[2]) > 8) n++;+ }+ }+ return n;+}++export async function run(ed) {+ const root = await makeProject({ 'assets/scenes/main.esscene': SCENE });+ await cp(path.join(EXAMPLE, 'project.esproject'), path.join(root, 'project.esproject'));+ await cp(path.join(EXAMPLE, 'src'), path.join(root, 'src'), { recursive: true });+ const check = checker();+ await ed.open(root, 'assets/scenes/main.esscene');++ const showFrustum = (on) =>+ ed.call('set_field', { entity: 0, component: 'Camera', key: 'showFrustum', type: 'bool', value: on }, 30000);++ const off = await ed.screenshot('frustum-off');+ await showFrustum(true);+ await ed.sleep(800);+ const on = await ed.screenshot('frustum-on');++ const drawn = changedPixels(off, on);+ if (!check(drawn > 200, `turning showFrustum on changed ${drawn} pixels — the volume is not being drawn`)) {+ return check.failures;+ }++ // ...and the field is what draws it. Without this a viewport that redrew+ // something else on every set_field would pass the first claim.+ await showFrustum(false);+ await ed.sleep(800);+ const back = await ed.screenshot('frustum-back');+ check(+ changedPixels(off, back) < drawn / 5,+ `turning showFrustum back off left ${changedPixels(off, back)} pixels changed against the `+ + `original ${drawn} — the volume is not what came and went`,+ );++ return check.failures;+}diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.tsindex 17e7c1461..101f71295 100644--- a/desktop/src/engine/ViewportController.ts+++ b/desktop/src/engine/ViewportController.ts@@ -14,7 +14,7 @@ import {layerOrderOf,editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, EDITOR_UI_ANCHOR,entityWorldBox, uiNodeWorldBox, meshWorldBox, editorViewIsOrbited,- editorViewAxes, editorViewAxisAngles, type ScreenAxis,+ editorViewAxes, editorViewAxisAngles, cameraFrustumCorners, type ScreenAxis,type TilesetModel, type TileCollisionPiece, type TileGridParams,} from 'esengine';import type { EntityId } from '@/types';@@ -24,6 +24,7 @@ import { SceneModel } from './SceneModel';import {type OBB,type ClientRect,+ frustumPlaneCrossings,quatAngleZ,obbCorners,pointInOBB,@@ -713,40 +714,51 @@ export const ViewportController = {},/**- * Screen-space icon position + authored view rect (CSS px) of a scene camera,- * for drawing its gizmo. The rect is the camera's authored framing (orthoSize- * half-height × the viewport aspect) — what that game camera is set to see.+ * Screen-space gizmo of a scene camera: its icon, what it frames on z = 0, and+ * — when asked — its view volume, as SVG paths in CSS px. The corners come from+ * the camera's own view-projection inverted, so a perspective or tilted one+ * draws what it really sees; `frame` is empty for a camera aimed off the plane.*/getCameraGizmo(id: EntityId,- ): { cx: number; cy: number; rect: { x: number; y: number; w: number; h: number } } | null {+ withVolume = false,+ ): { cx: number; cy: number; frame: string; volume: string } | null {const world = EngineHost.world;- const canvas = EngineHost.canvas;- if (!world || !canvas || !world.valid(id) || !world.has(id, Camera) || !world.has(id, Transform)) {+ if (!world || !world.valid(id) || !world.has(id, Camera) || !world.has(id, Transform)) {return null;}const t = world.get(id, Transform);- const c = world.get(id, Camera) as { orthoSize?: number };- const halfH = c.orthoSize ?? 360;- const aspect = canvas.height > 0 ? canvas.width / canvas.height : 1;- const halfW = halfH * aspect;- const x = t.worldPosition.x;- const y = t.worldPosition.y;- const toClient = this.projectorFor(id);- const center = toClient(x, y);+ const c = world.get(id, Camera);+ const screen = this.screenInfo();+ const corners = cameraFrustumCorners(+ c as Parameters<typeof cameraFrustumCorners>[0],+ t as Parameters<typeof cameraFrustumCorners>[1],+ screen.designResolution.x, screen.designResolution.y, screen,+ );+ const center = this.worldToClient(t.worldPosition.x, t.worldPosition.y, t.worldPosition.z);if (!center) return null;- const corners = [- [x - halfW, y - halfH],- [x + halfW, y - halfH],- [x + halfW, y + halfH],- [x - halfW, y + halfH],- ].map(([wx, wy]) => toClient(wx, wy));- if (corners.some((p) => !p)) return null;- const xs = corners.map((p) => p!.x);- const ys = corners.map((p) => p!.y);- const minX = Math.min(...xs);- const minY = Math.min(...ys);- return { cx: center.x, cy: center.y, rect: { x: minX, y: minY, w: Math.max(...xs) - minX, h: Math.max(...ys) - minY } };++ const at = (i: number): { x: number; y: number } | null =>+ this.worldToClient(corners[i * 3]!, corners[i * 3 + 1]!, corners[i * 3 + 2]!);+ const ring = (pts: ({ x: number; y: number } | null)[]): string =>+ pts.some((p) => !p) ? ''+ : `M${pts.map((p) => `${p!.x.toFixed(1)} ${p!.y.toFixed(1)}`).join('L')}Z`;++ // A camera looking along the content plane has edges that never reach it,+ // and then there is no frame to draw.+ const crossings = frustumPlaneCrossings(corners, 0)+ .map((p) => (p ? this.worldToClient(p.x, p.y, 0) : null));++ let volume = '';+ if (withVolume) {+ const near = [at(0), at(1), at(2), at(3)];+ const far = [at(4), at(5), at(6), at(7)];+ const edges = near.every(Boolean) && far.every(Boolean)+ ? near.map((p, i) => `M${p!.x.toFixed(1)} ${p!.y.toFixed(1)}L${far[i]!.x.toFixed(1)} ${far[i]!.y.toFixed(1)}`).join('')+ : '';+ volume = `${ring(near)}${ring(far)}${edges}`;+ }+ return { cx: center.x, cy: center.y, frame: ring(crossings), volume };},/** Ids of the scene's Light2D entities — the light-gizmo set (structural). */diff --git a/desktop/src/engine/viewportMath.ts b/desktop/src/engine/viewportMath.tsindex ace132ba6..f783b741d 100644--- a/desktop/src/engine/viewportMath.ts+++ b/desktop/src/engine/viewportMath.ts@@ -204,3 +204,29 @@ export function axisIndicatorEnds(}return ends.sort((a, b) => a.depth - b.depth);}++/**+ * Where each of a frustum's four side edges crosses the plane z = `planeZ`, in+ * the corner order `cameraFrustumCorners` returns (near face, then far). An edge+ * that never reaches the plane yields null, so a caller with any null has no+ * quadrilateral to draw rather than a made-up one.+ */+export function frustumPlaneCrossings(+ corners: ArrayLike<number>,+ planeZ: number,+): ({ x: number; y: number } | null)[] {+ const out: ({ x: number; y: number } | null)[] = [];+ for (let i = 0; i < 4; i++) {+ const n = i * 3;+ const f = 12 + i * 3;+ const span = corners[f + 2]! - corners[n + 2]!;+ const k = Math.abs(span) > 1e-6 ? (planeZ - corners[n + 2]!) / span : -1;+ out.push(k >= 0 && k <= 1+ ? {+ x: corners[n]! + (corners[f]! - corners[n]!) * k,+ y: corners[n + 1]! + (corners[f + 1]! - corners[n + 1]!) * k,+ }+ : null);+ }+ return out;+}diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsxindex 36ecf424d..2943776e7 100644--- a/desktop/src/panels/Viewport.tsx+++ b/desktop/src/panels/Viewport.tsx@@ -1656,16 +1656,22 @@ export function Viewport() {const camsOn = ready && showG && !useEditorStore.getState().isPlaying;for (const [cid, wrap] of camRefs.current) {if (!wrap) continue;- const cg = camsOn ? ViewportController.getCameraGizmo(cid) : null;+ // `showFrustum` is an editor-only field, so it is read from the document+ // rather than the projected World, which has no member for it.+ const csrc = SceneModel.sourceFor(cid);+ const cdata = csrc != null+ ? SceneModel.entityBySource(csrc)?.components.find((c) => c.type === 'Camera')?.data+ : undefined;+ const cg = camsOn+ ? ViewportController.getCameraGizmo(cid, (cdata as { showFrustum?: boolean } | undefined)?.showFrustum === true)+ : null;if (cg) {wrap.style.opacity = '1';const icon = wrap.firstElementChild as HTMLElement | null;- const rectEl = wrap.lastElementChild as HTMLElement | null;if (icon) icon.style.transform = `translate(${cg.cx}px, ${cg.cy}px)`;- if (rectEl) {- rectEl.style.transform = `translate(${cg.rect.x}px, ${cg.rect.y}px)`;- rectEl.style.width = `${cg.rect.w}px`;- rectEl.style.height = `${cg.rect.h}px`;+ for (const [sel, d] of [['.viewport__cam-frame', cg.frame],+ ['.viewport__cam-volume', cg.volume]] as const) {+ (wrap.querySelector(sel) as SVGPathElement | null)?.setAttribute('d', d);}} else {wrap.style.opacity = '0';@@ -2437,7 +2443,8 @@ export function Viewport() {onDrop={onDrop}/>- {/* Scene-camera gizmos (icon + authored view rect); positioned by the rAF. */}+ {/* Scene-camera gizmos (icon + what the camera frames, + its volume when the+ camera asks for it); projected by the rAF. */}{camIds.map((id) => (<divkey={id}@@ -2449,7 +2456,10 @@ export function Viewport() {aria-hidden="true"><Camera className="viewport__cam-icon" size={15} strokeWidth={1.75} />- <div className="viewport__cam-rect" />+ <svg className="viewport__cam-shape">+ <path className="viewport__cam-frame" />+ <path className="viewport__cam-volume" />+ </svg></div>))}diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.cssindex e2e72e832..5cf9f4259 100644--- a/desktop/src/theme/app.css+++ b/desktop/src/theme/app.css@@ -387,13 +387,26 @@color: var(--star-hi);filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.75));}-.viewport__cam-rect {+.viewport__cam-shape {position: absolute;- left: 0;- top: 0;- border: 1px dashed var(--star-line);- border-radius: 2px;- background: rgba(76, 143, 214, 0.04);+ inset: 0;+ width: 100%;+ height: 100%;+ overflow: visible;+}+.viewport__cam-frame {+ fill: rgba(76, 143, 214, 0.04);+ stroke: var(--star-line);+ stroke-width: 1;+ stroke-dasharray: 4 3;+}+/* The view volume: the same line, unfilled, so the near and far faces read as+ depth rather than as two more framings. */+.viewport__cam-volume {+ fill: none;+ stroke: color-mix(in srgb, var(--star-line) 60%, transparent);+ stroke-width: 1;+ stroke-dasharray: 2 3;}/* Cover capture (ProjectStore.captureThumbnail): for the capture frame, hide everydiff --git a/desktop/tests/viewport-math.test.ts b/desktop/tests/viewport-math.test.tsindex 2ae3c842b..c9303d14d 100644--- a/desktop/tests/viewport-math.test.ts+++ b/desktop/tests/viewport-math.test.ts@@ -18,6 +18,7 @@ import {worldToLocal2D,rankPickCandidates,axisIndicatorEnds,+ frustumPlaneCrossings,type PickCandidate,} from '@/engine/viewportMath';import { LayerOrder, layerOrderOf } from 'esengine';@@ -218,3 +219,37 @@ describe('the view-axis indicator', () => {expect(keys[keys.length - 1]).toBe('z+');});});++describe('frustumPlaneCrossings', () => {+ /** Eight corners: near face bl, br, tr, tl at z = `nz`, the same square at `fz`. */+ const box = (nz: number, fz: number, half = 10): Float32Array => {+ const xy = [[-half, -half], [half, -half], [half, half], [-half, half]];+ return Float32Array.from([+ ...xy.flatMap(([x, y]) => [x!, y!, nz]),+ ...xy.flatMap(([x, y]) => [x!, y!, fz]),+ ]);+ };++ it('meets the plane halfway down an edge that spans it', () => {+ const pts = frustumPlaneCrossings(box(10, -10), 0);+ expect(pts.map((p) => p && [p.x, p.y])).toEqual([[-10, -10], [10, -10], [10, 10], [-10, 10]]);+ });++ it('interpolates x and y along the edge, not just z', () => {+ // A volume that widens with depth: at three quarters of the way down, the+ // crossing is three quarters of the way out.+ const c = Float32Array.from([+ -1, -1, 3, 1, -1, 3, 1, 1, 3, -1, 1, 3,+ -5, -5, -1, 5, -5, -1, 5, 5, -1, -5, 5, -1,+ ]);+ const pts = frustumPlaneCrossings(c, 0);+ expect(pts[0]!.x).toBeCloseTo(-4);+ expect(pts[0]!.y).toBeCloseTo(-4);+ });++ it('reports no crossing for edges that never reach the plane', () => {+ // Entirely in front of it, and lying parallel to it.+ expect(frustumPlaneCrossings(box(10, 1), 0)).toEqual([null, null, null, null]);+ expect(frustumPlaneCrossings(box(5, 5), 0)).toEqual([null, null, null, null]);+ });+});diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex cd0f516ab..8bcc70655 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -2,11 +2,11 @@"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {"public": 113,- "beta": 62,+ "beta": 65,"experimental": 1530,"deprecated": 3},- "total": 1705,+ "total": 1708,"subsystems": [{"id": "ecs",@@ -1720,6 +1720,30 @@"minigame"]},+ {+ "name": "CameraFields",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "CameraTransformFields",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "CharacterController","kind": "const",@@ -2200,6 +2224,18 @@"minigame"]},+ {+ "name": "cameraFrustumCorners",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "captureFramePixels","kind": "function",diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 8ad1b4c34..c40009590 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -373,6 +373,7 @@"key": "showFrustum","type": "boolean","default": "false",+ "doc": "Draw this camera's whole view volume in the editor, not just what it frames on the content plane.","advanced": true}],diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex e99985cc9..ea9f6045e 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 55 beta · 1415 experimental · 3 deprecated+Symbols: 113 public · 58 beta · 1415 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1519,6 +1519,21 @@ halfH: numberhalfW: number```+## CameraFields — interface @beta+```+clearFlags: number+cullingMask: number | undefined+farPlane: number+fov: number+isActive: boolean+nearPlane: number+orthoSize: number+pixelPerfect: boolean+priority: number+projectionType: number+viewport: { x: number; y: number; z: number; w: number; }+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1553,6 +1568,12 @@ viewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```+## CameraTransformFields — interface @beta+```+position: { x: number; y: number; z: number; }+rotation: { x: number; y: number; z: number; w: number; }+```+## CameraView — const @experimental```ResourceDef<CameraViewAPI>@@ -9092,6 +9113,11 @@ BtPlugin(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number```+## cameraFrustumCorners — function @beta+```+(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array+```+## canCaptureFramePixels — function @experimental```(module: ESEngineModule): booleandiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 919eac4aa..b44e55d14 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 60 beta · 1434 experimental · 3 deprecated+Symbols: 113 public · 63 beta · 1434 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1519,6 +1519,21 @@ halfH: numberhalfW: number```+## CameraFields — interface @beta+```+clearFlags: number+cullingMask: number | undefined+farPlane: number+fov: number+isActive: boolean+nearPlane: number+orthoSize: number+pixelPerfect: boolean+priority: number+projectionType: number+viewport: { x: number; y: number; z: number; w: number; }+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1553,6 +1568,12 @@ viewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```+## CameraTransformFields — interface @beta+```+position: { x: number; y: number; z: number; }+rotation: { x: number; y: number; z: number; w: number; }+```+## CameraView — const @experimental```ResourceDef<CameraViewAPI>@@ -9300,6 +9321,11 @@ BtPlugin(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number```+## cameraFrustumCorners — function @beta+```+(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array+```+## canCaptureFramePixels — function @experimental```(module: ESEngineModule): booleandiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex bbeec89d6..9690d17ba 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 57 beta · 1414 experimental · 3 deprecated+Symbols: 113 public · 60 beta · 1414 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1514,6 +1514,21 @@ halfH: numberhalfW: number```+## CameraFields — interface @beta+```+clearFlags: number+cullingMask: number | undefined+farPlane: number+fov: number+isActive: boolean+nearPlane: number+orthoSize: number+pixelPerfect: boolean+priority: number+projectionType: number+viewport: { x: number; y: number; z: number; w: number; }+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1548,6 +1563,12 @@ viewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```+## CameraTransformFields — interface @beta+```+position: { x: number; y: number; z: number; }+rotation: { x: number; y: number; z: number; w: number; }+```+## CameraView — const @experimental```ResourceDef<CameraViewAPI>@@ -9087,6 +9108,11 @@ BtPlugin(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number```+## cameraFrustumCorners — function @beta+```+(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array+```+## canCaptureFramePixels — function @experimental```(module: ESEngineModule): booleandiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 6b457cbf5..3cd184e7f 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 55 beta · 1435 experimental · 3 deprecated+Symbols: 113 public · 58 beta · 1435 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1514,6 +1514,21 @@ halfH: numberhalfW: number```+## CameraFields — interface @beta+```+clearFlags: number+cullingMask: number | undefined+farPlane: number+fov: number+isActive: boolean+nearPlane: number+orthoSize: number+pixelPerfect: boolean+priority: number+projectionType: number+viewport: { x: number; y: number; z: number; w: number; }+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1548,6 +1563,12 @@ viewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```+## CameraTransformFields — interface @beta+```+position: { x: number; y: number; z: number; }+rotation: { x: number; y: number; z: number; w: number; }+```+## CameraView — const @experimental```ResourceDef<CameraViewAPI>@@ -9332,6 +9353,11 @@ BtPlugin(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number```+## cameraFrustumCorners — function @beta+```+(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array+```+## canCaptureFramePixels — function @experimental```(module: ESEngineModule): booleandiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex ea4dd293b..2836a6122 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 55 beta · 1425 experimental · 3 deprecated+Symbols: 113 public · 58 beta · 1425 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1514,6 +1514,21 @@ halfH: numberhalfW: number```+## CameraFields — interface @beta+```+clearFlags: number+cullingMask: number | undefined+farPlane: number+fov: number+isActive: boolean+nearPlane: number+orthoSize: number+pixelPerfect: boolean+priority: number+projectionType: number+viewport: { x: number; y: number; z: number; w: number; }+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1548,6 +1563,12 @@ viewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```+## CameraTransformFields — interface @beta+```+position: { x: number; y: number; z: number; }+rotation: { x: number; y: number; z: number; w: number; }+```+## CameraView — const @experimental```ResourceDef<CameraViewAPI>@@ -9114,6 +9135,11 @@ BtPlugin(sourceX: number, sourceY: number, listenerX: number, listenerY: number, maxDistance: number): number```+## cameraFrustumCorners — function @beta+```+(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array+```+## canCaptureFramePixels — function @experimental```(module: ESEngineModule): booleandiff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 2fbfb2d83..0e6059886 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -25,7 +25,10 @@ import { RenderPipeline } from '../render/renderPipeline';import { Renderer } from '../render/renderer';import { platformNow, platformDevicePixelRatio } from '../platform';import { SceneManager } from '../scene/sceneManager';-import { ortho, perspective, invertViewZ, invertViewOrbit, invertViewQuat, multiply, IDENTITY } from '../math/mat4';+import {+ ortho, perspective, invertViewZ, invertViewOrbit, invertViewQuat, multiply,+ frustumCornersWorld, IDENTITY,+} from '../math/mat4';// =============================================================================// Camera Info@@ -182,10 +185,38 @@ export function snapToPixelGrid(value: number, worldPerPixel: number): number {return worldPerPixel > 0 ? Math.round(value / worldPerPixel) * worldPerPixel : value;}+/**+ * The Camera fields a POV is read from. Named as a shape rather than as one+ * registry's return type, because the editor reads the same fields off its own+ * projected World.+ *+ * @beta+ */+export interface CameraFields {+ isActive: boolean;+ projectionType: number;+ orthoSize: number;+ fov: number;+ nearPlane: number;+ farPlane: number;+ viewport: { x: number; y: number; z: number; w: number };+ clearFlags: number;+ priority: number;+ pixelPerfect: boolean;+ /** Absent on a core built before the field; that camera drew every layer. */+ cullingMask?: number;+}++/** The placement a POV is read from — see {@link CameraFields}. @beta */+export interface CameraTransformFields {+ position: { x: number; y: number; z: number };+ rotation: { x: number; y: number; z: number; w: number };+}+function readCameraPOV(entity: number,- camera: ReturnType<CppRegistry['getCamera']>,- transform: ReturnType<CppRegistry['getTransform']>,+ camera: CameraFields,+ transform: CameraTransformFields,): CameraPOV {const q = transform.rotation;return {@@ -285,6 +316,29 @@ export function buildCameraInfo(return cam;}+const _frustumPool: CameraInfo[] = [];++/**+ * The eight world-space corners of what a camera sees — near face then far, in+ * the order {@link frustumCornersWorld} documents. Built through the same POV →+ * CameraInfo path a frame is, so it carries the projection, the tilt and the+ * design-resolution framing. @p width / @p height are the frame it renders into.+ *+ * @beta+ */+export function cameraFrustumCorners(+ camera: CameraFields,+ transform: CameraTransformFields,+ width: number,+ height: number,+ canvas: CanvasScale | null,+ result?: Float32Array,+): Float32Array {+ const pov = readCameraPOV(0, camera, transform);+ const info = buildCameraInfo(pov, width, height, canvas, _frustumPool, 0);+ return frustumCornersWorld(info.viewProjection, result);+}+// =============================================================================// Camera Collection// =============================================================================diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex b4b2924b0..888de020e 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -54,6 +54,8 @@ export { CameraBounds } from './camera/CameraBounds';export type { CameraBoundsData } from './camera/CameraBounds';export type { CameraDirectorState } from './camera/CameraDirector';export type { CameraPOV } from './camera/CameraPlugin';+export { cameraFrustumCorners } from './camera/CameraPlugin';+export type { CameraFields, CameraTransformFields } from './camera/CameraPlugin';export { computeEffectiveOrthoSize, uiLayoutRect, EDITOR_VIEW_ENTITY, EDITOR_UI_ANCHOR } from './camera/uiLayoutRect';export type { CameraExtents, CanvasScale, WorldRect } from './camera/uiLayoutRect';diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.tsindex 587c8bf93..aeac0d49e 100644--- a/sdk/src/ecs/component.ts+++ b/sdk/src/ecs/component.ts@@ -893,7 +893,11 @@ export const Camera = defineBuiltin<CameraData>('Camera',clearFlags: { flags: [{ label: 'Color', value: 1 }, { label: 'Depth', value: 2 }] },// showFrustum is a TS-only editor field (no C++ Camera member), so its// metadata can't come from an annotation.- showFrustum: { advanced: true },+ showFrustum: {+ advanced: true,+ tooltip: 'Draw this camera\'s whole view volume in the editor, not just what it '+ + 'frames on the content plane.',+ },},});diff --git a/sdk/src/math/mat4.ts b/sdk/src/math/mat4.tsindex 09338da9d..c77dada28 100644--- a/sdk/src/math/mat4.ts+++ b/sdk/src/math/mat4.ts@@ -181,3 +181,85 @@ export const IDENTITY = new Float32Array([0, 0, 1, 0,0, 0, 0, 1,]);++/**+ * General 4x4 inverse (cofactor expansion). A singular matrix yields the+ * untouched `result` — callers treat that as "no inverse" rather than NaN.+ *+ * The view/projection builders above have exact inverses of their own; this is+ * for a matrix nobody can name, such as a composed view-projection.+ */+export function invertMatrix4(m: Float32Array, result?: Float32Array): Float32Array {+ const out = result ?? new Float32Array(16);++ const a00 = m[0], a01 = m[1], a02 = m[2], a03 = m[3];+ const a10 = m[4], a11 = m[5], a12 = m[6], a13 = m[7];+ const a20 = m[8], a21 = m[9], a22 = m[10], a23 = m[11];+ const a30 = m[12], a31 = m[13], a32 = m[14], a33 = m[15];++ const b00 = a00 * a11 - a01 * a10;+ const b01 = a00 * a12 - a02 * a10;+ const b02 = a00 * a13 - a03 * a10;+ const b03 = a01 * a12 - a02 * a11;+ const b04 = a01 * a13 - a03 * a11;+ const b05 = a02 * a13 - a03 * a12;+ const b06 = a20 * a31 - a21 * a30;+ const b07 = a20 * a32 - a22 * a30;+ const b08 = a20 * a33 - a23 * a30;+ const b09 = a21 * a32 - a22 * a31;+ const b10 = a21 * a33 - a23 * a31;+ const b11 = a22 * a33 - a23 * a32;++ let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;+ if (det === 0) return out;+ det = 1.0 / det;++ out[0] = (a11 * b11 - a12 * b10 + a13 * b09) * det;+ out[1] = (a02 * b10 - a01 * b11 - a03 * b09) * det;+ out[2] = (a31 * b05 - a32 * b04 + a33 * b03) * det;+ out[3] = (a22 * b04 - a21 * b05 - a23 * b03) * det;+ out[4] = (a12 * b08 - a10 * b11 - a13 * b07) * det;+ out[5] = (a00 * b11 - a02 * b08 + a03 * b07) * det;+ out[6] = (a32 * b02 - a30 * b05 - a33 * b01) * det;+ out[7] = (a20 * b05 - a22 * b02 + a23 * b01) * det;+ out[8] = (a10 * b10 - a11 * b08 + a13 * b06) * det;+ out[9] = (a01 * b08 - a00 * b10 - a03 * b06) * det;+ out[10] = (a30 * b04 - a31 * b02 + a33 * b00) * det;+ out[11] = (a21 * b02 - a20 * b04 - a23 * b00) * det;+ out[12] = (a11 * b07 - a10 * b09 - a12 * b06) * det;+ out[13] = (a00 * b09 - a01 * b07 + a02 * b06) * det;+ out[14] = (a31 * b01 - a30 * b03 - a32 * b00) * det;+ out[15] = (a20 * b03 - a21 * b01 + a22 * b00) * det;++ return out;+}++const _invVP = new Float32Array(16);++/**+ * The eight world-space corners of what a view-projection sees: near face (bl,+ * br, tr, tl) then far, as 24 floats. Read off the matrix's INVERSE, so+ * projection, orbit and tilt all come from the one thing that decides the frame;+ * they are the unit cube's, in the [-1, 1] depth range the builders above use.+ */+export function frustumCornersWorld(viewProjection: Float32Array,+ result?: Float32Array): Float32Array {+ const out = result ?? new Float32Array(24);+ // Cleared first because a singular matrix leaves the inverse untouched, and+ // the scratch would then still hold the LAST camera's — corners that look+ // like a frustum and belong to something else.+ const inv = invertMatrix4(viewProjection, _invVP.fill(0));+ for (let i = 0; i < 8; i++) {+ const x = (i & 1) ? 1 : -1;+ const y = (i & 2) ? 1 : -1;+ const z = (i & 4) ? 1 : -1;+ const w = inv[3] * x + inv[7] * y + inv[11] * z + inv[15];+ const s = w !== 0 ? 1 / w : 0;+ // Corner order runs bl, br, tr, tl per face — the ring a line strip walks.+ const at = (i & 4 ? 12 : 0) + [0, 3, 9, 6][i & 3]!;+ out[at] = (inv[0] * x + inv[4] * y + inv[8] * z + inv[12]) * s;+ out[at + 1] = (inv[1] * x + inv[5] * y + inv[9] * z + inv[13]) * s;+ out[at + 2] = (inv[2] * x + inv[6] * y + inv[10] * z + inv[14]) * s;+ }+ return out;+}diff --git a/sdk/src/ui/util/math.ts b/sdk/src/ui/util/math.tsindex f08616407..77b2428d5 100644--- a/sdk/src/ui/util/math.ts+++ b/sdk/src/ui/util/math.ts@@ -1,5 +1,12 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+// The general 4x4 inverse lives in the math layer beside the projections it+// undoes; re-exported here because this module is where the UI already reaches+// for it.+import { invertMatrix4 } from '../../math/mat4';++export { invertMatrix4 };+export interface ScreenRect {x: number;y: number;@@ -15,51 +22,6 @@ export function intersectRects(a: ScreenRect, b: ScreenRect): ScreenRect {return { x, y, w: Math.max(0, r - x), h: Math.max(0, t - y) };}-export function invertMatrix4(m: Float32Array, result?: Float32Array): Float32Array {- const out = result ?? new Float32Array(16);-- const a00 = m[0], a01 = m[1], a02 = m[2], a03 = m[3];- const a10 = m[4], a11 = m[5], a12 = m[6], a13 = m[7];- const a20 = m[8], a21 = m[9], a22 = m[10], a23 = m[11];- const a30 = m[12], a31 = m[13], a32 = m[14], a33 = m[15];-- const b00 = a00 * a11 - a01 * a10;- const b01 = a00 * a12 - a02 * a10;- const b02 = a00 * a13 - a03 * a10;- const b03 = a01 * a12 - a02 * a11;- const b04 = a01 * a13 - a03 * a11;- const b05 = a02 * a13 - a03 * a12;- const b06 = a20 * a31 - a21 * a30;- const b07 = a20 * a32 - a22 * a30;- const b08 = a20 * a33 - a23 * a30;- const b09 = a21 * a32 - a22 * a31;- const b10 = a21 * a33 - a23 * a31;- const b11 = a22 * a33 - a23 * a32;-- let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;- if (det === 0) return out;- det = 1.0 / det;-- out[0] = (a11 * b11 - a12 * b10 + a13 * b09) * det;- out[1] = (a02 * b10 - a01 * b11 - a03 * b09) * det;- out[2] = (a31 * b05 - a32 * b04 + a33 * b03) * det;- out[3] = (a22 * b04 - a21 * b05 - a23 * b03) * det;- out[4] = (a12 * b08 - a10 * b11 - a13 * b07) * det;- out[5] = (a00 * b11 - a02 * b08 + a03 * b07) * det;- out[6] = (a32 * b02 - a30 * b05 - a33 * b01) * det;- out[7] = (a20 * b05 - a22 * b02 + a23 * b01) * det;- out[8] = (a10 * b10 - a11 * b08 + a13 * b06) * det;- out[9] = (a01 * b08 - a00 * b10 - a03 * b06) * det;- out[10] = (a30 * b04 - a31 * b02 + a33 * b00) * det;- out[11] = (a21 * b02 - a20 * b04 - a23 * b00) * det;- out[12] = (a11 * b07 - a10 * b09 - a12 * b06) * det;- out[13] = (a00 * b09 - a01 * b07 + a02 * b06) * det;- out[14] = (a31 * b01 - a30 * b03 - a32 * b00) * det;- out[15] = (a20 * b03 - a21 * b01 + a22 * b00) * det;-- return out;-}-/*** Unprojects one NDC point, depth included.*diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex 9b487122c..b9fb4a5eb 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -93,6 +93,7 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho},"showFrustum": {"advanced": true,+ "tooltip": "Draw this camera's whole view volume in the editor, not just what it frames on the content plane.",},},"Canvas": {diff --git a/sdk/tests/camera-pov.test.ts b/sdk/tests/camera-pov.test.tsindex 3ec19ca33..881b10459 100644--- a/sdk/tests/camera-pov.test.ts+++ b/sdk/tests/camera-pov.test.ts@@ -6,7 +6,9 @@* is the decoupling point a camera director will blend over (Phase C).*/import { describe, it, expect } from 'vitest';-import { buildCameraInfo, snapToPixelGrid, type CameraPOV } from '../src/camera/CameraPlugin';+import {+ buildCameraInfo, cameraFrustumCorners, snapToPixelGrid, type CameraPOV,+} from '../src/camera/CameraPlugin';import { ProjectionType, ClearFlags } from '../src/ecs/component';function ndc(vp: Float32Array, x: number, y: number) {@@ -85,3 +87,62 @@ describe('camera POV → view-projection', () => {expect(cam.viewProjection.some((v) => v !== 0)).toBe(true);});});++describe('cameraFrustumCorners', () => {+ const camera = (over: Record<string, unknown> = {}) => ({+ isActive: true,+ projectionType: ProjectionType.Orthographic,+ orthoSize: 300,+ fov: 60,+ nearPlane: 0.1,+ farPlane: 1000,+ viewport: { x: 0, y: 0, z: 1, w: 1 },+ clearFlags: ClearFlags.ColorAndDepth,+ priority: 0,+ pixelPerfect: false,+ cullingMask: 0xFFFFFFFF,+ ...over,+ });+ const transform = (over: Record<string, unknown> = {}) => ({+ position: { x: 0, y: 0, z: 10 },+ rotation: { x: 0, y: 0, z: 0, w: 1 },+ ...over,+ });+ type CamArg = Parameters<typeof cameraFrustumCorners>[0];+ type TrArg = Parameters<typeof cameraFrustumCorners>[1];+ const corners = (c: ReturnType<typeof camera>, t: ReturnType<typeof transform>,+ w = 800, h = 600) =>+ cameraFrustumCorners(c as unknown as CamArg, t as unknown as TrArg, w, h, null,+ new Float32Array(24));++ it('frames the authored ortho rect, aspect included', () => {+ // orthoSize is the half-HEIGHT; 800x600 makes the half-width 400.+ const c = corners(camera(), transform());+ expect(c[0]).toBeCloseTo(-400, 3);+ expect(c[1]).toBeCloseTo(-300, 3);+ expect(c[6]).toBeCloseTo(400, 3); // near top-right+ expect(c[7]).toBeCloseTo(300, 3);+ });++ it('follows the camera, and its tilt with it', () => {+ const moved = corners(camera(), transform({ position: { x: 100, y: 50, z: 10 } }));+ expect(moved[0]).toBeCloseTo(-300, 3);+ expect(moved[1]).toBeCloseTo(-250, 3);+ // Pitched 90° about X the camera looks along -Y, so its frame leaves the+ // z = 0 plane entirely — the corners' z spread rather than their x.+ const s = Math.sin(Math.PI / 4);+ const pitched = corners(camera(), transform({ rotation: { x: s, y: 0, z: 0, w: s } }));+ const zs = [pitched[2]!, pitched[5]!, pitched[8]!, pitched[11]!];+ expect(Math.max(...zs) - Math.min(...zs)).toBeGreaterThan(500);+ });++ it('is a real perspective volume when the camera says so', () => {+ const c = corners(camera({ projectionType: ProjectionType.Perspective, fov: 90 }),+ transform());+ // 90° fov: the near face's half-height is its distance from the eye.+ const nearHalfH = Math.abs(c[7]!);+ const farHalfH = Math.abs(c[19]!);+ expect(nearHalfH).toBeCloseTo(0.1, 3);+ expect(farHalfH / nearHalfH).toBeCloseTo(1000 / 0.1, -1); // float32 ratio+ });+});diff --git a/sdk/tests/mat4.test.ts b/sdk/tests/mat4.test.tsindex ea4429d14..bfe88a4b2 100644--- a/sdk/tests/mat4.test.ts+++ b/sdk/tests/mat4.test.ts@@ -9,7 +9,9 @@* point transforms as out[r] = Σ_c m[c*4+r] · v[c].*/import { describe, it, expect } from 'vitest';-import { ortho, perspective, invertTranslation, invertViewZ, multiply, IDENTITY } from '../src/math/mat4';+import {+ ortho, perspective, invertTranslation, invertViewZ, multiply, frustumCornersWorld, IDENTITY,+} from '../src/math/mat4';const close = (a: number, b: number, eps = 1e-6) => expect(Math.abs(a - b)).toBeLessThanOrEqual(eps);@@ -146,3 +148,39 @@ describe('mat4 shared scratch buffers (footgun contract)', () => {expect(IDENTITY[5]).toBe(1);});});++describe('mat4.frustumCornersWorld', () => {+ // Corner i: near face bl, br, tr, tl (i = 0..3), then the far face.+ const corner = (c: Float32Array, i: number): [number, number, number] =>+ [c[i * 3]!, c[i * 3 + 1]!, c[i * 3 + 2]!];++ it('undoes an orthographic view-projection back to its own box', () => {+ // The camera sits at z = 10 looking down -Z; the symmetric ortho depth range+ // puts the near face BEHIND it, which is what the box really is.+ const vp = snap(multiply(snap(ortho(-400, 400, -300, 300, -1000, 1000)),+ snap(invertViewZ(0, 0, 10, 1, 0))));+ const c = frustumCornersWorld(vp);+ expect(corner(c, 0).map((v) => Math.round(v))).toEqual([-400, -300, 1010]);+ expect(corner(c, 2).map((v) => Math.round(v))).toEqual([400, 300, 1010]);+ expect(corner(c, 4).map((v) => Math.round(v))).toEqual([-400, -300, -990]);+ expect(corner(c, 6).map((v) => Math.round(v))).toEqual([400, 300, -990]);+ });++ it('opens out with distance under a perspective projection', () => {+ // 90° vertical fov, aspect 2: the near face is 2x1 half-extents at z = -1,+ // and the far face ten times that at z = -10.+ const vp = snap(perspective(Math.PI / 2, 2, 1, 10));+ const c = frustumCornersWorld(vp);+ const [nx, ny, nz] = corner(c, 2);+ close(nx, 2, 1e-4); close(ny, 1, 1e-4); close(nz, -1, 1e-4);+ const [fx, fy, fz] = corner(c, 6);+ close(fx, 20, 1e-3); close(fy, 10, 1e-3); close(fz, -10, 1e-3);+ });++ it('collapses to the origin for a matrix with no inverse', () => {+ // Not "whatever the scratch held": a singular matrix has no frustum, and the+ // previous camera's corners would be indistinguishable from this one's.+ frustumCornersWorld(snap(perspective(Math.PI / 2, 2, 1, 10)));+ expect(Array.from(frustumCornersWorld(new Float32Array(16)))).toEqual(new Array(24).fill(0));+ });+});diff --git a/tools/check-component-fields.mjs b/tools/check-component-fields.mjsindex 96c6b9a67..bad96a05b 100644--- a/tools/check-component-fields.mjs+++ b/tools/check-component-fields.mjs@@ -27,7 +27,6 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');* says which, so the list reads as work rather than as permission.*/const DECLARED_GAPS = {- 'Camera.showFrustum': 'an editor-only flag for drawing a camera\'s view volume, which nothing draws yet','TilemapLayer.originOffset': "Tiled's per-tileset tileoffset, which the loader does not read either",'TilemapLayer.tilesetRows': 'written by the Tiled loader; nothing bounds-checks a tile id against it yet',};