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(editor): the editor's eye can turn

esengine9b4941f8d7e9
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 49ba86e8b..65784fa7b 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -22,6 +22,7 @@
* ESTELLA_VERIFY_PREFAB .esprefab instantiated into the scene after load
* ESTELLA_VERIFY_SET_FIELD one inspector field written after load (JSON)
* ESTELLA_VERIFY_PICK hit-test a viewport point, asserting the entity (JSON)
+ * ESTELLA_VERIFY_ORBIT turn the editor eye before capture ("yaw,pitch" degrees)
*/
import { app, BrowserWindow } from 'electron';
import http from 'node:http';
@@ -288,6 +289,20 @@ app.whenReady().then(async () => {
})()`);
}
+ // ESTELLA_VERIFY_ORBIT="<yaw>,<pitch>" turns the editor's eye before the frame
+ // is read — the 3D navigation, driven the way Alt-drag drives it.
+ if (process.env.ESTELLA_VERIFY_ORBIT) {
+ const [yaw, pitch] = process.env.ESTELLA_VERIFY_ORBIT.split(',').map(Number);
+ await exec(`(async () => {
+ const api = window.__estellaHeadless.api;
+ // The orbit belongs to the editor's eye, so the frame has to be drawn
+ // through it rather than through the scene's own camera.
+ api.useEditorView(true);
+ api.setViewOrbit(${yaw || 0}, ${pitch || 0});
+ await api.step(2, 1 / 60);
+ })()`);
+ }
+
// ESTELLA_VERIFY_PICK={"x","y","entity"} clicks a point (viewport fractions)
// and asserts which entity answers — the editor's own hit test, whose box for
// a mesh is its geometry rather than the icon square a shapeless entity gets.
diff --git a/desktop/src/commands/editorCommands.ts b/desktop/src/commands/editorCommands.ts
index 4824db218..0cb001436 100644
--- a/desktop/src/commands/editorCommands.ts
+++ b/desktop/src/commands/editorCommands.ts
@@ -491,6 +491,16 @@ commands.register({
isChecked: () => editor().viewPerspective,
run: () => editor().toggleViewPerspective(),
});
+commands.register({
+ id: 'view.resetOrbit',
+ label: t('cmd.view.resetOrbit'),
+ category: t('cat.view'),
+ isEnabled: () => ViewportController.isOrbited(),
+ run: () => {
+ ViewportController.resetOrbit();
+ editor().setViewOrbited(false);
+ },
+});
commands.register({
id: 'view.togglePivotMode',
label: t('cmd.view.togglePivotMode'),
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index fa0e7cf7a..59761efc0 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -840,6 +840,21 @@ export class EditorControlSurfaceImpl {
return (rt == null ? null : this.s.model.sourceFor(rt)) ?? null;
}
+ /**
+ * Turn the editor's eye off the head-on axis (degrees). What Alt-drag does, as
+ * one call — so a driver can look at a scene from somewhere else and assert
+ * what it sees. Both zero is the 2D view, exactly as it was.
+ */
+ setViewOrbit(yaw: number, pitch: number): void {
+ ViewportController.setOrbit(yaw, pitch);
+ }
+
+ /** Render (and hit-test) through the editor's own eye rather than the scene
+ * camera — what edit mode does, as one call a driver can make. */
+ useEditorView(on: boolean): void {
+ EngineHost.setEditorViewActive(on);
+ }
+
/** Screen rect (CSS px rel. canvas) of an entity's selection bounds, or null. */
entityScreenRect(id: EntityId): { x: number; y: number; w: number; h: number } | null {
return ViewportController.getEntityScreenRect(id);
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index d69e707cf..a3adec669 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -291,6 +291,18 @@ class EngineHostImpl {
return wasStop;
}
+ /**
+ * Look through the editor's own eye, or through the scene's camera. Activating
+ * seeds the view from that camera (see syncEditorViewToScene), so the two show
+ * the same framing until navigation moves one of them.
+ */
+ setEditorViewActive(on: boolean): void {
+ const view = this.getResource(EditorView);
+ if (!view) return;
+ if (on) this.syncEditorViewToScene();
+ else view.active = false;
+ }
+
/**
* Seed the editor camera from the scene's active camera and activate it for
* edit mode. Called after a scene loads; navigation thereafter is independent
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index b4309c3cc..165024063 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -13,7 +13,7 @@ import {
readColliderShapes, colliderShapeOutline, shapeCenter,
layerOrderOf,
editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, EDITOR_UI_ANCHOR,
- entityWorldBox, uiNodeWorldBox, meshWorldBox,
+ entityWorldBox, uiNodeWorldBox, meshWorldBox, editorViewIsOrbited,
type TilesetModel, type TileCollisionPiece, type TileGridParams,
} from 'esengine';
import type { EntityId } from '@/types';
@@ -36,6 +36,8 @@ import {
// World half-size of the pick/outline box for entities without renderable bounds
// (cameras, lights, empties) — so they're click-selectable like any sprite.
const ICON_WORLD_HALF = 24;
+// Degrees of turn per pixel dragged — the rate a DCC's orbit uses.
+const ORBIT_DEG_PER_PX = 0.4;
// Pick priority for icon-only entities: above any real sprite layer, so a small
// foreground gizmo (camera/light) wins a tie against a big sprite beneath it.
const ICON_PICK_LAYER = 1e6;
@@ -456,6 +458,37 @@ export const ViewportController = {
view.y += a.y - b.y;
},
+ /**
+ * Turn the eye around what it is looking at (Alt-drag). Degrees per pixel is
+ * the rate every DCC uses; pitch stops short of the poles, where the up vector
+ * is parallel to the view and the frame would roll.
+ */
+ orbitByClient(prevX: number, prevY: number, curX: number, curY: number): void {
+ const view = editorView();
+ if (!view) return;
+ view.yaw += (curX - prevX) * ORBIT_DEG_PER_PX;
+ view.pitch = Math.max(-89, Math.min(89, view.pitch + (curY - prevY) * ORBIT_DEG_PER_PX));
+ },
+
+ /** Point the eye at a given yaw/pitch (degrees) — the automation door's orbit. */
+ setOrbit(yaw: number, pitch: number): void {
+ const view = editorView();
+ if (!view) return;
+ view.yaw = yaw;
+ view.pitch = Math.max(-89, Math.min(89, pitch));
+ },
+
+ /** Face the scene head-on again — the 2D view, exactly as it was. */
+ resetOrbit(): void {
+ this.setOrbit(0, 0);
+ },
+
+ /** True while the eye is turned off the head-on axis (drives the reset affordance). */
+ isOrbited(): boolean {
+ const view = editorView();
+ return view ? editorViewIsOrbited(view) : false;
+ },
+
/** Zoom the editor view: factor > 1 zooms out, < 1 zooms in (editor orthoSize). */
zoomBy(factor: number): void {
const view = editorView();
diff --git a/desktop/src/i18n/messages/commands.ts b/desktop/src/i18n/messages/commands.ts
index f1327aa97..10daf9e66 100644
--- a/desktop/src/i18n/messages/commands.ts
+++ b/desktop/src/i18n/messages/commands.ts
@@ -57,6 +57,7 @@ export const commandMessages = defineMessages({
'cmd.view.toggleCoordSpace': { en: 'Local Axes', zh: '局部坐标轴' },
'cmd.view.toggleViewPerspective': { en: 'Perspective View', zh: '透视视图' },
'cmd.view.togglePivotMode': { en: 'Pivot (vs Center)', zh: '轴心(而非中心)' },
+ 'cmd.view.resetOrbit': { en: 'Face Scene Head-On', zh: '恢复正对视角' },
'cmd.view.toggleSnapping': { en: 'Snapping', zh: '吸附' },
'cmd.view.toggleMinimap': { en: 'Minimap', zh: '小地图' },
'cmd.view.toggleStats': { en: 'Stats HUD', zh: '统计信息' },
diff --git a/desktop/src/i18n/messages/viewport.ts b/desktop/src/i18n/messages/viewport.ts
index e37de8aae..d08c4cb5e 100644
--- a/desktop/src/i18n/messages/viewport.ts
+++ b/desktop/src/i18n/messages/viewport.ts
@@ -105,6 +105,10 @@ export const viewportMessages = defineMessages({
'vp.projectionTitle': { en: 'Editor viewport projection — perspective makes depth visible for 2.5D authoring. Does not change the game camera.', zh: '编辑器视口投影——透视可在编辑 2.5D 时看见深度。不影响游戏相机。' },
'vp.proj.ortho': { en: '2D', zh: '2D' },
'vp.proj.perspective': { en: '3D', zh: '3D' },
+ 'vp.resetOrbitTitle': {
+ en: 'Face the scene head-on again (Alt-drag turns the editor eye)',
+ zh: '恢复正对场景(Alt+拖拽可转动编辑器视角)',
+ },
// — Design-resolution + device-preview dropdowns (UI mode) —
'vp.designResTitle': {
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index 6b470327c..4f8e80f12 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -7,7 +7,7 @@ import {
Camera, Loader2, TriangleAlert, Lightbulb, Sparkles, Globe, Crosshair, Monitor, Magnet, Axis3d, Hexagon, MapPin, Box, type LucideIcon,
AlignStartVertical, AlignCenterVertical, AlignEndVertical,
AlignStartHorizontal, AlignCenterHorizontal, AlignEndHorizontal,
- AlignHorizontalDistributeCenter, AlignVerticalDistributeCenter,
+ AlignHorizontalDistributeCenter, AlignVerticalDistributeCenter, RotateCcw,
} from 'lucide-react';
import { t } from '@/i18n';
import { useEditorStore } from '@/store/editorStore';
@@ -736,6 +736,8 @@ export function Viewport() {
const coordSpace = useEditorStore((s) => s.coordSpace);
const pivotMode = useEditorStore((s) => s.pivotMode);
const viewPerspective = useEditorStore((s) => s.viewPerspective);
+ const viewOrbited = useEditorStore((s) => s.viewOrbited);
+ const setViewOrbited = useEditorStore((s) => s.setViewOrbited);
const snapping = useEditorStore((s) => s.snapping);
const snapStep = useEditorStore((s) => s.snapStep);
const snapAngle = useEditorStore((s) => s.snapAngle);
@@ -829,6 +831,7 @@ export function Viewport() {
// Camera pan (middle/right drag, or Space+left drag for trackpad users) is
// built-in navigation, separate from tools.
const panRef = useRef<{ px: number; py: number } | null>(null);
+ const orbitRef = useRef<{ px: number; py: number } | null>(null);
const spaceHeld = useRef(false);
const [spacePan, setSpacePan] = useState(false); // drives the grab cursor
// The tool that owns the in-progress left-button stroke (move/up route to it).
@@ -1869,7 +1872,8 @@ export function Viewport() {
activeToolRef.current.cancel?.(toolCtx);
activeToolRef.current = null;
e.stopImmediatePropagation();
- } else if (panRef.current) {
+ } else if (orbitRef.current || panRef.current) {
+ orbitRef.current = null;
panRef.current = null;
e.stopImmediatePropagation();
} else if (isTilePaintMode()) {
@@ -1909,6 +1913,16 @@ export function Viewport() {
const onPointerDown = (e: ReactPointerEvent) => {
if (engine.status !== 'ready') return;
+ // Alt + left drag = orbit the eye (the DCC convention). Checked before pan so
+ // it wins over the tools, and available in both projections: an orthographic
+ // view turned off-axis is the isometric one.
+ if (e.button === 0 && e.altKey) {
+ e.preventDefault();
+ orbitRef.current = { px: e.clientX, py: e.clientY };
+ stageRef.current?.setPointerCapture(e.pointerId);
+ return;
+ }
+
// Middle / right drag, or Space + left drag = pan the view (camera navigation,
// always available regardless of the active tool; Space-drag is the trackpad path).
if (e.button === 1 || e.button === 2 || (e.button === 0 && spaceHeld.current)) {
@@ -1934,6 +1948,13 @@ export function Viewport() {
const wp = ViewportController.canvasToWorld(e.clientX, e.clientY);
if (wp) StatsStore.setCursor(wp.x, wp.y);
+ if (orbitRef.current) {
+ ViewportController.orbitByClient(orbitRef.current.px, orbitRef.current.py, e.clientX, e.clientY);
+ orbitRef.current = { px: e.clientX, py: e.clientY };
+ setViewOrbited(ViewportController.isOrbited());
+ return;
+ }
+
if (panRef.current) {
ViewportController.panByClient(panRef.current.px, panRef.current.py, e.clientX, e.clientY);
panRef.current.px = e.clientX;
@@ -1960,6 +1981,11 @@ export function Viewport() {
};
const endDrag = (e: ReactPointerEvent) => {
+ if (orbitRef.current) {
+ stageRef.current?.releasePointerCapture(e.pointerId);
+ orbitRef.current = null;
+ return;
+ }
if (panRef.current) {
stageRef.current?.releasePointerCapture(e.pointerId);
panRef.current = null;
@@ -1974,6 +2000,11 @@ export function Viewport() {
// pointercancel (OS/gesture interruption) aborts the stroke instead of committing —
// the tool rolls back its live edits, matching Esc.
const cancelDrag = (e: ReactPointerEvent) => {
+ if (orbitRef.current) {
+ stageRef.current?.releasePointerCapture(e.pointerId);
+ orbitRef.current = null;
+ return;
+ }
if (panRef.current) {
stageRef.current?.releasePointerCapture(e.pointerId);
panRef.current = null;
@@ -2120,6 +2151,18 @@ export function Viewport() {
<Box size={13} strokeWidth={1.9} />
<span className="val">{viewPerspective ? t('vp.proj.perspective') : t('vp.proj.ortho')}</span>
</button>
+ {/* Only while the eye is turned: a 2D project never sees it, and a user
+ who turned the view by accident has the way back in front of them. */}
+ {viewOrbited && (
+ <button
+ type="button"
+ className="ovbtn"
+ title={t('vp.resetOrbitTitle')}
+ onClick={() => commands.run('view.resetOrbit')}
+ >
+ <RotateCcw size={13} strokeWidth={1.9} />
+ </button>
+ )}
{/* Screen controls — available in EVERY editor mode. Design resolution edits
the scene Canvas when present, else the project reference resolution; the
device dropdown simulates a real screen regardless of any UI layer. */}
diff --git a/desktop/src/store/editorStore.ts b/desktop/src/store/editorStore.ts
index 3fa8b616f..a7cb2ee8c 100644
--- a/desktop/src/store/editorStore.ts
+++ b/desktop/src/store/editorStore.ts
@@ -74,6 +74,9 @@ interface EditorState {
toggleCoordSpace: () => void;
/** Editor viewport projection: a perspective eye for authoring 2.5D. */
viewPerspective: boolean;
+ /** The editor eye is turned off the head-on axis — drives the reset affordance. */
+ viewOrbited: boolean;
+ setViewOrbited: (on: boolean) => void;
toggleViewPerspective: () => void;
togglePivotMode: () => void;
/** Axis of the gizmo handle currently being dragged (null = none) — drives the
@@ -203,6 +206,8 @@ export const useEditorStore = create<EditorState>((set) => ({
toggleCoordSpace: () => set((s) => ({ coordSpace: s.coordSpace === 'world' ? 'local' : 'world' })),
viewPerspective: false,
toggleViewPerspective: () => set((s) => ({ viewPerspective: !s.viewPerspective })),
+ viewOrbited: false,
+ setViewOrbited: (on) => set((s) => (s.viewOrbited === on ? s : { viewOrbited: on })),
togglePivotMode: () => set((s) => ({ pivotMode: s.pivotMode === 'center' ? 'pivot' : 'center' })),
activeGizmoAxis: null,
setActiveGizmoAxis: (activeGizmoAxis) => set({ activeGizmoAxis }),
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 4eba4d746..a2f332379 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 62,
- "experimental": 1525,
+ "experimental": 1526,
"deprecated": 3
},
- "total": 1700,
+ "total": 1701,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 6720a13d8..85e868443 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 55 beta · 1410 experimental · 3 deprecated
+Symbols: 113 public · 55 beta · 1411 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1528,6 +1528,7 @@ far: number
fov: number
isActive: boolean
near: number
+orbit: { yaw: number; pitch: number; } | undefined
orthoSize: number
pixelPerfect: boolean
priority: number
@@ -2667,9 +2668,11 @@ distance: number
fov: number
orthoSize: number
perspective: boolean
+pitch: number
uiPreviewAspect: number
x: number
y: number
+yaw: number
```
## EffectDef — interface @experimental
@@ -9539,6 +9542,11 @@ DragPlugin
(view: EditorViewData): number
```
+## editorViewIsOrbited — function @experimental
+```
+(view: EditorViewData): boolean
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 50c0285bc..65330443c 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 60 beta · 1429 experimental · 3 deprecated
+Symbols: 113 public · 60 beta · 1430 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1528,6 +1528,7 @@ far: number
fov: number
isActive: boolean
near: number
+orbit: { yaw: number; pitch: number; } | undefined
orthoSize: number
pixelPerfect: boolean
priority: number
@@ -2675,9 +2676,11 @@ distance: number
fov: number
orthoSize: number
perspective: boolean
+pitch: number
uiPreviewAspect: number
x: number
y: number
+yaw: number
```
## EffectDef — interface @experimental
@@ -9772,6 +9775,11 @@ DragPlugin
(view: EditorViewData): number
```
+## editorViewIsOrbited — function @experimental
+```
+(view: EditorViewData): boolean
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index e6ef11d40..f327f3488 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 57 beta · 1409 experimental · 3 deprecated
+Symbols: 113 public · 57 beta · 1410 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1523,6 +1523,7 @@ far: number
fov: number
isActive: boolean
near: number
+orbit: { yaw: number; pitch: number; } | undefined
orthoSize: number
pixelPerfect: boolean
priority: number
@@ -2662,9 +2663,11 @@ distance: number
fov: number
orthoSize: number
perspective: boolean
+pitch: number
uiPreviewAspect: number
x: number
y: number
+yaw: number
```
## EffectDef — interface @experimental
@@ -9534,6 +9537,11 @@ DragPlugin
(view: EditorViewData): number
```
+## editorViewIsOrbited — function @experimental
+```
+(view: EditorViewData): boolean
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index ce14d50f7..87e6635dd 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 55 beta · 1430 experimental · 3 deprecated
+Symbols: 113 public · 55 beta · 1431 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1523,6 +1523,7 @@ far: number
fov: number
isActive: boolean
near: number
+orbit: { yaw: number; pitch: number; } | undefined
orthoSize: number
pixelPerfect: boolean
priority: number
@@ -2662,9 +2663,11 @@ distance: number
fov: number
orthoSize: number
perspective: boolean
+pitch: number
uiPreviewAspect: number
x: number
y: number
+yaw: number
```
## EffectDef — interface @experimental
@@ -9784,6 +9787,11 @@ DragPlugin
(view: EditorViewData): number
```
+## editorViewIsOrbited — function @experimental
+```
+(view: EditorViewData): boolean
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 1d6ce587a..df5d67754 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 55 beta · 1420 experimental · 3 deprecated
+Symbols: 113 public · 55 beta · 1421 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1523,6 +1523,7 @@ far: number
fov: number
isActive: boolean
near: number
+orbit: { yaw: number; pitch: number; } | undefined
orthoSize: number
pixelPerfect: boolean
priority: number
@@ -2662,9 +2663,11 @@ distance: number
fov: number
orthoSize: number
perspective: boolean
+pitch: number
uiPreviewAspect: number
x: number
y: number
+yaw: number
```
## EffectDef — interface @experimental
@@ -9561,6 +9564,11 @@ DragPlugin
(view: EditorViewData): number
```
+## editorViewIsOrbited — function @experimental
+```
+(view: EditorViewData): boolean
+```
+
## emptyAnimatorController — function @experimental
```
(): AnimatorControllerDef
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 9e45f7010..38a2953f1 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -18,14 +18,14 @@ import type { Entity } from '../types';
import { UICameraInfo } from '../ui/core/ui-camera-info';
import { ProjectionType, SceneOwner, ClearFlags } from '../ecs/component';
import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY, type CanvasScale } from './uiLayoutRect';
-import { EditorView, DEFAULT_EDITOR_VIEW, type EditorViewData } from './EditorView';
+import { EditorView, DEFAULT_EDITOR_VIEW, editorViewIsOrbited, type EditorViewData } from './EditorView';
import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenScaling';
import { CameraDirector, createDirectorState, resolveMainPOV } from './CameraDirector';
import { RenderPipeline } from '../render/renderPipeline';
import { Renderer } from '../render/renderer';
import { platformNow, platformDevicePixelRatio } from '../platform';
import { SceneManager } from '../scene/sceneManager';
-import { ortho, perspective, invertViewZ, multiply, IDENTITY } from '../math/mat4';
+import { ortho, perspective, invertViewZ, invertViewOrbit, multiply, IDENTITY } from '../math/mat4';
// =============================================================================
// Camera Info
@@ -150,6 +150,9 @@ export interface CameraPOV {
y: number;
z: number;
rotation: number; // Z rotation, radians
+ /** Orbit about (x, y, z) in radians — an eye that stands off the -Z axis.
+ * Absent (the 2D case) keeps the rotation-about-Z view exactly as it was. */
+ orbit?: { yaw: number; pitch: number };
projection: number; // ProjectionType
orthoSize: number; // authored ortho half-height
fov: number;
@@ -248,7 +251,11 @@ export function buildCameraInfo(
camY = snapToPixelGrid(pov.y, worldPerPixel);
}
- const view = invertViewZ(camX, camY, pov.z, Math.cos(pov.rotation), Math.sin(pov.rotation));
+ // An orbited camera stands off the axis, so its view comes from the focus it
+ // turns around; without one the 2D path is untouched.
+ const view = pov.orbit
+ ? invertViewOrbit(camX, camY, 0, pov.orbit.yaw, pov.orbit.pitch, pov.z)
+ : invertViewZ(camX, camY, pov.z, Math.cos(pov.rotation), Math.sin(pov.rotation));
const cam = acquireCameraInfo(pool, index);
cam.entity = pov.entity;
cam.viewProjection.set(multiply(projection, view));
@@ -345,8 +352,14 @@ export function editorCameraInfo(
y: view.y,
// Perspective needs the camera to stand somewhere: it is the distance that
// makes content near or far, where orthographically nothing depends on z.
- z: view.perspective ? view.distance : 0,
+ // Orthographically nothing depends on z — except where the eye stands,
+ // which is what an orbit turns; so an orbited ortho view needs one too.
+ z: view.perspective || editorViewIsOrbited(view) ? view.distance : 0,
rotation: 0,
+ ...(editorViewIsOrbited(view)
+ ? { orbit: { yaw: (view.yaw ?? 0) * Math.PI / 180,
+ pitch: (view.pitch ?? 0) * Math.PI / 180 } }
+ : {}),
projection: view.perspective ? ProjectionType.Perspective : ProjectionType.Orthographic,
orthoSize: view.orthoSize,
fov: view.fov,
diff --git a/sdk/src/camera/EditorView.ts b/sdk/src/camera/EditorView.ts
index 50c479493..56c31e17a 100644
--- a/sdk/src/camera/EditorView.ts
+++ b/sdk/src/camera/EditorView.ts
@@ -47,6 +47,14 @@ export interface EditorViewData {
* changing the fov instead would alter the projection the user is previewing.
*/
distance: number;
+ /**
+ * Where the eye stands relative to the focus (x, y): yaw about world +Y, pitch
+ * above the xz plane, in DEGREES like `fov`. Both zero is the head-on 2D view,
+ * and every 2D projection stays exactly what it was there — orbiting is what a
+ * 3D scene needs to be looked at, not a different camera.
+ */
+ yaw: number;
+ pitch: number;
/**
* Aspect ratio the editor lays UI out against, so the editor previews how UI adapts
* on a simulated device: `> 0` fits the design resolution into this aspect (the device
@@ -59,7 +67,7 @@ export interface EditorViewData {
export const DEFAULT_EDITOR_VIEW: EditorViewData = {
active: false, x: 0, y: 0, orthoSize: 360, uiPreviewAspect: 0,
// Off by default: an existing project opens on exactly the view it always had.
- perspective: false, fov: 60, distance: 1000,
+ perspective: false, fov: 60, distance: 1000, yaw: 0, pitch: 0,
};
/**
@@ -101,3 +109,12 @@ export function setEditorViewHalfHeight(view: EditorViewData, halfH: number): vo
}
export const EditorView = defineResource<EditorViewData>({ ...DEFAULT_EDITOR_VIEW }, 'EditorView');
+
+/**
+ * True when the view is turned away from the head-on 2D one. Absent angles read
+ * as zero: a workspace saved before this existed, or a partial view an embedder
+ * hands in, is the 2D view — not an orbit by NaN.
+ */
+export function editorViewIsOrbited(view: EditorViewData): boolean {
+ return (view.yaw ?? 0) !== 0 || (view.pitch ?? 0) !== 0;
+}
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index d27d208f6..9f0b9f303 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -40,7 +40,7 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTextur
// =============================================================================
export { CameraView, CameraViewAPI } from './camera/Camera';
-export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight } from './camera/EditorView';
+export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, editorViewIsOrbited } from './camera/EditorView';
export type { EditorViewData } from './camera/EditorView';
export { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './camera/ScreenScaling';
export type { ScreenScalingData } from './camera/ScreenScaling';
diff --git a/sdk/src/math/mat4.ts b/sdk/src/math/mat4.ts
index b3987ea99..9492315c1 100644
--- a/sdk/src/math/mat4.ts
+++ b/sdk/src/math/mat4.ts
@@ -79,6 +79,54 @@ export function invertViewZ(
return m;
}
+const _orbitM = new Float32Array(16);
+
+/**
+ * The view matrix of a camera ORBITING a focus point: it stands `distance` away
+ * along the direction yaw/pitch name (radians) and looks back at the focus.
+ *
+ * At yaw = pitch = 0 this equals {@link invertViewZ} at θ = 0 for a camera at
+ * (fx, fy, fz + distance) — the 2D view is this one's special case.
+ */
+export function invertViewOrbit(
+ fx: number, fy: number, fz: number,
+ yaw: number, pitch: number, distance: number,
+): Float32Array {
+ const cp = Math.cos(pitch);
+ // The camera's own axis, pointing FROM the focus TOWARD the eye (+z of the
+ // view basis, since a camera looks down its -z).
+ const zx = Math.sin(yaw) * cp;
+ const zy = Math.sin(pitch);
+ const zz = Math.cos(yaw) * cp;
+
+ // World up is +y; at the poles it is parallel to the view axis, so the right
+ // vector is taken from the yaw alone there rather than from a zero cross.
+ let rx = zz, ry = 0, rz = -zx;
+ const rl = Math.hypot(rx, rz);
+ if (rl < 1e-6) { rx = Math.cos(yaw); ry = 0; rz = -Math.sin(yaw); }
+ else { rx /= rl; rz /= rl; }
+
+ // up = z × right (right-handed): the other order flips the world upside down,
+ // which reads as a working camera until anything is compared to the 2D view.
+ const ux = zy * rz - zz * ry;
+ const uy = zz * rx - zx * rz;
+ const uz = zx * ry - zy * rx;
+
+ const ex = fx + zx * distance;
+ const ey = fy + zy * distance;
+ const ez = fz + zz * distance;
+
+ const m = _orbitM;
+ m[0] = rx; m[1] = ux; m[2] = zx; m[3] = 0;
+ m[4] = ry; m[5] = uy; m[6] = zy; m[7] = 0;
+ m[8] = rz; m[9] = uz; m[10] = zz; m[11] = 0;
+ m[12] = -(rx * ex + ry * ey + rz * ez);
+ m[13] = -(ux * ex + uy * ey + uz * ez);
+ m[14] = -(zx * ex + zy * ey + zz * ez);
+ m[15] = 1;
+ return m;
+}
+
const _mulM = new Float32Array(16);
export function multiply(a: Float32Array, b: Float32Array): Float32Array {
diff --git a/sdk/tests/editor-view-orbit.test.ts b/sdk/tests/editor-view-orbit.test.ts
new file mode 100644
index 000000000..b1b1d1739
--- /dev/null
+++ b/sdk/tests/editor-view-orbit.test.ts
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The editor's eye, turned off the -Z axis.
+ *
+ * A 3D scene cannot be looked at head-on only, and every 2D projection has to
+ * stay exactly what it was: the head-on case is asserted matrix-for-matrix, the
+ * turned one against where a point lands.
+ */
+import { describe, expect, it } from 'vitest';
+import { invertViewZ, invertViewOrbit, multiply, perspective, ortho } from '../src/math/mat4';
+import { editorCameraInfo } from '../src/camera/CameraPlugin';
+import { DEFAULT_EDITOR_VIEW, editorViewIsOrbited } from '../src/camera/EditorView';
+import { screenToWorld, invertMatrix4 } from '../src/ui/util/math';
+
+const project = (vp: Float32Array, x: number, y: number, z: number) => {
+ const w = vp[3]! * x + vp[7]! * y + vp[11]! * z + vp[15]!;
+ return {
+ x: (vp[0]! * x + vp[4]! * y + vp[8]! * z + vp[12]!) / w,
+ y: (vp[1]! * x + vp[5]! * y + vp[9]! * z + vp[13]!) / w,
+ };
+};
+
+describe('the editor view, orbited', () => {
+ it('is the head-on view exactly when yaw and pitch are zero', () => {
+ // If these ever differ, turning the feature on moves every 2D scene.
+ // Signed zero is normalized: -0 and 0 are one entry of a matrix.
+ const cells = (m: Float32Array) => Array.from(m, v => v + 0);
+ expect(cells(invertViewOrbit(30, -40, 0, 0, 0, 500)))
+ .toEqual(cells(invertViewZ(30, -40, 500, 1, 0)));
+ });
+
+ it('puts the eye where yaw says, looking back at the focus', () => {
+ // Yaw 90° stands the eye on +X: the focus still projects to the centre,
+ // and what was to the camera's right is now nearer or further, not sideways.
+ const view = invertViewOrbit(0, 0, 0, Math.PI / 2, 0, 100);
+ const vp = multiply(perspective(Math.PI / 3, 1, 0.1, 1000), view);
+ const centre = project(vp, 0, 0, 0);
+ expect(centre.x).toBeCloseTo(0);
+ expect(centre.y).toBeCloseTo(0);
+ // A point along +Z is now to the LEFT of the eye standing on +X.
+ expect(project(vp, 0, 0, 50).x).toBeLessThan(-0.01);
+ expect(project(vp, 0, 0, -50).x).toBeGreaterThan(0.01);
+ });
+
+ it('raises the eye with pitch, keeping the focus centred', () => {
+ const view = invertViewOrbit(10, 20, 0, 0, Math.PI / 4, 200);
+ const vp = multiply(ortho(-100, 100, -100, 100, -1000, 1000), view);
+ const centre = project(vp, 10, 20, 0);
+ expect(centre.x).toBeCloseTo(0);
+ expect(centre.y).toBeCloseTo(0);
+ // Looking down at 45°, ground that is further away rides UP the screen.
+ expect(project(vp, 10, -80, 0).y).toBeLessThan(project(vp, 10, 120, 0).y);
+ });
+
+ it('carries the orbit into the camera the editor renders through', () => {
+ const view = { ...DEFAULT_EDITOR_VIEW, active: true, yaw: 90, pitch: 0 };
+ expect(editorViewIsOrbited(view)).toBe(true);
+ const cam = editorCameraInfo(view, 256, 256, []);
+ // Same claim as the matrix test, through the camera the editor builds.
+ expect(project(cam.viewProjection, 0, 0, 0).x).toBeCloseTo(0);
+ expect(project(cam.viewProjection, 0, 0, 100).x).toBeLessThan(-0.01);
+ });
+
+ it('hit-tests through the turned view: a screen point still finds z = 0', () => {
+ // Picking is a ray against the z = 0 plane, so an orbited view has to
+ // answer with the point under the cursor rather than one beside it.
+ const view = { ...DEFAULT_EDITOR_VIEW, active: true, yaw: 30, pitch: 20 };
+ const cam = editorCameraInfo(view, 256, 256, []);
+ const inv = invertMatrix4(cam.viewProjection);
+ const centre = screenToWorld(128, 128, inv, 0, 0, 256, 256, 0);
+ expect(centre.x).toBeCloseTo(view.x, 3);
+ expect(centre.y).toBeCloseTo(view.y, 3);
+ });
+});
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 17fb1aa12..dea46f44d 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -145,6 +145,10 @@ export const SCENES = [
// two triangles, so the frame says which geometry is drawn — and the hit test
// lands 120 world units out, where only the mesh's own box reaches.
{ id: "mesh-assign", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SET_FIELD: "{\"entity\":1,\"component\":\"Mesh2D\",\"key\":\"mesh\",\"value\":\"/scenes/textured-quad.esmesh\"}", ESTELLA_VERIFY_PICK: "{\"x\":0.7,\"y\":0.3833,\"entity\":1}", ESTELLA_VERIFY_SCENE: "/scenes/mesh2d.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh2d.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,255,255],\"tol\":40},{\"x\":0.30,\"y\":0.556,\"rgb\":[255,255,255],\"tol\":40}]" } },
+ // The editor's eye turned 60° about Y. Where the triangles land is arithmetic:
+ // centres at x = ±120 project to 0.40 / 0.60, with 0.30 empty. The hit test at
+ // the new place proves screen→world followed the turn.
+ { id: "view-orbit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_ORBIT: "60,0", ESTELLA_VERIFY_PICK: "{\"x\":0.40,\"y\":0.556,\"entity\":1}", ESTELLA_VERIFY_SCENE: "/scenes/mesh2d.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh2d.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.40,\"y\":0.556,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.60,\"y\":0.556,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.30,\"y\":0.556,\"rgb\":[0,0,0],\"tol\":30}]" } },
// A normal map over FLAT normals: the quad faces the viewer, so without the map
// both halves take the same light. Its texels point -X and +X, so the lit half
// and the unlit one are the tangent frame, derived per pixel from derivatives.