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
fix(editor): how much world the view sees is one formula, so the grid covers it
yhh5e7ef25263f8
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.tsindex 8cfa3e06d..bf7070370 100644--- a/desktop/src/engine/EngineHost.ts+++ b/desktop/src/engine/EngineHost.ts@@ -9,7 +9,7 @@ import {Transform,Sprite,Camera,- EditorView,+ EditorView, editorViewHalfHeight, setEditorViewHalfHeight,EditorGrid,installEditorGrid,setEditorMode,@@ -302,17 +302,21 @@ class EngineHostImpl {if (cam) {view.x = cam.x;view.y = cam.y;- view.orthoSize = cam.orthoSize;+ // The scene camera's framing, as an extent the editor view SEES — under a+ // perspective eye that is a distance, not an orthoSize.+ setEditorViewHalfHeight(view, cam.orthoSize);}view.active = !this.playing_;}- /** The editor camera's current center + ortho half-height, or null pre-boot.- * Prefab Mode saves this on enter so exit can return the user to the exact- * scene view they left (syncEditorViewToScene would otherwise reframe). */+ /** The editor camera's current center + the world half-height it SEES, or null+ * pre-boot. Prefab Mode saves this on enter so exit can return the user to the+ * exact scene view they left (syncEditorViewToScene would otherwise reframe).+ * The seen extent rather than the raw field, so a view saved in perspective and+ * restored in either projection comes back to the same framing. */editorViewState(): { x: number; y: number; orthoSize: number } | null {const view = this.getResource(EditorView);- return view ? { x: view.x, y: view.y, orthoSize: view.orthoSize } : null;+ return view ? { x: view.x, y: view.y, orthoSize: editorViewHalfHeight(view) } : null;}/** Restore the editor camera to a saved center + zoom (the inverse read of@@ -322,7 +326,7 @@ class EngineHostImpl {if (!view) return;view.x = v.x;view.y = v.y;- view.orthoSize = v.orthoSize;+ setEditorViewHalfHeight(view, v.orthoSize);}/**diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.tsindex 753acdbf3..b73bd510d 100644--- a/desktop/src/engine/ViewportController.ts+++ b/desktop/src/engine/ViewportController.ts@@ -12,6 +12,7 @@ import {tileCellCenter, tileCellOutline, isNonOrthogonal,readColliderShapes, colliderShapeOutline, shapeCenter,layerOrderOf,+ editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight,type TilesetModel, type TileCollisionPiece, type TileGridParams,} from 'esengine';import type { EntityId } from '@/types';@@ -26,7 +27,6 @@ import {pointInOBB,rectsIntersect,screenAABB,- clamp,worldToLocal2D,rankPickCandidates,type PickCandidate,@@ -86,22 +86,23 @@ function editorView(): EditorViewData | null {}/**- * The quantity zoom scales, which differs by projection but behaves the same.+ * What zoom scales: the world half-height the view SEES on the z = 0 plane.*- * Orthographically it is the half-height of the view box. In perspective it is- * the camera's distance — and on the z = 0 plane, where 2D content lives, the- * visible extent is proportional to distance exactly as it is to orthoSize. That- * is what lets one zoom formula serve both instead of two that drift.+ * Orthographically that is `orthoSize`; in perspective it is the frustum's+ * cross-section there, which the camera's distance moves. Working in the seen+ * extent rather than in whichever field each projection zooms with is what lets+ * one zoom, one framing and one minimap rect serve both — the SDK owns the+ * conversion (editorViewHalfHeight / setEditorViewHalfHeight) so the grid, which+ * has to cover exactly this rect, cannot disagree with the navigation that moved+ * it.*/const ZOOM_MIN = 8;const ZOOM_MAX = 40000;function zoomAmount(view: EditorViewData): number {- return view.perspective ? view.distance : view.orthoSize;+ return editorViewHalfHeight(view);}function setZoomAmount(view: EditorViewData, value: number): void {- const v = Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, value));- if (view.perspective) view.distance = v;- else view.orthoSize = v;+ setEditorViewHalfHeight(view, Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, value)));}/** DOM pointer position → engine screen space (buffer px, y-up). */@@ -489,9 +490,11 @@ export const ViewportController = {const spanX = maxX - minX;const spanY = maxY - minY;const aspect = canvas && canvas.height > 0 ? canvas.width / canvas.height : 1;- // orthoSize is the view half-height; fit whichever axis is the binding constraint.+ // Fit whichever axis is the binding constraint, in SEEN half-height — which+ // the perspective view reaches by moving the camera, not by writing orthoSize+ // (a field it does not render through: framing simply did nothing there).const halfH = Math.max(spanY / 2, aspect > 0 ? spanX / 2 / aspect : spanX / 2) * 1.2;- if (halfH > 1) view.orthoSize = clamp(halfH, 8, 40000);+ if (halfH > 1) setZoomAmount(view, halfH);},/**@@ -519,17 +522,17 @@ export const ViewportController = {view.y = ci.cy;const aspect = panel && panel.height > 0 ? panel.width / panel.height : 1;const halfH = Math.max(desHalfH, aspect > 0 ? desHalfW / aspect : desHalfW) * 1.1;- view.orthoSize = clamp(halfH, 8, 40000);+ setZoomAmount(view, halfH);},- /** World center + half-extents of the editor camera's visible rect — the minimap's- * camera indicator. Half-height = orthoSize; half-width = orthoSize × panel aspect. */+ /** World center + half-extents of the editor camera's visible rect on the z = 0+ * plane — the minimap's camera indicator, from the same extent the grid covers. */editorViewRect(): { cx: number; cy: number; halfW: number; halfH: number } | null {const view = editorView();const canvas = EngineHost.canvas;if (!view) return null;const aspect = canvas && canvas.height > 0 ? canvas.width / canvas.height : 1;- return { cx: view.x, cy: view.y, halfW: view.orthoSize * aspect, halfH: view.orthoSize };+ return { cx: view.x, cy: view.y, ...editorViewHalfExtent(view, aspect) };},/** Recenter the editor view on a world point (minimap click / drag navigation). Leavesdiff --git a/sdk/src/camera/EditorView.ts b/sdk/src/camera/EditorView.tsindex c013f0e00..50c479493 100644--- a/sdk/src/camera/EditorView.ts+++ b/sdk/src/camera/EditorView.ts@@ -62,4 +62,42 @@ export const DEFAULT_EDITOR_VIEW: EditorViewData = {perspective: false, fov: 60, distance: 1000,};+/**+ * Half-height, in world units, of what the view sees on the z = 0 plane — where+ * 2D content lives and where the grid, the framing and the minimap all measure.+ *+ * Orthographically this IS `orthoSize`. In perspective the visible extent is the+ * frustum's cross-section at the focus plane, `tan(fov/2) · distance` — merely+ * proportional to the zoom value, not equal to it. Everything that needs "how+ * much world is on screen" asks here rather than reading `orthoSize`, which+ * answers for one of the two projections and silently mis-scales the other.+ */+export function editorViewHalfHeight(view: EditorViewData): number {+ return view.perspective+ ? Math.tan((view.fov * Math.PI) / 180 / 2) * view.distance+ : view.orthoSize;+}++/** {@link editorViewHalfHeight} with the panel aspect applied — the visible world rect. */+export function editorViewHalfExtent(+ view: EditorViewData, aspect: number,+): { halfW: number; halfH: number } {+ const halfH = editorViewHalfHeight(view);+ return { halfW: halfH * (aspect > 0 ? aspect : 1), halfH };+}++/**+ * Zoom the view until it sees @p halfH world units of height, writing whichever+ * field this projection zooms with. The inverse of {@link editorViewHalfHeight},+ * so "frame this" and "how big is what I see" cannot disagree.+ */+export function setEditorViewHalfHeight(view: EditorViewData, halfH: number): void {+ if (view.perspective) {+ const t = Math.tan((view.fov * Math.PI) / 180 / 2);+ view.distance = t > 0 ? halfH / t : halfH;+ } else {+ view.orthoSize = halfH;+ }+}+export const EditorView = defineResource<EditorViewData>({ ...DEFAULT_EDITOR_VIEW }, 'EditorView');diff --git a/sdk/src/camera/editorGridRenderer.ts b/sdk/src/camera/editorGridRenderer.tsindex 2ae379944..0233808d8 100644--- a/sdk/src/camera/editorGridRenderer.ts+++ b/sdk/src/camera/editorGridRenderer.ts@@ -11,10 +11,11 @@* pre-scene pass, scene entities occlude the grid (UE5 / Unity behaviour).** The quad is a unit quad placed by the `u_rect` param (centre = EditorView.x/y,- * half-extents = orthoSize * aspect by orthoSize) to cover the camera's visible- * world rect, so the fragment's interpolated world position is exact and no- * inverse view-projection is needed. Line width and minor-line density fade are- * driven by `worldPerPixel` (= 2·orthoSize / viewportHeight), so the grid stays+ * half-extents = `editorViewHalfExtent`) to cover the camera's visible world rect+ * on the z = 0 plane, so the fragment's interpolated world position is exact and+ * no inverse view-projection is needed — under either projection, since that is+ * the one place the extent is worked out. Line width and minor-line density fade+ * are driven by `worldPerPixel` (= 2·halfH / viewportHeight), so the grid stays* crisp and moiré-free at every zoom without relying on GLSL derivatives.** The shader is a dual-language `.esshader` (GLSL + WGSL twins) on the reflected@@ -31,7 +32,7 @@ import { Geometry, type GeometryHandle } from '../render/geometry';import { Material, type MaterialHandle } from '../render/material';import { BlendMode } from '../render/blend';import { registerPreSceneDrawCallback } from '../render/customDraw';-import { EditorView } from './EditorView';+import { EditorView, editorViewHalfExtent } from './EditorView';import { EditorGrid, DEFAULT_EDITOR_GRID } from './EditorGrid';/** The grid's dual-language material shader (exported for the twins structure guard). */@@ -207,8 +208,11 @@ export function installEditorGrid(app: App): void {if (!grid.enabled || !view.active || grid.spacing <= 0) return;if (!ensureResources()) return;- const halfH = view.orthoSize;- const halfW = halfH * (width / height);+ // The rect the camera actually sees on the z = 0 plane the quad sits on. Under+ // a perspective eye that is NOT orthoSize — reading it there left the grid a+ // bounded island floating in the middle of the viewport, since the quad was+ // sized for a projection the view is no longer using.+ const { halfW, halfH } = editorViewHalfExtent(view, width / height);const worldPerPixel = (2 * halfH) / height;setParam('u_rect', view.x, view.y, halfW, halfH);diff --git a/sdk/tests/editor-view.test.ts b/sdk/tests/editor-view.test.tsindex b06ca6a49..6d41eca22 100644--- a/sdk/tests/editor-view.test.ts+++ b/sdk/tests/editor-view.test.ts@@ -59,7 +59,12 @@ describe('EditorView camera', () => {// Perspective preview (2.5D authoring)// =============================================================================-import { DEFAULT_EDITOR_VIEW } from '../src/camera/EditorView';+import {+ DEFAULT_EDITOR_VIEW,+ editorViewHalfExtent,+ editorViewHalfHeight,+ setEditorViewHalfHeight,+} from '../src/camera/EditorView';const view = (over: Partial<typeof DEFAULT_EDITOR_VIEW>) =>({ ...DEFAULT_EDITOR_VIEW, active: true, ...over });@@ -111,3 +116,69 @@ describe('EditorView perspective preview', () => {.toBeGreaterThan(Math.abs(ndc3(wide.viewProjection, 100, 0, 0).x));});});++// =============================================================================+// How much world the view SEES — the one extent the grid, the framing and the+// minimap all measure with. Read from the projection itself, so the helper+// cannot drift from the matrix it claims to describe.+// =============================================================================++describe('editorViewHalfHeight', () => {+ // What "half-height" has to mean, under either projection: the world y that+ // lands exactly on the top edge of the frame on the z = 0 plane.+ const seenHalfHeight = (v: typeof DEFAULT_EDITOR_VIEW): number => {+ const cam = editorCameraInfo(v, 800, 600, []);+ let lo = 0;+ let hi = 1e6;+ for (let i = 0; i < 60; i++) {+ const mid = (lo + hi) / 2;+ if (ndc3(cam.viewProjection, v.x, v.y + mid, 0).y <= 1) lo = mid;+ else hi = mid;+ }+ return lo;+ };++ it('is orthoSize orthographically', () => {+ const v = view({ orthoSize: 300 });+ expect(editorViewHalfHeight(v)).toBe(300);+ expect(seenHalfHeight(v)).toBeCloseTo(300, 1);+ });++ it('is the frustum cross-section at z = 0 in perspective — NOT the distance', () => {+ const v = view({ perspective: true, fov: 60, distance: 1000 });+ const expected = Math.tan((60 * Math.PI) / 180 / 2) * 1000; // ≈ 577.35+ expect(editorViewHalfHeight(v)).toBeCloseTo(expected, 4);+ expect(editorViewHalfHeight(v)).not.toBeCloseTo(1000, 0);+ expect(seenHalfHeight(v)).toBeCloseTo(expected, 0);+ });++ it('scales with aspect on the horizontal, like an ortho box does', () => {+ const v = view({ perspective: true, fov: 60, distance: 1000 });+ const { halfW, halfH } = editorViewHalfExtent(v, 800 / 600);+ expect(halfW).toBeCloseTo(halfH * (800 / 600), 4);+ });++ // Framing writes an extent; zooming reads one. If the two disagree, "frame+ // selection" lands on a different zoom than it asked for — which is what+ // writing orthoSize under a perspective view did (it did nothing at all).+ it('round-trips through setEditorViewHalfHeight in both projections', () => {+ for (const perspective of [false, true]) {+ const v = view({ perspective, fov: 60, distance: 1000, orthoSize: 300 });+ setEditorViewHalfHeight(v, 420);+ expect(editorViewHalfHeight(v)).toBeCloseTo(420, 6);+ expect(seenHalfHeight(v)).toBeCloseTo(420, 0);+ }+ });++ it('moves the camera in perspective and the box orthographically', () => {+ const p = view({ perspective: true, fov: 60, distance: 1000, orthoSize: 300 });+ setEditorViewHalfHeight(p, 1154.7);+ expect(p.distance).toBeCloseTo(2000, 0);+ expect(p.orthoSize).toBe(300); // untouched — not the field this view renders through++ const o = view({ orthoSize: 300, distance: 1000 });+ setEditorViewHalfHeight(o, 500);+ expect(o.orthoSize).toBe(500);+ expect(o.distance).toBe(1000);+ });+});