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(engine): camera director + view-target blending (camera modernization C)
esengine16ae4de87bb4
diff --git a/sdk/src/camera/CameraDirector.ts b/sdk/src/camera/CameraDirector.tsnew file mode 100644index 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.tsindex 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.tsindex 68ca23087..e3517885f 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -40,6 +40,9 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTexturexport { 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 APIdiff --git a/sdk/tests/camera-director.test.ts b/sdk/tests/camera-director.test.tsnew file mode 100644index 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.tsindex 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,