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.

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.ts
index 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.ts
index 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). Leaves
diff --git a/sdk/src/camera/EditorView.ts b/sdk/src/camera/EditorView.ts
index 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.ts
index 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.ts
index 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);
+ });
+});