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): dedicated editor viewport camera (EditorView override)
esenginef88c84ba2df5
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex df671f743..f9ac10b4c 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -10,7 +10,8 @@ import type { ESEngineModule, CppRegistry } from '../wasm';import type { World } from '../world';import type { Entity } from '../types';import { UICameraInfo } from '../ui/UICameraInfo';-import { ProjectionType, ScaleMode, SceneOwner } from '../component';+import { ProjectionType, ScaleMode, SceneOwner, ClearFlags } from '../component';+import { EditorView, DEFAULT_EDITOR_VIEW, type EditorViewData } from './EditorView';import { RenderPipeline } from '../renderPipeline';import { Renderer } from '../renderer';import { platformNow } from '../platform';@@ -167,6 +168,70 @@ export function collectCameras(return cameras;}+// =============================================================================+// Editor View (dedicated editor camera — overrides scene cameras when active)+// =============================================================================++/**+ * Build a full-frame CameraInfo from the editor view, reusing the SAME VP math+ * primitives (ortho / invertTranslation / multiply) as scene cameras — only the+ * camera *configuration* differs (full-frame viewport, raw orthoSize, no canvas+ * design-resolution scaling). This is what makes the editor view a first-class+ * peer of scene cameras rather than a separate view-math implementation.+ */+export function editorCameraInfo(+ view: EditorViewData,+ width: number,+ height: number,+ pool: CameraInfo[],+): CameraInfo {+ const aspect = height > 0 ? width / height : 1;+ const halfH = view.orthoSize;+ const halfW = halfH * aspect;+ const FAR = 100000;+ const projection = ortho(-halfW, halfW, -halfH, halfH, -FAR, FAR);+ const v = invertTranslation(view.x, view.y, 0);+ const cam = acquireCameraInfo(pool, 0);+ cam.entity = -1; // synthetic — not a scene entity+ cam.viewProjection.set(multiply(projection, v));+ cam.viewportRect.x = 0;+ cam.viewportRect.y = 0;+ cam.viewportRect.w = 1;+ cam.viewportRect.h = 1;+ cam.clearFlags = ClearFlags.ColorAndDepth;+ cam.priority = 0;+ cam.halfW = halfW;+ cam.halfH = halfH;+ cam.cameraX = view.x;+ cam.cameraY = view.y;+ return cam;+}++/**+ * 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.+ */+function resolveCameras(+ app: App,+ module: ESEngineModule,+ cppRegistry: CppRegistry,+ width: number,+ height: number,+ world: World | undefined,+ activeScenes: Set<string> | undefined,+ pool: CameraInfo[],+): CameraInfo[] {+ if (app.hasResource(EditorView)) {+ const view = app.getResource(EditorView);+ if (view.active && width > 0 && height > 0) {+ return [editorCameraInfo(view, width, height, pool)];+ }+ }+ return collectCameras(module, cppRegistry, width, height, world, activeScenes, pool);+}+// =============================================================================// UICameraInfo Sync// =============================================================================@@ -222,6 +287,10 @@ export function cameraPlugin(// so two Apps running at once never clobber each other's CameraInfo.const cameraInfoPool: CameraInfo[] = [];+ // 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 });+const viewport = getViewportSize ?? (() => {const dpr = typeof window !== 'undefined' ? (window.devicePixelRatio || 1) : 1;return {@@ -236,7 +305,8 @@ export function cameraPlugin(_params: [],_fn: () => {const { width, height } = viewport();- syncUICameraInfo(app, module, cppRegistry, width, height, undefined, cameraInfoPool);+ const cameras = resolveCameras(app, module, cppRegistry, width, height, undefined, undefined, cameraInfoPool);+ syncUICameraInfo(app, module, cppRegistry, width, height, cameras);},};@@ -267,7 +337,7 @@ export function cameraPlugin(}pipeline.setActiveScenes(activeScenes ?? null);- const cameras = collectCameras(module, cppRegistry, width, height, app.world, activeScenes, cameraInfoPool);+ const cameras = resolveCameras(app, module, cppRegistry, width, height, app.world, activeScenes, cameraInfoPool);syncUICameraInfo(app, module, cppRegistry, width, height, cameras);diff --git a/sdk/src/camera/EditorView.ts b/sdk/src/camera/EditorView.tsnew file mode 100644index 000000000..8c79f40e5--- /dev/null+++ b/sdk/src/camera/EditorView.ts@@ -0,0 +1,31 @@+/**+ * @file EditorView.ts+ * @brief Editor viewport camera — a dedicated, editor-only 2D view.+ *+ * This is NOT a scene entity: it is never serialized, never on the undo stack,+ * and never part of the saved scene. When `active`, the camera system renders+ * the framebuffer through this view and drives all screen<->world queries from+ * it (CameraView / UICameraInfo) INSTEAD of the scene's game Camera entities —+ * so editor navigation (pan / zoom / frame) moves only this view and never the+ * scene's camera. In play mode it is deactivated, so the viewport shows the real+ * game camera (the true "Game" view). The editor mutates x / y / orthoSize.+ *+ * The view's view-projection is built from the SAME math primitives as scene+ * cameras (see CameraPlugin) — there is one source of view-projection math; only+ * the camera *configuration* (full-frame, raw orthoSize) differs.+ */+import { defineResource } from '../resource';++export interface EditorViewData {+ /** When true, the framebuffer + screen<->world use this view, not scene cameras. */+ active: boolean;+ /** World-space camera center. */+ x: number;+ y: number;+ /** Half-height of the view in world units (zoom; smaller = more zoomed in). */+ orthoSize: number;+}++export const DEFAULT_EDITOR_VIEW: EditorViewData = { active: false, x: 0, y: 0, orthoSize: 360 };++export const EditorView = defineResource<EditorViewData>({ ...DEFAULT_EDITOR_VIEW }, 'EditorView');diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 875bbdbe0..68ca23087 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -38,6 +38,8 @@ 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';// =============================================================================// Draw APIdiff --git a/sdk/tests/editor-view.test.ts b/sdk/tests/editor-view.test.tsnew file mode 100644index 000000000..a2cc056c9--- /dev/null+++ b/sdk/tests/editor-view.test.ts@@ -0,0 +1,54 @@+/**+ * @file Editor camera (EditorView) — verifies the editor viewport camera builds+ * a geometrically correct full-frame view-projection from {x, y, orthoSize},+ * using the same math primitives as scene cameras. This is the new code in+ * the camera override path; the render path itself is shared with scene+ * cameras (so if scene cameras render, the editor camera renders).+ */+import { describe, it, expect } from 'vitest';+import { editorCameraInfo } from '../src/camera/CameraPlugin';+import { ClearFlags } from '../src/component';++// Apply a column-major VP matrix to a 2D world point → clip/NDC xy.+function ndc(vp: Float32Array, x: number, y: number) {+ return {+ x: vp[0] * x + vp[4] * y + vp[12],+ y: vp[1] * x + vp[5] * y + vp[13],+ };+}++describe('EditorView camera', () => {+ it('builds a full-frame ortho view centered on (x, y) with orthoSize half-height', () => {+ const cam = editorCameraInfo({ active: true, x: 100, y: 50, orthoSize: 300 }, 800, 600, []);++ // Configuration: synthetic (no entity), full-frame, clears color+depth.+ expect(cam.entity).toBe(-1);+ expect(cam.viewportRect).toEqual({ x: 0, y: 0, w: 1, h: 1 });+ expect(cam.clearFlags).toBe(ClearFlags.ColorAndDepth);+ expect(cam.cameraX).toBe(100);+ expect(cam.cameraY).toBe(50);+ expect(cam.halfH).toBe(300);+ expect(cam.halfW).toBeCloseTo(300 * (800 / 600)); // 400, aspect-corrected++ // Geometry: the camera center maps to clip origin; the view edges to ±1.+ const center = ndc(cam.viewProjection, 100, 50);+ expect(center.x).toBeCloseTo(0);+ expect(center.y).toBeCloseTo(0);++ const right = ndc(cam.viewProjection, 100 + cam.halfW, 50);+ expect(right.x).toBeCloseTo(1);++ const top = ndc(cam.viewProjection, 100, 50 + 300);+ expect(top.y).toBeCloseTo(1);+ });++ it('zoom (orthoSize) widens/narrows the visible world extent', () => {+ const near = editorCameraInfo({ active: true, x: 0, y: 0, orthoSize: 100 }, 800, 600, []);+ const far = editorCameraInfo({ active: true, x: 0, y: 0, orthoSize: 400 }, 800, 600, []);+ // A larger orthoSize sees more world → a given world point sits closer to center.+ const p = 200;+ expect(Math.abs(ndc(near.viewProjection, p, 0).x)).toBeGreaterThan(+ Math.abs(ndc(far.viewProjection, p, 0).x),+ );+ });+});