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(camera): the camera a frame was drawn with is a value anyone can hold
yhh433713758c33
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex c56ac19dd..adace87e3 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": 91,+ "beta": 96,"experimental": 1824,"deprecated": 3},- "total": 2028,+ "total": 2033,"subsystems": [{"id": "ecs",@@ -1825,6 +1825,30 @@"minigame"]},+ {+ "name": "CameraCommit",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "CameraCommitData",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "CameraData","kind": "interface",@@ -1849,6 +1873,18 @@"minigame"]},+ {+ "name": "CameraLens",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "CameraTransformFields","kind": "interface",@@ -2234,6 +2270,18 @@"minigame"]},+ {+ "name": "PresentedCameraView",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "ProjectionType","kind": "enum",@@ -2763,6 +2811,18 @@"index.node"]},+ {+ "name": "presentedCameraView",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "removeNode","kind": "function",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex f76ccda28..3a6e8ad3a 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 · 84 beta · 1663 experimental · 3 deprecated+Symbols: 113 public · 89 beta · 1663 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1694,6 +1694,22 @@ minX: numberminY: number```+## CameraCommit — const @beta+```+ResourceDef<CameraCommitData>+```++## CameraCommitData — interface @beta+```+revision: number+valid: boolean+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraData — interface @beta```aspectRatio: number@@ -1759,6 +1775,15 @@ renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```+## CameraLens — interface @beta+```+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1817,7 +1842,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null-static new (app_: App): CameraViewAPI+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPIstatic prototype: CameraViewAPI```@@ -2545,7 +2570,7 @@ ScreenScalingData## DEFAULT_UI_CAMERA_INFO — const @experimental```-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }```## DODGE_KEY — const @experimental@@ -6553,6 +6578,11 @@ generation: number | undefinedquery: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"```+## PresentedCameraView — const @beta+```+ResourceDef<CameraViewAPI>+```+## ProbedRegistrations — interface @experimental```fingerprint: string@@ -9512,6 +9542,7 @@ SizeY = 11## UICameraData — interface @beta```+revision: numberscreenH: numberscreenW: numbervalid: boolean@@ -12618,6 +12649,11 @@ PrefabsPlugin(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>```+## presentedCameraView — const @beta+```+(app: App) => CameraViewAPI+```+## probeRegistrations — function @experimental```(register: () => Promise<void>): Promise<ProbedRegistrations>diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex e17dcde49..940211fb3 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 · 89 beta · 1682 experimental · 3 deprecated+Symbols: 113 public · 94 beta · 1682 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1694,6 +1694,22 @@ minX: numberminY: number```+## CameraCommit — const @beta+```+ResourceDef<CameraCommitData>+```++## CameraCommitData — interface @beta+```+revision: number+valid: boolean+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraData — interface @beta```aspectRatio: number@@ -1759,6 +1775,15 @@ renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```+## CameraLens — interface @beta+```+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1817,7 +1842,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null-static new (app_: App): CameraViewAPI+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPIstatic prototype: CameraViewAPI```@@ -2553,7 +2578,7 @@ ScreenScalingData## DEFAULT_UI_CAMERA_INFO — const @experimental```-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }```## DODGE_KEY — const @experimental@@ -6736,6 +6761,11 @@ generation: number | undefinedquery: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"```+## PresentedCameraView — const @beta+```+ResourceDef<CameraViewAPI>+```+## ProbedRegistrations — interface @experimental```fingerprint: string@@ -9705,6 +9735,7 @@ SizeY = 11## UICameraData — interface @beta```+revision: numberscreenH: numberscreenW: numbervalid: boolean@@ -12861,6 +12892,11 @@ PrefabsPlugin(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>```+## presentedCameraView — const @beta+```+(app: App) => CameraViewAPI+```+## probeRegistrations — function @experimental```(register: () => Promise<void>): Promise<ProbedRegistrations>diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 583f74857..c17a9cc38 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 · 86 beta · 1662 experimental · 3 deprecated+Symbols: 113 public · 91 beta · 1662 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1689,6 +1689,22 @@ minX: numberminY: number```+## CameraCommit — const @beta+```+ResourceDef<CameraCommitData>+```++## CameraCommitData — interface @beta+```+revision: number+valid: boolean+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraData — interface @beta```aspectRatio: number@@ -1754,6 +1770,15 @@ renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```+## CameraLens — interface @beta+```+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1812,7 +1837,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null-static new (app_: App): CameraViewAPI+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPIstatic prototype: CameraViewAPI```@@ -2540,7 +2565,7 @@ ScreenScalingData## DEFAULT_UI_CAMERA_INFO — const @experimental```-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }```## DODGE_KEY — const @experimental@@ -6548,6 +6573,11 @@ generation: number | undefinedquery: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"```+## PresentedCameraView — const @beta+```+ResourceDef<CameraViewAPI>+```+## ProbedRegistrations — interface @experimental```fingerprint: string@@ -9507,6 +9537,7 @@ SizeY = 11## UICameraData — interface @beta```+revision: numberscreenH: numberscreenW: numbervalid: boolean@@ -12623,6 +12654,11 @@ PrefabsPlugin(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>```+## presentedCameraView — const @beta+```+(app: App) => CameraViewAPI+```+## probeRegistrations — function @experimental```(register: () => Promise<void>): Promise<ProbedRegistrations>diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 613a64437..8dfb6f0c1 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 · 84 beta · 1684 experimental · 3 deprecated+Symbols: 113 public · 89 beta · 1684 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1689,6 +1689,22 @@ minX: numberminY: number```+## CameraCommit — const @beta+```+ResourceDef<CameraCommitData>+```++## CameraCommitData — interface @beta+```+revision: number+valid: boolean+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraData — interface @beta```aspectRatio: number@@ -1754,6 +1770,15 @@ renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```+## CameraLens — interface @beta+```+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1812,7 +1837,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null-static new (app_: App): CameraViewAPI+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPIstatic prototype: CameraViewAPI```@@ -2540,7 +2565,7 @@ ScreenScalingData## DEFAULT_UI_CAMERA_INFO — const @experimental```-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }```## DODGE_KEY — const @experimental@@ -6794,6 +6819,11 @@ generation: number | undefinedquery: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"```+## PresentedCameraView — const @beta+```+ResourceDef<CameraViewAPI>+```+## ProbedRegistrations — interface @experimental```fingerprint: string@@ -9753,6 +9783,7 @@ SizeY = 11## UICameraData — interface @beta```+revision: numberscreenH: numberscreenW: numbervalid: boolean@@ -12880,6 +12911,11 @@ PrefabsPlugin(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>```+## presentedCameraView — const @beta+```+(app: App) => CameraViewAPI+```+## probeRegistrations — function @experimental```(register: () => Promise<void>): Promise<ProbedRegistrations>diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 1778caec2..f96013e8f 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 · 84 beta · 1674 experimental · 3 deprecated+Symbols: 113 public · 89 beta · 1674 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1689,6 +1689,22 @@ minX: numberminY: number```+## CameraCommit — const @beta+```+ResourceDef<CameraCommitData>+```++## CameraCommitData — interface @beta+```+revision: number+valid: boolean+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraData — interface @beta```aspectRatio: number@@ -1754,6 +1770,15 @@ renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```+## CameraLens — interface @beta+```+viewProjection: Float32Array<ArrayBufferLike>+vpH: number+vpW: number+vpX: number+vpY: number+```+## CameraPOV — interface @experimental```clearFlags: number@@ -1812,7 +1837,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | nullscreenRay: (screenX: number, screenY: number) => WorldRay | nullscreenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | nullworldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null-static new (app_: App): CameraViewAPI+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPIstatic prototype: CameraViewAPI```@@ -2540,7 +2565,7 @@ ScreenScalingData## DEFAULT_UI_CAMERA_INFO — const @experimental```-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }```## DODGE_KEY — const @experimental@@ -6555,6 +6580,11 @@ generation: number | undefinedquery: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"```+## PresentedCameraView — const @beta+```+ResourceDef<CameraViewAPI>+```+## ProbedRegistrations — interface @experimental```fingerprint: string@@ -9514,6 +9544,7 @@ SizeY = 11## UICameraData — interface @beta```+revision: numberscreenH: numberscreenW: numbervalid: boolean@@ -12646,6 +12677,11 @@ PrefabsPlugin(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>```+## presentedCameraView — const @beta+```+(app: App) => CameraViewAPI+```+## probeRegistrations — function @experimental```(register: () => Promise<void>): Promise<ProbedRegistrations>diff --git a/sdk/src/app/corePlugin.ts b/sdk/src/app/corePlugin.tsindex 0997aaba0..aa8ff2f08 100644--- a/sdk/src/app/corePlugin.ts+++ b/sdk/src/app/corePlugin.ts@@ -11,7 +11,7 @@ import { initGeometryAPI, shutdownGeometryAPI } from '../render/geometry';import { initPostProcessAPI, shutdownPostProcessAPI } from '../postprocess';import { initRendererAPI, shutdownRendererAPI } from '../render/renderer';import { initGLDebugAPI, shutdownGLDebugAPI } from '../render/glDebug';-import { CameraView, CameraViewAPI } from '../camera/Camera';+import { CameraView, CameraViewAPI, PresentedCameraView, presentedCameraView } from '../camera/Camera';let offMemoryWarning: (() => void) | null = null;@@ -37,6 +37,10 @@ export const corePlugin: Plugin = {initRendererAPI(module);initGLDebugAPI(module);app.insertResource(CameraView, new CameraViewAPI(app));+ // Published beside it, not instead of it: a system inside the frame+ // wants the camera being resolved, and an overlay on the picture wants+ // the one that drew it. Two questions, so two resources.+ app.insertResource(PresentedCameraView, presentedCameraView(app));},cleanup() {@@ -60,4 +64,5 @@ export const DEFAULT_UI_CAMERA_INFO = {worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,worldMouseX: 0, worldMouseY: 0,valid: false,+ revision: 0,} as const;diff --git a/sdk/src/camera/Camera.ts b/sdk/src/camera/Camera.tsindex b51d81651..0d61904ec 100644--- a/sdk/src/camera/Camera.ts+++ b/sdk/src/camera/Camera.ts@@ -3,6 +3,7 @@import type { App } from '../app/app';import { defineResource } from '../ecs/resource';import { UICameraInfo, type UICameraData } from '../ui/core/ui-camera-info';+import { CameraCommit } from './CameraCommit';import type { Vec3 } from '../types';import { screenToWorld, projectWorldPoint, projectDirectionAt, nearPlaneSide, isProjectable, createInvVPCache, screenRay, type WorldRay } from '../ui/util/math';@@ -18,12 +19,60 @@ import { screenToWorld, projectWorldPoint, projectDirectionAt, nearPlaneSide, is/** How far inside the near plane a cut lands, as a fraction of the segment. */const CLIP_NUDGE = 1e-4;+/**+ * The camera as a LENS — what a projection needs, and nothing about the surface.+ *+ * Narrower than {@link UICameraData} on purpose: it is the part two different+ * cameras can both supply, one being resolved and one already drawn with.+ * @beta+ */+export interface CameraLens {+ viewProjection: Float32Array;+ vpX: number;+ vpY: number;+ vpW: number;+ vpH: number;+}++/** The camera currently being resolved — moves twice a frame. */+const liveLens = (app: App): CameraLens | null => {+ const cam: UICameraData = app.getResource(UICameraInfo);+ return cam.valid ? cam : null;+};++/** The camera the last frame was drawn with. */+const committedLens = (app: App): CameraLens | null => {+ const commit = app.getResource(CameraCommit);+ return commit.valid ? commit : null;+};+export class CameraViewAPI {private readonly invVPCache = createInvVPCache();- constructor(private readonly app_: App) {}+ /**+ * @param lens_ Which camera this view answers for. The default is the one+ * being resolved — what a system inside the frame wants.+ * Anything aligning to the PICTURE wants+ * {@link PresentedCameraView}: the live one moves mid-frame and+ * can hold a state no frame was drawn from.+ */+ constructor(+ private readonly app_: App,+ private readonly lens_: (app: App) => CameraLens | null = liveLens,+ ) {}++ private cam(): CameraLens | null {+ return this.lens_(this.app_);+ }- private cam(): UICameraData | null {+ /**+ * The live UI surface, for the two answers that are not projections.+ *+ * Where the pointer is and what box UI lays out within are facts about the+ * surface as it stands, not about a picture that was drawn — so they read+ * the live resource even on a view over the committed camera.+ */+ private surface(): UICameraData | null {const cam = this.app_.getResource(UICameraInfo);return cam.valid ? cam : null;}@@ -122,13 +171,13 @@ export class CameraViewAPI {}getWorldMousePosition(): { x: number; y: number } | null {- const cam = this.cam();+ const cam = this.surface();if (!cam) return null;return { x: cam.worldMouseX, y: cam.worldMouseY };}getWorldBounds(): { left: number; right: number; bottom: number; top: number } | null {- const cam = this.cam();+ const cam = this.surface();if (!cam) return null;return { left: cam.worldLeft, right: cam.worldRight, bottom: cam.worldBottom, top: cam.worldTop };}@@ -140,3 +189,16 @@ export class CameraViewAPI {* `CameraView` rather than `Camera` because `Camera` is the ECS component.)*/export const CameraView = defineResource<CameraViewAPI>(null!, 'CameraView');++/**+ * The same queries, against the camera the last frame was actually drawn with.+ *+ * One implementation, two sources: a second projection written over the commit+ * would be a second near-plane cut to keep in step, and a wireframe cut by one+ * and drawn by the other comes apart exactly where a segment leaves the view.+ * @beta+ */+export const PresentedCameraView = defineResource<CameraViewAPI>(null!, 'PresentedCameraView');++/** A view over the camera the last frame was drawn with. @beta */+export const presentedCameraView = (app: App): CameraViewAPI => new CameraViewAPI(app, committedLens);diff --git a/sdk/src/camera/CameraCommit.ts b/sdk/src/camera/CameraCommit.tsnew file mode 100644index 000000000..68e99b7b3--- /dev/null+++ b/sdk/src/camera/CameraCommit.ts@@ -0,0 +1,43 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file CameraCommit.ts+ * @brief The camera the picture on screen was drawn from.+ * @details Anything that draws OVER the canvas — an editor's gizmo overlay, a+ * DOM label pinned to a world point — has to project through the same+ * camera the canvas did, or it lands somewhere the picture never was.+ *+ * {@link UICameraInfo} cannot answer that. Its matrix is rewritten in+ * place twice a frame (an early peek, then the authoritative resolve),+ * so a reader on its own clock samples at an arbitrary phase and can+ * get a camera no frame was ever drawn with — not stale, a third state.+ *+ * This is a COPY, published once, after the draw. A reader holding it+ * holds a moment rather than a view onto memory somebody else is still+ * writing, and `revision` says which moment, so an overlay can be held+ * to having used the same one.+ */+import { defineResource } from '../ecs/resource';++/** @beta */+export interface CameraCommitData {+ /** The {@link UICameraData.revision} this frame was drawn with; 0 = none. */+ revision: number;+ /** The view-projection that drew it — a copy, not the live resource's array. */+ viewProjection: Float32Array;+ /** Where the picture landed, in window pixels. */+ vpX: number;+ vpY: number;+ vpW: number;+ vpH: number;+ /** False until a frame has been drawn with a camera at all. */+ valid: boolean;+}++/** The last drawn camera, as a resource. @beta */+export const CameraCommit = defineResource<CameraCommitData>({+ revision: 0,+ viewProjection: new Float32Array(16),+ vpX: 0, vpY: 0, vpW: 0, vpH: 0,+ valid: false,+}, 'CameraCommit');diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex eb35bc999..9d2515227 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -16,6 +16,7 @@ import type { ESEngineModule, CppRegistry } from '../wasm';import type { World } from '../ecs/world';import type { Entity } from '../types';import { UICameraInfo, type UICameraData } from '../ui/core/ui-camera-info';+import { CameraCommit } from './CameraCommit';import { ScreenLayout, screenLayoutRect, screenProjection } from '../ui/core/screen-layout';import { ScreenOverlay } from '../ui/core/screen-overlay';import { ProjectionType, SceneOwner, ClearFlags } from '../ecs/component';@@ -589,6 +590,28 @@ function publishScreenLayout();}+/**+ * Publish the camera this frame was drawn from, as a copy.+ *+ * After the submit, never from the early peek: the value names a picture, and a+ * peek draws nothing. Copied because UICameraInfo's array is rewritten in place,+ * so a view onto it would change under a reader mid-gizmo.+ */+function commitCamera(app: App, cam: CameraInfo | null, uiCam: UICameraData): void {+ const commit = app.getResource(CameraCommit);+ if (!cam) {+ commit.valid = false;+ return;+ }+ commit.viewProjection.set(cam.viewProjection);+ commit.vpX = uiCam.vpX;+ commit.vpY = uiCam.vpY;+ commit.vpW = uiCam.vpW;+ commit.vpH = uiCam.vpH;+ commit.revision = uiCam.revision;+ commit.valid = true;+}+function syncUICameraInfo(app: App,module: ESEngineModule | null,@@ -606,6 +629,9 @@ function syncUICameraInfo(if (cameras.length > 0) {const cam = cameras[0];uiCam.viewProjection.set(cam.viewProjection);+ // In the same statement group as the write it names: a revision published+ // apart from the matrix is a reader's chance to see one without the other.+ uiCam.revision++;// Against the WINDOW, not the camera's render target: this rect is what a// pointer's coordinates are normalised by, and a pointer is on the window.const box = viewportPixels(cam.viewportRect, width, height);@@ -639,6 +665,7 @@ function syncUICameraInfo(uiCam.valid = true;} else {uiCam.valid = false;+ uiCam.revision++;}publishScreenOverlay(app, width, height, uiCam, cameras);}@@ -860,6 +887,11 @@ export function cameraPlugin(// swapchain image goes back.pipeline.endFrame();}, { remainder: 'wait' });++ // The frame is drawn; say which camera drew it. After the+ // submit, so nothing can publish a commit for a picture that+ // then failed to render.+ commitCamera(app, cameras.length > 0 ? cameras[0] : null, app.getResource(UICameraInfo));},};diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 9dad62425..d23c2661b 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -41,7 +41,8 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTextur// Camera// =============================================================================-export { CameraView, CameraViewAPI } from './camera/Camera';+export { CameraView, CameraViewAPI, PresentedCameraView, presentedCameraView, type CameraLens } from './camera/Camera';+export { CameraCommit, type CameraCommitData } from './camera/CameraCommit';export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, editorViewWorldPerPixel, setEditorViewHalfHeight, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewBasis, editorViewEye, editorViewStandoff, editorViewClipFar, editorViewClipNear, editorViewWorkPlane, editorViewGridPlane, screenWorkAxes, worldAxisVector, moveEditorViewFocus, editorViewBoxExtent } from './camera/EditorView';export type { EditorViewData, ScreenAxis, EditorViewBasis, EditorWorkPlane, WorldAxis } from './camera/EditorView';export { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './camera/ScreenScaling';diff --git a/sdk/src/ui/core/ui-camera-info.ts b/sdk/src/ui/core/ui-camera-info.tsindex 47daa45f2..a4425550a 100644--- a/sdk/src/ui/core/ui-camera-info.ts+++ b/sdk/src/ui/core/ui-camera-info.ts@@ -23,6 +23,14 @@ export interface UICameraData {worldMouseX: number;worldMouseY: number;valid: boolean;+ /**+ * Which write of {@link UICameraData.viewProjection} this is.+ *+ * The matrix is rewritten IN PLACE twice a frame — an early peek, then the+ * resolve the renderer draws from — so a reader holds live memory and cannot+ * tell the two apart. This number can; `CameraCommit` is the drawn one.+ */+ revision: number;}/** The UI surface, as a resource — what a system reads to place something in@@ -35,4 +43,5 @@ export const UICameraInfo = defineResource<UICameraData>({worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,worldMouseX: 0, worldMouseY: 0,valid: false,+ revision: 0,}, 'UICameraInfo');diff --git a/sdk/tests/camera-commit.test.ts b/sdk/tests/camera-commit.test.tsnew file mode 100644index 000000000..dc49bf7ea--- /dev/null+++ b/sdk/tests/camera-commit.test.ts@@ -0,0 +1,158 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The camera an overlay is allowed to project through.+ *+ * A gizmo drawn over the canvas has to use the camera the canvas was drawn with.+ * UICameraInfo cannot answer that: its matrix is rewritten in place twice a+ * frame — an early peek that must not tick the director's blend, then the+ * authoritative resolve the render system draws from — so a reader on its own+ * clock samples at an arbitrary phase. CameraCommit is the answer, published+ * once, after the submit, as a copy.+ */+import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import { bootMockApp } from './helpers/mockApp';+import { setPlatform } from '../src/platform/base';+import type { PlatformAdapter } from '../src/platform/types';+import { cameraPlugin } from '../src/camera/CameraPlugin';+import { CameraCommit } from '../src/camera/CameraCommit';+import { UICameraInfo } from '../src/ui/core/ui-camera-info';+import { RenderPipeline } from '../src/render/renderPipeline';+import { setRendererBackend, type RendererBackend } from '../src/render/renderer';+import { defineSystem, Schedule } from '../src/ecs/system';+import { Camera, Transform, ProjectionType } from '../src/ecs/component';+import { Query, Mut } from '../src/ecs/query';+import type { Entity } from '../src/types';+import type { CppRegistry } from '../src/wasm';++/** The mock's registry. Its runtime shape is wider than the module type, which+ * declares a `Registry` constructor rather than this accessor. */+const registryOf = (module: unknown): Record<string, unknown> & CppRegistry =>+ (module as { getRegistry(): unknown }).getRegistry() as Record<string, unknown> & CppRegistry;++describe('the camera a frame was drawn with', () => {+ let drawnWith: Float32Array | null = null;++ function fakeBackend(): RendererBackend {+ return {+ init: () => {}, resize: () => {},+ beginFrame: () => {}, updateTransforms: () => {},+ begin: (viewProjection) => { drawnWith = new Float32Array(viewProjection); },+ submitAll: () => {}, flush: () => {}, end: () => {}, endFrame: () => {},+ hasScreenOverlay: () => false,+ beginScreenOverlay: () => {}, submitScreenOverlay: () => {}, endScreenOverlay: () => {},+ setStage: () => {}, setViewport: () => {},+ setYSortLayers: () => {}, setDepthLayers: () => {}, setCullingMask: () => {},+ setViewId: () => {},+ lodInspect: () => null, setLodPreview: () => {}, lightStatus: () => null, shadowStatus: () => null,+ getStats: () => ({ drawCalls: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 }),+ };+ }++ /** An app with one orthographic camera, drawing through the fake backend. */+ function bootWithCamera() {+ const { app, module } = bootMockApp();+ const registry = registryOf(module);+ const cam = app.world.spawn('camera') as Entity;+ app.world.insert(cam, Transform, { position: { x: 0, y: 0, z: 0 } });+ app.world.insert(cam, Camera, {+ isActive: true, projectionType: ProjectionType.Orthographic, orthoSize: 300,+ });+ registry.getCameraEntities = () => [cam];+ registry.getCanvasEntities = () => [];+ app.setPipeline(new RenderPipeline());+ setRendererBackend(fakeBackend());+ app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));+ return { app, cam };+ }++ beforeEach(() => {+ drawnWith = null;+ setPlatform({ now: () => 0, devicePixelRatio: () => 1 } as unknown as PlatformAdapter);+ });+ afterEach(() => { setRendererBackend(null); });++ it('is published, and names the write it came from', async () => {+ const { app } = bootWithCamera();+ await app.tick(1 / 60);++ const commit = app.getResource(CameraCommit);+ expect(commit.valid).toBe(true);+ expect(commit.revision).toBeGreaterThan(0);+ // The picture and the commit agree — one that named a different matrix+ // would send every overlay somewhere the frame never drew.+ expect(drawnWith).not.toBeNull();+ expect(Array.from(commit.viewProjection)).toEqual(Array.from(drawnWith!));+ });++ it('is a copy, so a later write cannot move it under a reader', async () => {+ const { app } = bootWithCamera();+ await app.tick(1 / 60);+ const commit = app.getResource(CameraCommit);+ const held = new Float32Array(commit.viewProjection);++ // What the engine does to UICameraInfo between an overlay's two reads.+ const uiCam = app.getResource(UICameraInfo);+ uiCam.viewProjection.fill(99);++ expect(Array.from(commit.viewProjection)).toEqual(Array.from(held));+ expect(commit.viewProjection).not.toBe(uiCam.viewProjection);+ });++ it('advances once per drawn frame, never backwards', async () => {+ const { app } = bootWithCamera();+ const seen: number[] = [];+ for (let i = 0; i < 3; i++) {+ await app.tick(1 / 60);+ seen.push(app.getResource(CameraCommit).revision);+ }+ expect(seen).toEqual([...seen].sort((a, b) => a - b));+ expect(new Set(seen).size).toBe(seen.length);+ });++ it('is BEHIND the live resource mid-frame, which is the reason it exists', async () => {+ // The early peek moves UICameraInfo.revision before anything is drawn+ // with it, so a reader landing here holds a camera no frame was ever+ // drawn from: not a stale one, a third state.+ const { app } = bootWithCamera();+ await app.tick(1 / 60);++ let midFrame = -1;+ app.addSystemToSchedule(Schedule.PreUpdate, defineSystem(+ [],+ () => { midFrame = app.getResource(UICameraInfo).revision; },+ { name: 'readAfterEarlySync' },+ ));+ const committedBefore = app.getResource(CameraCommit).revision;+ await app.tick(1 / 60);++ expect(midFrame).toBeGreaterThan(committedBefore);+ expect(midFrame).not.toBe(app.getResource(CameraCommit).revision);+ });++ it('follows the camera that moved, not the one the peek saw', async () => {+ const { app } = bootWithCamera();+ const SPEED = 300;+ app.addSystemToSchedule(Schedule.Update, defineSystem(+ [Query(Mut(Transform), Camera)],+ (query) => { query.forEach((_e, t) => { t.position.x += SPEED * (1 / 60); }); },+ { name: 'cameraMove' },+ ));+ await app.tick(1 / 60);++ const commit = app.getResource(CameraCommit);+ expect(Array.from(commit.viewProjection)).toEqual(Array.from(drawnWith!));+ });++ it('says nothing when no camera drew', async () => {+ const { app, module } = bootMockApp();+ const registry = registryOf(module);+ registry.getCameraEntities = () => [];+ registry.getCanvasEntities = () => [];+ app.setPipeline(new RenderPipeline());+ setRendererBackend(fakeBackend());+ app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));+ await app.tick(1 / 60);+ expect(app.getResource(CameraCommit).valid).toBe(false);+ });+});diff --git a/sdk/tests/ui-anchor-preset.test.ts b/sdk/tests/ui-anchor-preset.test.tsindex b2fda9211..867f5907e 100644--- a/sdk/tests/ui-anchor-preset.test.ts+++ b/sdk/tests/ui-anchor-preset.test.ts@@ -114,7 +114,7 @@ describe.skipIf(!HAS_WASM)('anchor presets lay out via Yoga (WASM integration)',viewProjection: new Float32Array(16),vpX: 0, vpY: 0, vpW: 0, vpH: 0, screenW: 0, screenH: 0,worldLeft: -400, worldBottom: -300, worldRight: 400, worldTop: 300,- worldMouseX: 0, worldMouseY: 0, valid: true,+ worldMouseX: 0, worldMouseY: 0, valid: true, revision: 1,});setScreenBox(app, -400, -300, 400, 300);app.addPlugin(uiLayoutPlugin);diff --git a/sdk/tests/ui-components.test.ts b/sdk/tests/ui-components.test.tsindex c3416ca16..65fd1be18 100644--- a/sdk/tests/ui-components.test.ts+++ b/sdk/tests/ui-components.test.ts@@ -77,6 +77,7 @@ describe.skipIf(!HAS_WASM)('UI Components (WASM integration)', () => {worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,worldMouseX: 0, worldMouseY: 0,valid: false,+ revision: 1,});app.addPlugin(uiLayoutPlugin);diff --git a/sdk/tests/ui-layout-incremental.test.ts b/sdk/tests/ui-layout-incremental.test.tsindex 6df9957cf..e20031be4 100644--- a/sdk/tests/ui-layout-incremental.test.ts+++ b/sdk/tests/ui-layout-incremental.test.ts@@ -64,7 +64,7 @@ describe.skipIf(!HAS_WASM)('incremental layout equals a fresh solve', () => {vpX: 0, vpY: 0, vpW: 0, vpH: 0, screenW: 0, screenH: 0,worldLeft: -camW / 2, worldBottom: -camH / 2,worldRight: camW / 2, worldTop: camH / 2,- worldMouseX: 0, worldMouseY: 0, valid: true,+ worldMouseX: 0, worldMouseY: 0, valid: true, revision: 1,});setScreenBox(app, -camW / 2, -camH / 2, camW / 2, camH / 2);app.addPlugin(uiLayoutPlugin);diff --git a/sdk/tests/ui-layout-integration.test.ts b/sdk/tests/ui-layout-integration.test.tsindex a5da23cba..7e65ae42c 100644--- a/sdk/tests/ui-layout-integration.test.ts+++ b/sdk/tests/ui-layout-integration.test.ts@@ -108,6 +108,7 @@ describe.skipIf(!HAS_WASM)('UI Layout via App.tick() (WASM integration)', () =>worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,worldMouseX: 0, worldMouseY: 0,valid: false,+ revision: 1,});app.insertResource(ScreenLayout, { ...ScreenLayout._default });diff --git a/sdk/tests/ui-list-view-widget.test.ts b/sdk/tests/ui-list-view-widget.test.tsindex 81d7b23d6..5ab1e47a4 100644--- a/sdk/tests/ui-list-view-widget.test.ts+++ b/sdk/tests/ui-list-view-widget.test.ts@@ -30,7 +30,7 @@ describe.skipIf(!HAS_WASM)('createListView (WASM integration)', () => {viewProjection: new Float32Array(16),vpX: 0, vpY: 0, vpW: 0, vpH: 0, screenW: 0, screenH: 0,worldLeft: 0, worldBottom: 0, worldRight: 800, worldTop: 600,- worldMouseX: 0, worldMouseY: 0, valid: true,+ worldMouseX: 0, worldMouseY: 0, valid: true, revision: 1,});// No inputPlugin: it binds platform input (unavailable in tests). The Input// resource has a default InputState, so the ScrollWheelSystem still resolves.