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): the 3D view button turns the eye

yhh606ae8930775
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b9d55087..95d3b11b7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,20 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **The 3D view button turns the eye.** It swapped the editor camera's projection
+ and nothing else, and swapping projection is invisible: looked at head-on, a
+ perspective picture of the z = 0 plane is the orthographic one, pixel for pixel.
+ So on exactly the scenes people press it on, a button labelled 3D appeared to do
+ nothing — depth was only ever visible after finding Alt-drag, which turns the eye
+ in either projection anyway.
+
+ Each projection now remembers the angle it was last looked at from; the toggle
+ parks one and restores the other, entering 3D from head-on for the first time
+ with a three-quarter view. A turned orthographic view — the isometric one — is a
+ working mode, and it survives the round trip unchanged.
+
### Added
- **Geometry you can make without a modelling package.** The engine drew meshes
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index 9f8b648ab..301adfb99 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -34,6 +34,30 @@ import type { ReadonlyWorldT, WorldT } from './schema';
const DEFAULT_SCENE_URL = '/scenes/sprite-rendering.esscene';
const DEFAULT_TEXTURES_URL = '/scenes/sprite-rendering.textures.json';
+/** Where the eye stands the first time the 3D view is entered from head-on. */
+const DEFAULT_3D_ORBIT = { yaw: 30, pitch: 25 };
+
+/** An eye angle in degrees, and the angle each projection is parked at. */
+export interface EyeAngle { yaw: number; pitch: number }
+export interface ParkedEye { ortho: EyeAngle | null; perspective: EyeAngle | null }
+
+export const NO_PARKED_EYE: ParkedEye = { ortho: null, perspective: null };
+
+/**
+ * Where the eye should stand after a projection toggle, and what each projection
+ * is left parked at. Swapping projection alone is INVISIBLE — head-on, a
+ * perspective picture of the z = 0 plane is the orthographic one — so a toggle
+ * parks the angle it leaves and restores the one it enters.
+ */
+export function eyeAcrossProjection(
+ toPerspective: boolean, from: EyeAngle, parked: ParkedEye,
+): EyeAngle & { parked: ParkedEye } {
+ const here = { yaw: from.yaw, pitch: from.pitch };
+ const eye = parked[toPerspective ? 'perspective' : 'ortho']
+ ?? (toPerspective ? DEFAULT_3D_ORBIT : here);
+ return { ...eye, parked: { ...parked, [toPerspective ? 'ortho' : 'perspective']: here } };
+}
+
export type EngineStatus = 'idle' | 'booting' | 'ready' | 'error';
export interface EngineSnapshot {
@@ -77,6 +101,8 @@ class EngineHostImpl {
// Play-state isolation: Stop rebuilds the World from the untouched edit model
// (model-authoritative), so no snapshot is needed — the model IS the truth.
private playing_ = false;
+ /** Where each projection was last looked from, so a toggle round trip is one. */
+ private parkedEye_: ParkedEye = NO_PARKED_EYE;
// What to load once the engine is ready. Set by ProjectStore when a project
// is opened from the launcher; absent → the in-repo placeholder scene (dev).
@@ -383,6 +409,11 @@ class EngineHostImpl {
const seen = editorViewHalfHeight(view);
view.perspective = on;
setEditorViewHalfHeight(view, seen);
+
+ const turn = eyeAcrossProjection(on, view, this.parkedEye_);
+ view.yaw = turn.yaw;
+ view.pitch = turn.pitch;
+ this.parkedEye_ = turn.parked;
}
/** The active (or first) scene camera's center + ortho half-height, for seeding. */
diff --git a/desktop/src/i18n/messages/commands.ts b/desktop/src/i18n/messages/commands.ts
index 10daf9e66..e47a0b58b 100644
--- a/desktop/src/i18n/messages/commands.ts
+++ b/desktop/src/i18n/messages/commands.ts
@@ -55,7 +55,7 @@ export const commandMessages = defineMessages({
'cmd.view.toggleColliders': { en: 'Show Physics Gizmos', zh: '显示物理 Gizmo' },
'cmd.view.toggleTileCollision': { en: 'Show Tile Collision', zh: '显示瓦片碰撞' },
'cmd.view.toggleCoordSpace': { en: 'Local Axes', zh: '局部坐标轴' },
- 'cmd.view.toggleViewPerspective': { en: 'Perspective View', zh: '透视视图' },
+ 'cmd.view.toggleViewPerspective': { en: '3D View', zh: '3D 视图' },
'cmd.view.togglePivotMode': { en: 'Pivot (vs Center)', zh: '轴心(而非中心)' },
'cmd.view.resetOrbit': { en: 'Face Scene Head-On', zh: '恢复正对视角' },
'cmd.view.toggleSnapping': { en: 'Snapping', zh: '吸附' },
diff --git a/desktop/src/i18n/messages/viewport.ts b/desktop/src/i18n/messages/viewport.ts
index 353e09fc7..03b46d9c1 100644
--- a/desktop/src/i18n/messages/viewport.ts
+++ b/desktop/src/i18n/messages/viewport.ts
@@ -102,7 +102,7 @@ export const viewportMessages = defineMessages({
},
'vp.pivot.pivot': { en: 'Pivot', zh: '轴心' },
'vp.pivot.center': { en: 'Center', zh: '中心' },
- 'vp.projectionTitle': { en: 'Editor viewport projection — perspective makes depth visible for 2.5D authoring. Does not change the game camera.', zh: '编辑器视口投影——透视可在编辑 2.5D 时看见深度。不影响游戏相机。' },
+ 'vp.projectionTitle': { en: 'The editor eye: 3D looks at the scene in perspective, from an angle. Alt-drag turns it further; each mode keeps the angle you left it at. Does not change the game camera.', zh: '编辑器视角:3D 用透视、从一个角度看场景。Alt+拖拽可继续转动;两种模式各自记住你离开时的角度。不影响游戏相机。' },
'vp.proj.ortho': { en: '2D', zh: '2D' },
'vp.proj.perspective': { en: '3D', zh: '3D' },
'vp.resetOrbitTitle': {
diff --git a/desktop/tests/editor-eye-projection.test.ts b/desktop/tests/editor-eye-projection.test.ts
new file mode 100644
index 000000000..940fc8ce1
--- /dev/null
+++ b/desktop/tests/editor-eye-projection.test.ts
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Where the editor's eye stands across a 2D/3D toggle.
+ *
+ * Swapping projection alone is invisible — head-on, a perspective picture of the
+ * z = 0 plane IS the orthographic one — so the toggle turns the eye. What that
+ * must not cost is the angle you had: an isometric orthographic view is a working
+ * mode, and it has to survive going to 3D and back.
+ */
+import { describe, it, expect } from 'vitest';
+import { eyeAcrossProjection, NO_PARKED_EYE, type ParkedEye } from '@/engine/EngineHost';
+
+const HEAD_ON = { yaw: 0, pitch: 0 };
+
+/** Toggle repeatedly, threading the parked angles the way EngineHost does. */
+function toggle(steps: boolean[], from = HEAD_ON, parked: ParkedEye = NO_PARKED_EYE) {
+ let eye = from;
+ let park = parked;
+ const seen = [];
+ for (const toPerspective of steps) {
+ const next = eyeAcrossProjection(toPerspective, eye, park);
+ eye = { yaw: next.yaw, pitch: next.pitch };
+ park = next.parked;
+ seen.push(eye);
+ }
+ return { eye, parked: park, seen };
+}
+
+describe('the editor eye across a projection toggle', () => {
+ it('turns the eye when 3D is entered head-on', () => {
+ const { eye } = toggle([true]);
+ expect(eye).not.toEqual(HEAD_ON);
+ expect(eye.pitch).toBeGreaterThan(0);
+ });
+
+ it('faces the scene head-on again on the way back', () => {
+ expect(toggle([true, false]).eye).toEqual(HEAD_ON);
+ });
+
+ it('returns to where 3D was left, not to the default', () => {
+ const first = toggle([true]);
+ const turned = { yaw: 50, pitch: 40 };
+ const back = eyeAcrossProjection(false, turned, first.parked);
+ const again = eyeAcrossProjection(true, back, back.parked);
+ expect({ yaw: again.yaw, pitch: again.pitch }).toEqual(turned);
+ expect(turned).not.toEqual(first.eye);
+ });
+
+ it('keeps an isometric 2D view through a round trip', () => {
+ const iso = { yaw: 20, pitch: 10 };
+ const { eye } = toggle([true, false], iso);
+ expect(eye).toEqual(iso);
+ });
+
+ it('parks the angle of the projection it leaves, both ways', () => {
+ const { parked } = toggle([true], { yaw: 20, pitch: 10 });
+ expect(parked.ortho).toEqual({ yaw: 20, pitch: 10 });
+ expect(parked.perspective).toBeNull();
+ });
+});