Skip to content

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.

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.mjs
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
index 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) => (
<div
key={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.css
index 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 every
diff --git a/desktop/tests/viewport-math.test.ts b/desktop/tests/viewport-math.test.ts
index 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.json
index 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.json
index 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.md
index 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: number
halfW: 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): boolean
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: number
halfW: 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): boolean
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: number
halfW: 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): boolean
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: number
halfW: 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): boolean
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: number
halfW: 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): boolean
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.snap
index 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.ts
index 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.ts
index 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.mjs
index 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',
};