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): dedicated editor viewport camera (EditorView override)

esenginef88c84ba2df5
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 API
diff --git a/sdk/tests/editor-view.test.ts b/sdk/tests/editor-view.test.ts
new file mode 100644
index 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),
+ );
+ });
+});