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(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.json
index 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.md
index 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: number
vpY: 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): void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: number
vpY: 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): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: number
vpY: 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): void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: number
vpY: 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): void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: number
vpY: 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): void
diff --git a/sdk/src/camera/CameraCommit.ts b/sdk/src/camera/CameraCommit.ts
index 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.ts
index 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): vo
commit.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): vo
commit.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.ts
index 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.ts
index 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);