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
feat(editor): the editor's eye can turn
esengine9b4941f8d7e9
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 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.tsindex 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.tsindex 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.tsindex 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 independentdiff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.tsindex 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.tsindex 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.tsindex 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.tsxindex 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 editsthe scene Canvas when present, else the project reference resolution; thedevice dropdown simulates a real screen regardless of any UI layer. */}diff --git a/desktop/src/store/editorStore.ts b/desktop/src/store/editorStore.tsindex 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.jsonindex 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.mdindex 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: numberfov: numberisActive: booleannear: number+orbit: { yaw: number; pitch: number; } | undefinedorthoSize: numberpixelPerfect: booleanpriority: number@@ -2667,9 +2668,11 @@ distance: numberfov: numberorthoSize: numberperspective: boolean+pitch: numberuiPreviewAspect: numberx: numbery: number+yaw: number```## EffectDef — interface @experimental@@ -9539,6 +9542,11 @@ DragPlugin(view: EditorViewData): number```+## editorViewIsOrbited — function @experimental+```+(view: EditorViewData): boolean+```+## emptyAnimatorController — function @experimental```(): AnimatorControllerDefdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: numberfov: numberisActive: booleannear: number+orbit: { yaw: number; pitch: number; } | undefinedorthoSize: numberpixelPerfect: booleanpriority: number@@ -2675,9 +2676,11 @@ distance: numberfov: numberorthoSize: numberperspective: boolean+pitch: numberuiPreviewAspect: numberx: numbery: number+yaw: number```## EffectDef — interface @experimental@@ -9772,6 +9775,11 @@ DragPlugin(view: EditorViewData): number```+## editorViewIsOrbited — function @experimental+```+(view: EditorViewData): boolean+```+## emptyAnimatorController — function @experimental```(): AnimatorControllerDefdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: numberfov: numberisActive: booleannear: number+orbit: { yaw: number; pitch: number; } | undefinedorthoSize: numberpixelPerfect: booleanpriority: number@@ -2662,9 +2663,11 @@ distance: numberfov: numberorthoSize: numberperspective: boolean+pitch: numberuiPreviewAspect: numberx: numbery: number+yaw: number```## EffectDef — interface @experimental@@ -9534,6 +9537,11 @@ DragPlugin(view: EditorViewData): number```+## editorViewIsOrbited — function @experimental+```+(view: EditorViewData): boolean+```+## emptyAnimatorController — function @experimental```(): AnimatorControllerDefdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: numberfov: numberisActive: booleannear: number+orbit: { yaw: number; pitch: number; } | undefinedorthoSize: numberpixelPerfect: booleanpriority: number@@ -2662,9 +2663,11 @@ distance: numberfov: numberorthoSize: numberperspective: boolean+pitch: numberuiPreviewAspect: numberx: numbery: number+yaw: number```## EffectDef — interface @experimental@@ -9784,6 +9787,11 @@ DragPlugin(view: EditorViewData): number```+## editorViewIsOrbited — function @experimental+```+(view: EditorViewData): boolean+```+## emptyAnimatorController — function @experimental```(): AnimatorControllerDefdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: numberfov: numberisActive: booleannear: number+orbit: { yaw: number; pitch: number; } | undefinedorthoSize: numberpixelPerfect: booleanpriority: number@@ -2662,9 +2663,11 @@ distance: numberfov: numberorthoSize: numberperspective: boolean+pitch: numberuiPreviewAspect: numberx: numbery: number+yaw: number```## EffectDef — interface @experimental@@ -9561,6 +9564,11 @@ DragPlugin(view: EditorViewData): number```+## editorViewIsOrbited — function @experimental+```+(view: EditorViewData): boolean+```+## emptyAnimatorController — function @experimental```(): AnimatorControllerDefdiff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 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; // ProjectionTypeorthoSize: number; // authored ortho half-heightfov: 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mjsindex 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.