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(engine): camera director + view-target blending (camera modernization C)

esengine16ae4de87bb4
diff --git a/sdk/src/camera/CameraDirector.ts b/sdk/src/camera/CameraDirector.ts
new file mode 100644
index 000000000..23244bcdb
--- /dev/null
+++ b/sdk/src/camera/CameraDirector.ts
@@ -0,0 +1,191 @@
+/**
+ * @file CameraDirector.ts
+ * @brief The camera director — picks the active view target among the scene's
+ * cameras and BLENDS smoothly between targets over time, the way UE's
+ * APlayerCameraManager (SetViewTargetWithBlend) and Unity Cinemachine's
+ * Brain do. It resolves ONE main point-of-view per frame (the previous
+ * target's POV lerped toward the new target's), which the camera plugin
+ * builds into the rendered view. Cameras stay declarative view defs; the
+ * director is the runtime that selects + transitions between them.
+ */
+import type { App } from '../app';
+import { defineResource } from '../resource';
+import type { CameraPOV } from './CameraPlugin';
+
+/** Easing for a view-target transition. */
+export const BlendCurve = {
+ Linear: 0,
+ EaseIn: 1,
+ EaseOut: 2,
+ EaseInOut: 3,
+} as const;
+export type BlendCurve = (typeof BlendCurve)[keyof typeof BlendCurve];
+
+export function applyCurve(curve: number, t: number): number {
+ const x = t < 0 ? 0 : t > 1 ? 1 : t;
+ switch (curve) {
+ case BlendCurve.EaseIn:
+ return x * x;
+ case BlendCurve.EaseOut:
+ return 1 - (1 - x) * (1 - x);
+ case BlendCurve.EaseInOut:
+ return x < 0.5 ? 2 * x * x : 1 - ((-2 * x + 2) * (-2 * x + 2)) / 2;
+ default:
+ return x; // Linear
+ }
+}
+
+/** Signed shortest angular delta a→b (radians), so a blend never spins the long way. */
+function shortAngle(a: number, b: number): number {
+ const TWO_PI = Math.PI * 2;
+ let d = (b - a) % TWO_PI;
+ if (d > Math.PI) d -= TWO_PI;
+ if (d < -Math.PI) d += TWO_PI;
+ return d;
+}
+
+/** Interpolate two POVs. Continuous fields lerp; discrete ones snap to the target. */
+export function lerpPOV(a: CameraPOV, b: CameraPOV, t: number): CameraPOV {
+ const l = (x: number, y: number) => x + (y - x) * t;
+ return {
+ entity: b.entity,
+ isActive: b.isActive,
+ x: l(a.x, b.x),
+ y: l(a.y, b.y),
+ z: l(a.z, b.z),
+ rotation: a.rotation + shortAngle(a.rotation, b.rotation) * t,
+ projection: t < 0.5 ? a.projection : b.projection, // discrete: flip at the midpoint
+ orthoSize: l(a.orthoSize, b.orthoSize),
+ fov: l(a.fov, b.fov),
+ near: l(a.near, b.near),
+ far: l(a.far, b.far),
+ viewport: b.viewport,
+ clearFlags: b.clearFlags,
+ priority: b.priority,
+ };
+}
+
+function clonePOV(p: CameraPOV): CameraPOV {
+ return { ...p, viewport: { ...p.viewport } };
+}
+
+export interface CameraDirectorState {
+ /** Committed view-target entity, or -1 → fall back to the active/priority camera. */
+ target: number;
+ // Pending setViewTarget request, applied on the next resolve.
+ hasPending: boolean;
+ pendingTarget: number;
+ pendingTime: number; // seconds
+ pendingCurve: number;
+ // Active blend.
+ blending: boolean;
+ from: CameraPOV | null;
+ startTime: number; // seconds (engine elapsed clock)
+ duration: number; // seconds
+ curve: number;
+ /** Last resolved main POV — also the snapshot source when a new blend starts. */
+ currentMain: CameraPOV | null;
+}
+
+export const DEFAULT_DIRECTOR: CameraDirectorState = {
+ target: -1,
+ hasPending: false,
+ pendingTarget: -1,
+ pendingTime: 0,
+ pendingCurve: BlendCurve.EaseInOut,
+ blending: false,
+ from: null,
+ startTime: 0,
+ duration: 0,
+ curve: BlendCurve.EaseInOut,
+ currentMain: null,
+};
+
+export const CameraDirector = defineResource<CameraDirectorState>(
+ { ...DEFAULT_DIRECTOR },
+ 'CameraDirector',
+);
+
+/**
+ * Switch the active view target, optionally blending over `time` seconds with an
+ * easing `curve`. Records intent; the director applies it on the next frame
+ * (snapshotting the current view as the blend start). `time<=0` (or no prior
+ * view) is an instant cut.
+ */
+export function setViewTarget(
+ app: App,
+ entity: number,
+ opts?: { time?: number; curve?: number },
+): void {
+ const dir = app.getResource(CameraDirector);
+ dir.hasPending = true;
+ dir.pendingTarget = entity;
+ dir.pendingTime = opts?.time ?? 0;
+ dir.pendingCurve = opts?.curve ?? BlendCurve.EaseInOut;
+}
+
+/** The active camera by policy: isActive wins (authoritative), else highest priority. */
+function pickActive(candidates: CameraPOV[]): CameraPOV {
+ const active = candidates.find((c) => c.isActive);
+ if (active) return active;
+ let best = candidates[0];
+ for (const c of candidates) if (c.priority > best.priority) best = c;
+ return best;
+}
+
+/**
+ * Resolve the main POV for this frame from the full-frame camera candidates.
+ * `advance` runs the state machine (consume a pending target, tick the blend);
+ * pass false to just peek the last resolved POV (so a second consumer per frame
+ * — the early UICameraInfo sync — doesn't double-advance the blend).
+ */
+export function resolveMainPOV(
+ dir: CameraDirectorState,
+ candidates: CameraPOV[],
+ now: number,
+ advance: boolean,
+): CameraPOV | null {
+ if (candidates.length === 0) {
+ if (advance) dir.currentMain = null;
+ return null;
+ }
+ if (!advance) {
+ return dir.currentMain ?? pickActive(candidates);
+ }
+
+ // Apply a pending setViewTarget — snapshot the current view as the blend start.
+ if (dir.hasPending) {
+ dir.hasPending = false;
+ if (dir.pendingTime > 0 && dir.currentMain) {
+ dir.from = clonePOV(dir.currentMain);
+ dir.blending = true;
+ dir.startTime = now;
+ dir.duration = dir.pendingTime;
+ dir.curve = dir.pendingCurve;
+ } else {
+ dir.blending = false;
+ dir.from = null;
+ }
+ dir.target = dir.pendingTarget;
+ }
+
+ const targetPOV =
+ (dir.target >= 0 ? candidates.find((c) => c.entity === dir.target) : undefined) ??
+ pickActive(candidates);
+
+ if (dir.blending && dir.from) {
+ const elapsed = now - dir.startTime;
+ if (dir.duration <= 0 || elapsed >= dir.duration) {
+ dir.blending = false;
+ dir.from = null;
+ dir.currentMain = targetPOV;
+ return targetPOV;
+ }
+ const blended = lerpPOV(dir.from, targetPOV, applyCurve(dir.curve, elapsed / dir.duration));
+ dir.currentMain = blended;
+ return blended;
+ }
+
+ dir.currentMain = targetPOV;
+ return targetPOV;
+}
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 25e2bc0f3..721b10f6d 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -12,6 +12,7 @@ import type { Entity } from '../types';
import { UICameraInfo } from '../ui/UICameraInfo';
import { ProjectionType, ScaleMode, SceneOwner, ClearFlags } from '../component';
import { EditorView, DEFAULT_EDITOR_VIEW, type EditorViewData } from './EditorView';
+import { CameraDirector, DEFAULT_DIRECTOR, resolveMainPOV } from './CameraDirector';
import { RenderPipeline } from '../renderPipeline';
import { Renderer } from '../renderer';
import { platformNow } from '../platform';
@@ -100,6 +101,7 @@ function computeEffectiveOrthoSize(
*/
export interface CameraPOV {
entity: number; // source entity, or -1 for a synthetic POV (e.g. the editor view)
+ isActive: boolean; // the authoritative "this is the main camera" flag (director input)
x: number;
y: number;
z: number;
@@ -122,6 +124,7 @@ function readCameraPOV(
const q = transform.rotation;
return {
entity,
+ isActive: camera.isActive,
x: transform.position.x,
y: transform.position.y,
z: transform.position.z,
@@ -193,15 +196,15 @@ export function buildCameraInfo(
// Camera Collection
// =============================================================================
-export function collectCameras(
+/** Authored POVs of the scene's cameras (scene-filtered), no matrices built yet. */
+function collectCameraPOVs(
module: ESEngineModule,
registry: CppRegistry,
width: number,
height: number,
world?: World,
activeScenes?: Set<string>,
- pool: CameraInfo[] = [],
-): CameraInfo[] {
+): CameraPOV[] {
if (width === 0 || height === 0) return [];
const cameraEntities = module.registry_getCameraEntities(registry);
if (cameraEntities.length === 0) return [];
@@ -213,20 +216,34 @@ export function collectCameras(
return activeScenes.has(owner.scene);
})
: cameraEntities;
- if (filtered.length === 0) return [];
-
- const canvas = findCanvasData(module, registry);
- const cameras: CameraInfo[] = [];
+ const out: CameraPOV[] = [];
for (const e of filtered) {
- const pov = readCameraPOV(e, registry.getCamera(e), registry.getTransform(e));
- cameras.push(buildCameraInfo(pov, width, height, canvas, pool, cameras.length));
+ out.push(readCameraPOV(e, registry.getCamera(e), registry.getTransform(e)));
}
+ return out;
+}
+export function collectCameras(
+ module: ESEngineModule,
+ registry: CppRegistry,
+ width: number,
+ height: number,
+ world?: World,
+ activeScenes?: Set<string>,
+ pool: CameraInfo[] = [],
+): CameraInfo[] {
+ const povs = collectCameraPOVs(module, registry, width, height, world, activeScenes);
+ if (povs.length === 0) return [];
+ const canvas = findCanvasData(module, registry);
+ const cameras = povs.map((pov, i) => buildCameraInfo(pov, width, height, canvas, pool, i));
cameras.sort((a, b) => a.priority - b.priority);
return cameras;
}
+const isFullFrame = (v: { x: number; y: number; z: number; w: number }): boolean =>
+ v.x === 0 && v.y === 0 && v.z === 1 && v.w === 1;
+
// =============================================================================
// Editor View (dedicated editor camera — overrides scene cameras when active)
// =============================================================================
@@ -248,6 +265,7 @@ export function editorCameraInfo(
// null canvas → raw orthoSize (no design-resolution scaling) for predictable zoom.
const pov: CameraPOV = {
entity: -1,
+ isActive: true,
x: view.x,
y: view.y,
z: 0,
@@ -265,10 +283,13 @@ export function editorCameraInfo(
}
/**
- * The cameras to render + sync this frame: the editor view (a single full-frame
- * camera) when it is active, otherwise the scene's game cameras. One decision
- * point shared by the UICameraInfo sync and the render system, so what is drawn
- * and what screen<->world resolves to can never diverge.
+ * The cameras to render + sync this frame, as ONE shared decision (so what's
+ * drawn and what screen<->world resolves to can't diverge):
+ * 1. the editor view, if active (a single full-frame camera); else
+ * 2. the camera director's resolved MAIN view (the active full-frame camera,
+ * or a view-target blend) at index 0, plus any sub-viewport overlay cameras.
+ * `advance` ticks the director's blend; the early UICameraInfo sync peeks (false)
+ * so it doesn't double-advance the same frame's blend.
*/
function resolveCameras(
app: App,
@@ -279,6 +300,8 @@ function resolveCameras(
world: World | undefined,
activeScenes: Set<string> | undefined,
pool: CameraInfo[],
+ now: number,
+ advance: boolean,
): CameraInfo[] {
if (app.hasResource(EditorView)) {
const view = app.getResource(EditorView);
@@ -286,7 +309,29 @@ function resolveCameras(
return [editorCameraInfo(view, width, height, pool)];
}
}
- return collectCameras(module, cppRegistry, width, height, world, activeScenes, pool);
+
+ const povs = collectCameraPOVs(module, cppRegistry, width, height, world, activeScenes);
+ if (povs.length === 0) return [];
+ const canvas = findCanvasData(module, cppRegistry);
+ const fullFrame = povs.filter((p) => isFullFrame(p.viewport));
+ const overlays = povs.filter((p) => !isFullFrame(p.viewport)).sort((a, b) => a.priority - b.priority);
+
+ const out: CameraInfo[] = [];
+ // The director resolves ONE main view from the full-frame candidates (active
+ // camera + view-target blending); index 0 → it also drives screen<->world.
+ if (fullFrame.length > 0 && app.hasResource(CameraDirector)) {
+ const main = resolveMainPOV(app.getResource(CameraDirector), fullFrame, now, advance);
+ if (main) out.push(buildCameraInfo(main, width, height, canvas, pool, out.length));
+ } else {
+ for (const p of fullFrame.slice().sort((a, b) => a.priority - b.priority)) {
+ out.push(buildCameraInfo(p, width, height, canvas, pool, out.length));
+ }
+ }
+ // Sub-viewport cameras render on top (minimaps, picture-in-picture).
+ for (const p of overlays) {
+ out.push(buildCameraInfo(p, width, height, canvas, pool, out.length));
+ }
+ return out;
}
// =============================================================================
@@ -347,6 +392,9 @@ export function cameraPlugin(
// The editor view is inactive by default — shipped games never touch
// it; the editor activates it in edit mode (see desktop EngineHost).
app.insertResource(EditorView, { ...DEFAULT_EDITOR_VIEW });
+ // The camera director: by default it just tracks the active camera;
+ // games call setViewTarget(app, entity, {time, curve}) to blend.
+ app.insertResource(CameraDirector, { ...DEFAULT_DIRECTOR });
const viewport = getViewportSize ?? (() => {
const dpr = typeof window !== 'undefined' ? (window.devicePixelRatio || 1) : 1;
@@ -362,7 +410,10 @@ export function cameraPlugin(
_params: [],
_fn: () => {
const { width, height } = viewport();
- const cameras = resolveCameras(app, module, cppRegistry, width, height, undefined, undefined, cameraInfoPool);
+ const now = (platformNow() - startTime) / 1000;
+ // Peek (advance=false): this early sync must not tick the director's
+ // blend — the render system (end of frame) is the authoritative tick.
+ const cameras = resolveCameras(app, module, cppRegistry, width, height, undefined, undefined, cameraInfoPool, now, false);
syncUICameraInfo(app, module, cppRegistry, width, height, cameras);
},
};
@@ -394,7 +445,8 @@ export function cameraPlugin(
}
pipeline.setActiveScenes(activeScenes ?? null);
- const cameras = resolveCameras(app, module, cppRegistry, width, height, app.world, activeScenes, cameraInfoPool);
+ // Authoritative tick (advance=true): ticks the director's blend.
+ const cameras = resolveCameras(app, module, cppRegistry, width, height, app.world, activeScenes, cameraInfoPool, elapsed, true);
syncUICameraInfo(app, module, cppRegistry, width, height, cameras);
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 68ca23087..e3517885f 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -40,6 +40,9 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTextur
export { CameraView, CameraViewApi } from './camera/Camera';
export { EditorView, DEFAULT_EDITOR_VIEW } from './camera/EditorView';
export type { EditorViewData } from './camera/EditorView';
+export { CameraDirector, setViewTarget, BlendCurve } from './camera/CameraDirector';
+export type { CameraDirectorState } from './camera/CameraDirector';
+export type { CameraPOV } from './camera/CameraPlugin';
// =============================================================================
// Draw API
diff --git a/sdk/tests/camera-director.test.ts b/sdk/tests/camera-director.test.ts
new file mode 100644
index 000000000..b02e93aa6
--- /dev/null
+++ b/sdk/tests/camera-director.test.ts
@@ -0,0 +1,112 @@
+/**
+ * @file Camera director — view-target selection + blending state machine. Pure
+ * logic (inject `now`), so deterministic and WASM-free.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ applyCurve,
+ lerpPOV,
+ resolveMainPOV,
+ BlendCurve,
+ DEFAULT_DIRECTOR,
+ type CameraDirectorState,
+} from '../src/camera/CameraDirector';
+import type { CameraPOV } from '../src/camera/CameraPlugin';
+import { ProjectionType, ClearFlags } from '../src/component';
+
+const mkPOV = (over: Partial<CameraPOV>): CameraPOV => ({
+ entity: 0,
+ isActive: false,
+ x: 0,
+ y: 0,
+ z: 0,
+ rotation: 0,
+ projection: ProjectionType.Orthographic,
+ orthoSize: 100,
+ fov: 0,
+ near: 0,
+ far: 1000,
+ viewport: { x: 0, y: 0, z: 1, w: 1 },
+ clearFlags: ClearFlags.ColorAndDepth,
+ priority: 0,
+ ...over,
+});
+const dir = (over?: Partial<CameraDirectorState>): CameraDirectorState => ({
+ ...DEFAULT_DIRECTOR,
+ ...over,
+});
+
+describe('applyCurve', () => {
+ it('eases and clamps', () => {
+ expect(applyCurve(BlendCurve.Linear, 0.5)).toBeCloseTo(0.5);
+ expect(applyCurve(BlendCurve.EaseIn, 0.5)).toBeCloseTo(0.25);
+ expect(applyCurve(BlendCurve.EaseOut, 0.5)).toBeCloseTo(0.75);
+ expect(applyCurve(BlendCurve.EaseInOut, 0.5)).toBeCloseTo(0.5);
+ expect(applyCurve(BlendCurve.Linear, -1)).toBe(0);
+ expect(applyCurve(BlendCurve.Linear, 2)).toBe(1);
+ });
+});
+
+describe('lerpPOV', () => {
+ it('lerps continuous fields, snaps discrete to the target', () => {
+ const a = mkPOV({ x: 0, y: 0, orthoSize: 100 });
+ const b = mkPOV({ entity: 7, x: 100, y: 50, orthoSize: 200, priority: 5 });
+ const m = lerpPOV(a, b, 0.5);
+ expect(m.x).toBeCloseTo(50);
+ expect(m.y).toBeCloseTo(25);
+ expect(m.orthoSize).toBeCloseTo(150);
+ expect(m.entity).toBe(7);
+ expect(m.priority).toBe(5);
+ });
+
+ it('rotates the short way (350° → 10° passes through 360°/0°, not back through 180°)', () => {
+ const a = mkPOV({ rotation: (350 * Math.PI) / 180 });
+ const b = mkPOV({ rotation: (10 * Math.PI) / 180 });
+ const m = lerpPOV(a, b, 0.5);
+ const deg = ((m.rotation * 180) / Math.PI) % 360;
+ expect(Math.min(Math.abs(deg - 0), Math.abs(deg - 360))).toBeLessThan(1);
+ });
+});
+
+describe('resolveMainPOV', () => {
+ const A = mkPOV({ entity: 1, isActive: true, x: 0 });
+ const B = mkPOV({ entity: 2, x: 100 });
+
+ it('picks the isActive camera (authoritative over priority)', () => {
+ const lowActive = mkPOV({ entity: 1, isActive: true, priority: 0 });
+ const highInactive = mkPOV({ entity: 2, isActive: false, priority: 10 });
+ expect(resolveMainPOV(dir(), [highInactive, lowActive], 0, true)?.entity).toBe(1);
+ });
+
+ it('falls back to highest priority when none is active', () => {
+ const p0 = mkPOV({ entity: 1, priority: 0 });
+ const p5 = mkPOV({ entity: 2, priority: 5 });
+ expect(resolveMainPOV(dir(), [p0, p5], 0, true)?.entity).toBe(2);
+ });
+
+ it('blends from the current view to a new target over time', () => {
+ const d = dir();
+ expect(resolveMainPOV(d, [A, B], 0, true)?.entity).toBe(1); // A is current
+
+ d.hasPending = true;
+ d.pendingTarget = 2;
+ d.pendingTime = 2;
+ d.pendingCurve = BlendCurve.Linear;
+
+ expect(resolveMainPOV(d, [A, B], 0, true)!.x).toBeCloseTo(0); // start = A
+ expect(d.blending).toBe(true);
+ expect(resolveMainPOV(d, [A, B], 1, true)!.x).toBeCloseTo(50); // midpoint
+ const end = resolveMainPOV(d, [A, B], 2, true);
+ expect(end!.x).toBeCloseTo(100); // end = B
+ expect(end!.entity).toBe(2);
+ expect(d.blending).toBe(false);
+ });
+
+ it('peek (advance=false) returns the current view without advancing', () => {
+ const d = dir({ currentMain: A });
+ d.hasPending = true;
+ d.pendingTarget = 2;
+ expect(resolveMainPOV(d, [A, B], 5, false)).toBe(A);
+ expect(d.hasPending).toBe(true); // not consumed
+ });
+});
diff --git a/sdk/tests/camera-pov.test.ts b/sdk/tests/camera-pov.test.ts
index 0b9cb85b7..724efffd1 100644
--- a/sdk/tests/camera-pov.test.ts
+++ b/sdk/tests/camera-pov.test.ts
@@ -13,6 +13,7 @@ function ndc(vp: Float32Array, x: number, y: number) {
const pov = (over: Partial<CameraPOV>): CameraPOV => ({
entity: -1,
+ isActive: true,
x: 0,
y: 0,
z: 0,