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 commit says when the camera CHANGED, not when one happened
yhhdad4f9ee3a8f
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex adace87e3..7ab2cddac 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": 96,+ "beta": 99,"experimental": 1824,"deprecated": 3},- "total": 2033,+ "total": 2036,"subsystems": [{"id": "ecs",@@ -1849,6 +1849,18 @@"minigame"]},+ {+ "name": "CameraCommitListener",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "CameraData","kind": "interface",@@ -2679,6 +2691,18 @@"minigame"]},+ {+ "name": "cameraCommitChanged",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "cameraFrustumCorners","kind": "function",@@ -2811,6 +2835,18 @@"index.node"]},+ {+ "name": "onCameraCommitChanged",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "presentedCameraView","kind": "const",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 768b65662..88f1e56cc 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 · 89 beta · 1663 experimental · 3 deprecated+Symbols: 113 public · 92 beta · 1663 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1710,6 +1710,11 @@ vpX: numbervpY: number```+## CameraCommitListener — type @beta+```+() => void+```+## CameraData — interface @beta```aspectRatio: number@@ -10799,6 +10804,11 @@ BtPlugin(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number```+## cameraCommitChanged — function @beta+```+(): void+```+## cameraFrustumCorners — function @beta```(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array@@ -12354,6 +12364,11 @@ NavPlugin(mask: number): number```+## onCameraCommitChanged — function @beta+```+(fn: CameraCommitListener): () => void+```+## openDialog — function @experimental```(world: World, events: UIEventQueue, root: Entity): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 9833636f9..1ececcb03 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 · 94 beta · 1682 experimental · 3 deprecated+Symbols: 113 public · 97 beta · 1682 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1710,6 +1710,11 @@ vpX: numbervpY: number```+## CameraCommitListener — type @beta+```+() => void+```+## CameraData — interface @beta```aspectRatio: number@@ -11007,6 +11012,11 @@ BtPlugin(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number```+## cameraCommitChanged — function @beta+```+(): void+```+## cameraFrustumCorners — function @beta```(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array@@ -12597,6 +12607,11 @@ NavPlugin(mask: number): number```+## onCameraCommitChanged — function @beta+```+(fn: CameraCommitListener): () => void+```+## openDialog — function @experimental```(world: World, events: UIEventQueue, root: Entity): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex fb3e755db..a87c96175 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 · 91 beta · 1662 experimental · 3 deprecated+Symbols: 113 public · 94 beta · 1662 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1705,6 +1705,11 @@ vpX: numbervpY: number```+## CameraCommitListener — type @beta+```+() => void+```+## CameraData — interface @beta```aspectRatio: number@@ -10794,6 +10799,11 @@ BtPlugin(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number```+## cameraCommitChanged — function @beta+```+(): void+```+## cameraFrustumCorners — function @beta```(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array@@ -12359,6 +12369,11 @@ NodePlatformAdapter(mask: number): number```+## onCameraCommitChanged — function @beta+```+(fn: CameraCommitListener): () => void+```+## openDialog — function @experimental```(world: World, events: UIEventQueue, root: Entity): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex de4fadcbb..9c7bc1231 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 · 89 beta · 1684 experimental · 3 deprecated+Symbols: 113 public · 92 beta · 1684 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1705,6 +1705,11 @@ vpX: numbervpY: number```+## CameraCommitListener — type @beta+```+() => void+```+## CameraData — interface @beta```aspectRatio: number@@ -11046,6 +11051,11 @@ BtPlugin(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number```+## cameraCommitChanged — function @beta+```+(): void+```+## cameraFrustumCorners — function @beta```(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array@@ -12616,6 +12626,11 @@ NavPlugin(mask: number): number```+## onCameraCommitChanged — function @beta+```+(fn: CameraCommitListener): () => void+```+## openDialog — function @experimental```(world: World, events: UIEventQueue, root: Entity): voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 08caa7c26..b46f612e5 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 · 89 beta · 1674 experimental · 3 deprecated+Symbols: 113 public · 92 beta · 1674 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1705,6 +1705,11 @@ vpX: numbervpY: number```+## CameraCommitListener — type @beta+```+() => void+```+## CameraData — interface @beta```aspectRatio: number@@ -10822,6 +10827,11 @@ BtPlugin(source: Vec3, listener: Vec3, right: Vec3, maxDistance: number): number```+## cameraCommitChanged — function @beta+```+(): void+```+## cameraFrustumCorners — function @beta```(camera: CameraFields, transform: CameraTransformFields, width: number, height: number, canvas: CanvasScale | null, result?: Float32Array): Float32Array@@ -12382,6 +12392,11 @@ NavPlugin(mask: number): number```+## onCameraCommitChanged — function @beta+```+(fn: CameraCommitListener): () => void+```+## openDialog — function @experimental```(world: World, events: UIEventQueue, root: Entity): voiddiff --git a/sdk/src/camera/CameraCommit.ts b/sdk/src/camera/CameraCommit.tsindex 68e99b7b3..72a99aeab 100644--- a/sdk/src/camera/CameraCommit.ts+++ b/sdk/src/camera/CameraCommit.ts@@ -34,6 +34,29 @@ export interface CameraCommitData {valid: boolean;}+/**+ * Told when the committed camera CHANGES — not when one is published.+ *+ * A commit happens on every drawn frame, so "a commit happened" says nothing+ * about what is on screen. Told the other question instead: looking for it on a+ * clock of one's own is a poll that never sleeps, or a change that lands late.+ * @beta+ */+export type CameraCommitListener = () => void;++const listeners = new Set<CameraCommitListener>();++/** Subscribe to committed-camera changes. Returns an unsubscribe. @beta */+export function onCameraCommitChanged(fn: CameraCommitListener): () => void {+ listeners.add(fn);+ return () => { listeners.delete(fn); };+}++/** Announce a change. Called by the camera plugin, after the submit. @beta */+export function cameraCommitChanged(): void {+ for (const fn of [...listeners]) fn();+}+/** The last drawn camera, as a resource. @beta */export const CameraCommit = defineResource<CameraCommitData>({revision: 0,diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 9d2515227..f7b222c79 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -16,7 +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 { CameraCommit, cameraCommitChanged } 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';@@ -603,6 +603,10 @@ function commitCamera(app: App, cam: CameraInfo | null, uiCam: UICameraData): vocommit.valid = false;return;}+ const moved = !commit.valid+ || commit.vpX !== uiCam.vpX || commit.vpY !== uiCam.vpY+ || commit.vpW !== uiCam.vpW || commit.vpH !== uiCam.vpH+ || !sameMatrix(commit.viewProjection, cam.viewProjection);commit.viewProjection.set(cam.viewProjection);commit.vpX = uiCam.vpX;commit.vpY = uiCam.vpY;@@ -610,6 +614,14 @@ function commitCamera(app: App, cam: CameraInfo | null, uiCam: UICameraData): vocommit.vpH = uiCam.vpH;commit.revision = uiCam.revision;commit.valid = true;+ if (moved) cameraCommitChanged();+}++/** Exact: the question is whether the projection moved, not whether two cameras+ * are close enough to look alike. */+function sameMatrix(a: Float32Array, b: Float32Array): boolean {+ for (let i = 0; i < 16; i++) if (a[i] !== b[i]) return false;+ return true;}function syncUICameraInfo(diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex d23c2661b..9c6927145 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -42,7 +42,8 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTextur// =============================================================================export { CameraView, CameraViewAPI, PresentedCameraView, presentedCameraView, type CameraLens } from './camera/Camera';-export { CameraCommit, type CameraCommitData } from './camera/CameraCommit';+export { CameraCommit, onCameraCommitChanged, cameraCommitChanged,+ type CameraCommitData, type CameraCommitListener } 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/tests/camera-commit.test.ts b/sdk/tests/camera-commit.test.tsindex dc49bf7ea..82e60207e 100644--- a/sdk/tests/camera-commit.test.ts+++ b/sdk/tests/camera-commit.test.ts@@ -15,7 +15,7 @@ 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 { CameraCommit, onCameraCommitChanged } 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';@@ -50,7 +50,7 @@ describe('the camera a frame was drawn with', () => {}/** An app with one orthographic camera, drawing through the fake backend. */- function bootWithCamera() {+ function bootWithCamera(viewport = { width: 800, height: 600 }) {const { app, module } = bootMockApp();const registry = registryOf(module);const cam = app.world.spawn('camera') as Entity;@@ -62,7 +62,7 @@ describe('the camera a frame was drawn with', () => {registry.getCanvasEntities = () => [];app.setPipeline(new RenderPipeline());setRendererBackend(fakeBackend());- app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));+ app.addPlugin(cameraPlugin(() => ({ ...viewport })));return { app, cam };}@@ -144,6 +144,39 @@ describe('the camera a frame was drawn with', () => {expect(Array.from(commit.viewProjection)).toEqual(Array.from(drawnWith!));});+ it('announces a change, not a commit', async () => {+ // A commit happens every drawn frame, so a listener told about commits is+ // told 60 times a second that nothing happened. Anything aligning to the+ // picture would then either poll or repaint forever.+ const { app } = bootWithCamera();+ let told = 0;+ const off = onCameraCommitChanged(() => { told++; });+ try {+ await app.tick(1 / 60);+ const first = told;+ expect(first).toBeGreaterThan(0);+ for (let i = 0; i < 5; i++) await app.tick(1 / 60);+ expect(told).toBe(first);+ } finally { off(); }+ });++ it('announces again the moment the projection moves', async () => {+ // Through the viewport, because this fake backend resolves no transforms+ // and the mock registry does not read a component written back by hand.+ const viewport = { width: 800, height: 600 };+ const { app } = bootWithCamera(viewport);+ await app.tick(1 / 60);+ let told = 0;+ const off = onCameraCommitChanged(() => { told++; });+ try {+ await app.tick(1 / 60);+ expect(told).toBe(0);+ viewport.width = 1200;+ await app.tick(1 / 60);+ expect(told).toBe(1);+ } finally { off(); }+ });+it('says nothing when no camera drew', async () => {const { app, module } = bootMockApp();const registry = registryOf(module);