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): an arrow key moves the way it points, on the plane being worked

esenginedeeb0ab22bd6
diff --git a/desktop/src/commands/editorCommands.ts b/desktop/src/commands/editorCommands.ts
index 77dbfe926..0754fd9ba 100644
--- a/desktop/src/commands/editorCommands.ts
+++ b/desktop/src/commands/editorCommands.ts
@@ -308,17 +308,19 @@ for (const m of EDITOR_MODES) {
}
// — Keyboard nudge — arrow keys move the selection by one grid step (Shift = ×10),
-// world +Y is up so ArrowUp adds to Y. One undo step; the Outliner stops arrows from
-// reaching here while it's focused (tree nav owns them there).
+// on the plane the view works on and the way the key points; head-on that is the
+// +X / +Y 2D nudge. One undo step; the Outliner stops arrows from reaching here
+// while it's focused (tree nav owns them there).
function nudgeSelection(ux: number, uy: number, big: boolean): void {
const ids = [...sel().selectedIds];
if (!ids.length) return;
const step = editor().snapStep * (big ? 10 : 1);
+ const d = ViewportController.nudgeVector(ux * step, uy * step);
SceneCommands.transact('Nudge', () => {
for (const sid of ids) {
const rt = SceneModel.runtimeFor(sid);
const pos = rt != null ? ViewportController.getEntityWorldPos(rt) : null;
- if (pos) SceneCommands.setEntityWorldPos(sid, pos.x + ux * step, pos.y + uy * step);
+ if (pos) SceneCommands.setEntityWorldPos(sid, pos.x + d.x, pos.y + d.y, pos.z + d.z);
}
});
}
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index e82bcc3f2..217646454 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -19,7 +19,7 @@ import {
pickEntitiesByRay, editorViewIsOrbited,
moveEditorViewFocus, editorViewBoxExtent,
editorViewAxes, editorViewAxisAngles, cameraFrustumCorners, type ScreenAxis,
- editorViewWorkPlane, worldAxisVector,
+ editorViewWorkPlane, screenNudgeAxes, worldAxisVector,
lightAimOf,
rayPlaneHit, type WorldRay, type Vec3,
type TilesetModel, type TileCollisionPiece, type TileGridParams,
@@ -233,6 +233,25 @@ export const ViewportController = {
return ray ? rayPlaneHit(ray, point, normal) : null;
},
+ /**
+ * What a nudge of `right` / `up` (world units, as the screen sees them) means in
+ * the world: the work plane's two axes, oriented so the thing moves the way the
+ * arrow points. Head-on this is the +X / +Y nudge the 2D editor always had.
+ */
+ nudgeVector(right: number, up: number): Vec3 {
+ const view = editorView();
+ if (!view) return { x: right, y: up, z: 0 };
+ const n = screenNudgeAxes(view);
+ const out = { x: 0, y: 0, z: 0 };
+ for (const [a, amount] of [[n.right, right], [n.up, up]] as const) {
+ const v = worldAxisVector(a.axis);
+ out.x += v.x * a.sign * amount;
+ out.y += v.y * a.sign * amount;
+ out.z += v.z * a.sign * amount;
+ }
+ return out;
+ },
+
/** The two world axes the view's work plane runs in, as their letters — what a
* coordinate readout on that plane is naming. */
workPlaneAxes(): [string, string] {
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index f69e2560c..c2212b86c 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -1365,8 +1365,12 @@ export function Viewport() {
// Show the design/device overlay in UI mode (design frame always) OR in any mode
// once a real device is picked — reading the project design resolution when the
// scene has no Canvas, so a gameplay scene previews on devices without a UI layer.
+ // Not from a turned eye: it is all screen rects on the 2D plane, and only a
+ // head-on view projects that plane to a rect — perspective head-on still does,
+ // so what this asks about is the eye and not the projection.
const ms0 = useEditorMode.getState();
- const ci = ready && showG && (activeModeOverlays().designFrame || ms0.device !== 'design')
+ const ci = ready && showG && !ViewportController.isOrbited()
+ && (activeModeOverlays().designFrame || ms0.device !== 'design')
? ViewportController.screenInfo()
: null;
// The design frame lives in the UI world scale: 1 unit = 1 design px (the invariant
diff --git a/desktop/tests/viewport-navigation.test.ts b/desktop/tests/viewport-navigation.test.ts
index 4c825f164..9ef2b6ac2 100644
--- a/desktop/tests/viewport-navigation.test.ts
+++ b/desktop/tests/viewport-navigation.test.ts
@@ -141,3 +141,33 @@ describe('the plane the view authors on', () => {
expect(ViewportController.workPlaneAxes()).toEqual(['x', 'z']);
});
});
+
+describe('the arrow-key nudge', () => {
+ it('is +X right and +Y up head-on, which is the 2D nudge', () => {
+ host.view = view({});
+ const d = ViewportController.nudgeVector(10, 4);
+ expect(d.x).toBeCloseTo(10, 6);
+ expect(d.y).toBeCloseTo(4, 6);
+ expect(d.z).toBeCloseTo(0, 6);
+ });
+
+ // From straight above, world +Y is the axis the eye looks down: adding to it
+ // lifts the thing off the ground instead of sliding it up the screen.
+ it('slides over the ground from a top-down eye', () => {
+ host.view = perspectiveView({ pitch: 90 });
+ const d = ViewportController.nudgeVector(10, 4);
+ expect(d.y).toBeCloseTo(0, 6);
+ expect(d.x).toBeCloseTo(10, 6);
+ expect(d.z).toBeCloseTo(-4, 6);
+ });
+
+ // Turned a quarter turn about Y, screen-right is world Z and the ground's other
+ // axis takes the vertical key — never the same axis twice.
+ it('follows the eye round, and never names one axis twice', () => {
+ host.view = perspectiveView({ yaw: 90, pitch: 45 });
+ const d = ViewportController.nudgeVector(10, 4);
+ expect(d.y).toBeCloseTo(0, 6);
+ expect(Math.abs(d.z)).toBeCloseTo(10, 6);
+ expect(Math.abs(d.x)).toBeCloseTo(4, 6);
+ });
+});
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index fdbf09416..b4ffe6cdd 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": 73,
- "experimental": 1591,
+ "experimental": 1592,
"deprecated": 3
},
- "total": 1777,
+ "total": 1778,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 23bfe70fd..7bacd0ab4 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 · 66 beta · 1477 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1478 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -11511,6 +11511,11 @@ Plugin
(name: string): string
```
+## screenNudgeAxes — function @experimental
+```
+(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }
+```
+
## screenRay — function @experimental
```
(screenX: number, screenY: number, inverseVP: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): WorldRay
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 9dd14db56..61a455649 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 · 71 beta · 1496 experimental · 3 deprecated
+Symbols: 113 public · 71 beta · 1497 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -11754,6 +11754,11 @@ Plugin
(name: string): string
```
+## screenNudgeAxes — function @experimental
+```
+(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }
+```
+
## screenRay — function @experimental
```
(screenX: number, screenY: number, inverseVP: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): WorldRay
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index b9a581399..43bb96460 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 · 68 beta · 1476 experimental · 3 deprecated
+Symbols: 113 public · 68 beta · 1477 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -11516,6 +11516,11 @@ Plugin
(name: string): string
```
+## screenNudgeAxes — function @experimental
+```
+(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }
+```
+
## screenRay — function @experimental
```
(screenX: number, screenY: number, inverseVP: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): WorldRay
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 56afd54b9..f9a3587f2 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 · 66 beta · 1497 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1498 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -11766,6 +11766,11 @@ Plugin
(name: string): string
```
+## screenNudgeAxes — function @experimental
+```
+(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }
+```
+
## screenRay — function @experimental
```
(screenX: number, screenY: number, inverseVP: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): WorldRay
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index a2c595665..a635ec9f4 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 · 66 beta · 1487 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1488 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -11538,6 +11538,11 @@ Plugin
(name: string): string
```
+## screenNudgeAxes — function @experimental
+```
+(view: EditorViewData): { right: { axis: WorldAxis; sign: number; }; up: { axis: WorldAxis; sign: number; }; }
+```
+
## screenRay — function @experimental
```
(screenX: number, screenY: number, inverseVP: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): WorldRay
diff --git a/sdk/src/camera/EditorView.ts b/sdk/src/camera/EditorView.ts
index 1b65665f3..1894c37eb 100644
--- a/sdk/src/camera/EditorView.ts
+++ b/sdk/src/camera/EditorView.ts
@@ -243,6 +243,36 @@ export function editorViewWorkPlane(view: EditorViewData): EditorWorkPlane {
return view.perspective ? { u: 0, v: 2, normal: 1 } : { u: 0, v: 1, normal: 2 };
}
+/**
+ * The work-plane axis a screen direction names, with the sign pointing that way —
+ * what an arrow key nudges along. `right` resolves first and `up` takes the plane's
+ * other axis, so the pair is never one axis twice. Head-on: +X right, +Y up.
+ */
+export function screenNudgeAxes(
+ view: EditorViewData,
+): { right: { axis: WorldAxis; sign: number }; up: { axis: WorldAxis; sign: number } } {
+ const plane = editorViewWorkPlane(view);
+ const screen = editorViewAxes(view);
+ const of = (a: WorldAxis): ScreenAxis => (a === 0 ? screen.x : a === 1 ? screen.y : screen.z);
+ // Screen y runs down, so pointing up the screen is a negative dy.
+ const score = (a: WorldAxis, sign: number, dir: 'right' | 'up'): number =>
+ sign * (dir === 'right' ? of(a).dx : -of(a).dy);
+ const best = (axes: WorldAxis[], dir: 'right' | 'up'): { axis: WorldAxis; sign: number } => {
+ let out = { axis: axes[0]!, sign: 1 };
+ let top = -Infinity;
+ for (const a of axes) {
+ for (const sign of [1, -1]) {
+ const v = score(a, sign, dir);
+ if (v > top) { top = v; out = { axis: a, sign }; }
+ }
+ }
+ return out;
+ };
+ const right = best([plane.u, plane.v], 'right');
+ const up = best([plane.u, plane.v].filter((a) => a !== right.axis), 'up');
+ return { right, up };
+}
+
/** A world axis as a unit vector. */
export function worldAxisVector(axis: WorldAxis): Vec3 {
return { x: axis === 0 ? 1 : 0, y: axis === 1 ? 1 : 0, z: axis === 2 ? 1 : 0 };
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index dd7461a8c..7d57873ef 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -42,7 +42,7 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTextur
// =============================================================================
export { CameraView, CameraViewAPI } from './camera/Camera';
-export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewBasis, editorViewEye, editorViewStandoff, editorViewWorkPlane, worldAxisVector, moveEditorViewFocus, editorViewBoxExtent } from './camera/EditorView';
+export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewBasis, editorViewEye, editorViewStandoff, editorViewWorkPlane, screenNudgeAxes, worldAxisVector, moveEditorViewFocus, editorViewBoxExtent } from './camera/EditorView';
export type { EditorViewData, ScreenAxis, EditorViewBasis, EditorWorkPlane, WorldAxis } from './camera/EditorView';
export { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './camera/ScreenScaling';
export type { ScreenScalingData } from './camera/ScreenScaling';