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(viewport): add spatial plane and center handles
yhh7c1c0f0520e0
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 6e99430aa..d327df9c7 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -728,6 +728,17 @@ jobs:path: output/gizmo-origins-ci/retention-days: 3+ - name: Check spatial transform planes and center handles+ if: matrix.shard == 1+ run: node tools/verify-gizmo-planes.mjs+ - name: Upload spatial transform acceptance evidence+ if: always() && matrix.shard == 1+ uses: actions/upload-artifact@v7+ with:+ name: gizmo-planes-editor-checks+ path: output/gizmo-planes-ci/+ retention-days: 3+# Between the two heavy steps, so the disk each one costs is attributable.# The report at the bottom cannot do that, and it is the report that dies# with the runner: a full disk takes the log that would name what filled it,diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c15aef1d9..d4ff03fab 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -28,6 +28,8 @@ published separately; it ships inside the editor.### Added+- **Spatial transform handles expose all three planes and distinct centers.** Move/scale tools offer camera-facing XY, YZ and ZX parallelograms, hiding edge-on planes and sharing their projected corners with hit tests. Spatial move uses the presented camera's screen plane, spatial scale uses one XYZ factor, and Local drags use the rotated plane normal. Head-on 2D keeps its original handle set; Universal shares the spatial move planes.+- **Universal Transform combines move, rotate and scale handles.** The viewport toolbar and Command Palette offer a combined tool on Y, preserving T for Rect. Move handles win overlaps, then outer scale boxes, then rotation rings; each drag captures one operation and highlights only its target. Scale boxes remain separate from arrow tips, and their drag sensitivity uses the captured box-arm length. Existing pivot, size, transaction and copy paths remain shared.- **Alt-copy on transform handles reaches the tool.** Camera orbit no longer consumes an Alt-left press on a visible, editable selected transform handle; the rest of the canvas retains its navigation behavior. Individual Origins starts duplicates at the originals' positions before applying rotation or scale, and CI saves intermediate observations even when a gesture check fails.diff --git a/desktop b/desktopindex e91793867..42106fb27 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit e91793867ab864a0c62462bf5cb71d01efb9ada7+Subproject commit 42106fb27c5af577e8856db3afa9e35e2db827bddiff --git a/docs/astro/src/content/docs/editor/viewport.mdx b/docs/astro/src/content/docs/editor/viewport.mdxindex 0664f7898..26b45d96d 100644--- a/docs/astro/src/content/docs/editor/viewport.mdx+++ b/docs/astro/src/content/docs/editor/viewport.mdx@@ -26,9 +26,9 @@ handle:| Tool | Shortcut | Gizmo ||---|---|---|| Select | `Q` | Pick / marquee only, no transform handles. |-| Move | `W` | Projected axis arrows plus the center handle for the most visible world plane. Head-on 2D shows X / Y. |+| Move | `W` | Projected arrows. Spatial views add XY / YZ / ZX planes and screen-plane movement at the center; head-on 2D keeps X / Y and its center plane. || Rotate | `E` | Projected axis rings; head-on 2D shows the Z ring. |-| Scale | `R` | Projected axis boxes plus a center handle that scales the visible plane's two axes. |+| Scale | `R` | Projected axis boxes. Spatial views add plane handles and XYZ uniform scaling at the center; head-on 2D keeps two-axis center scaling. || Rect | `T` | The selected sprite or UI node's own rectangle grips. || Universal Transform | `Y` | Move arrows and center plane, outer scale boxes and rotation rings together. |@@ -36,8 +36,15 @@ Universal Transform gives move handles priority over scale boxes, then rotationrings. Scale boxes sit beyond the arrow tips so they remain reachable; a dragalong one complete box-arm length doubles that axis's scale. Each press choosesone operation, which remains fixed for the entire drag. Its hover and drag-highlight affect only that operation. The separate W / E / R tools keep their-existing geometry and T remains Rect.+highlight affect only that operation. The separate W / E / R tools remain+available and T remains Rect.++Spatial plane handles turn into the quadrant facing the camera. Edge-on planes+are hidden; the same projected corners are drawn and hit-tested. A World plane+drag changes only its two named components. Local uses the rotated plane normal.+The spatial move center follows a plane parallel to the presented camera through+the selection pivot, captured at the start of the drag. Scale's spatial center+applies one factor to X, Y and Z. These gestures keep single-step undo and Esc.Hovering a transform handle highlights the handle that a press will grab. Thecursor shows moving, rotation or the projected resize direction. Camera ordiff --git a/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx b/docs/astro/src/content/docs/zh-cn/editor/viewport.mdxindex bd7cb263f..f33ebedc6 100644--- a/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx@@ -24,16 +24,22 @@ description: "视口导航、变换 gizmo、对齐与分布、显示开关、Sce| 工具 | 快捷键 | Gizmo ||---|---|---|| 选择 | `Q` | 只做拾取/框选,无变换手柄。 |-| 移动 | `W` | 投影后的轴向箭头,中心手柄操作最正对视线的世界平面;正对 2D 时显示 X / Y。 |+| 移动 | `W` | 投影后的轴向箭头;空间视角增加 XY / YZ / ZX 平面与中心屏幕平面移动,正面 2D 保留 X / Y 和中心平面。 || 旋转 | `E` | 投影后的轴向旋转环;正对 2D 时显示 Z 环。 |-| 缩放 | `R` | 投影后的轴向方块,中心手柄缩放可见平面的两轴。 |+| 缩放 | `R` | 投影后的轴向方块;空间视角增加平面手柄与中心 XYZ 等比缩放,正面 2D 保留中心两轴缩放。 || Rect | `T` | 选中精灵或 UI 节点自身的矩形手柄。 || 万能变换 | `Y` | 同时显示移动箭头与中心平面、外侧缩放方块和旋转环。 |万能变换按移动手柄、缩放方块、旋转环的顺序命中。缩放方块位于箭头外侧,保持可抓取;沿方块所在轴拖动一个完整臂长,该轴缩放加倍。每次按下只选择一种操作,并在整个拖拽期间保持;悬停和拖拽仅高亮该操作。-W / E / R 单独工具的几何保持原样,T 仍为 Rect。+W / E / R 单独工具仍可使用,T 仍为 Rect。++空间平面手柄会翻到朝向相机的象限,侧对视线的平面隐藏;绘制与命中使用+同一组投影角点。World 平面拖拽只改变对应两个分量,Local 使用旋转后的+平面法线。移动中心在经过选择轴心、平行于已呈现相机的平面上移动,+拖拽开始时固定该平面;缩放中心对 X / Y / Z 应用同一倍数。+这些操作仍是一步撤销,按 Esc 取消。悬停变换手柄会高亮实际按下时将抓到的手柄,光标显示移动、旋转或投影后的缩放方向。相机或选择变化会重新判断,离开画布即清除。导航、绘制、拾取和diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 75dcfb613..0a52146c9 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -30,6 +30,8 @@ export const NOTES_FLOOR = 'v0.65.0';export const NOTED = {'fix(animation): keep paused sprite motions out of exit transitions':{ note: 'Paused sprite motions wait for actual completion before exit transitions.' },+ 'feat(viewport): add spatial plane and center handles':+ { note: 'Spatial transform handles expose all three planes and distinct centers.' },'perf(ui): search measured list bounds and retry failed syncs':{ note: 'Measured lists locate visible items without scanning every preceding row.' },'feat(viewport): combine transform handles in a universal tool':diff --git a/tools/verify-gizmo-planes.mjs b/tools/verify-gizmo-planes.mjsnew file mode 100644index 000000000..80a693905--- /dev/null+++ b/tools/verify-gizmo-planes.mjs@@ -0,0 +1,53 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import fs from 'node:fs';+import path from 'node:path';+import assert from 'node:assert/strict';+import { fileURLToPath } from 'node:url';+import { runElectron } from './lib/electronRun.mjs';+if (!process.env.CI) throw Error('Editor acceptance runs only in CI; do not launch the local editor.');+const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..'),out=path.join(root,'output/gizmo-planes-ci');+fs.mkdirSync(out,{recursive:true});+const project=fs.mkdtempSync(path.join(out,'project-'));+fs.mkdirSync(path.join(project,'assets/scenes'),{recursive:true});fs.mkdirSync(path.join(project,'src'));+fs.writeFileSync(path.join(project,'project.esproject'),JSON.stringify({formatVersion:'1',name:'Spatial planes acceptance',defaultScene:'assets/scenes/main.esscene',spineVersion:'none'}));+fs.writeFileSync(path.join(project,'assets/scenes/main.esscene'),JSON.stringify({version:'1.0',name:'Main',entities:[{id:1,name:'Subject',parent:null,children:[],visible:true,components:[+ {type:'Transform',data:{position:{x:0,y:0,z:0}}},{type:'Sprite',data:{size:{x:60,y:60},color:{r:1,g:0,b:1,a:1}}}+]}]}));+fs.writeFileSync(path.join(project,'src/main.ts'),'export {};');fs.writeFileSync(path.join(project,'src/components.ts'),'export {};');+const read=`(()=>{const e=window.__estellaEditor;const snap=()=>{const t=e.surface.serializeScene().entities.find(v=>v.id===1).components.find(c=>c.type==='Transform').data;return {position:t.position??{x:0,y:0,z:0},scale:t.scale??{x:1,y:1,z:1},rotation:t.rotation??{x:0,y:0,z:0,w:1}};};const pose=snap(),layout=e.gizmoLayout();if(!window.__planesRead){window.__planesRead=true;return {pose,layout};}e.surface.undo();return {pose,layout,undone:snap()};})()`;+const records=[];+try{+ for(const axis of ['xy','yz','zx','view','xyz']){+ const mode=axis==='xyz'?'scale':'move';+ const point=`(()=>{const g=window.__estellaEditor.gizmoLayout();if(!g?.spatial)throw Error('Missing spatial frame');${axis==='view'||axis==='xyz'?'return g.screen;':`const p=g.planes.find(p=>p.axis==='${axis}');if(!p)throw Error('Missing ${axis} plane');return {x:g.screen.x+p.corners.reduce((n,p)=>n+p.x,0)/4,y:g.screen.y+p.corners.reduce((n,p)=>n+p.y,0)/4};`}})()`;+ const run=runElectron(['.'],{via:'npx',encoding:'utf8',cwd:path.join(root,'desktop'),timeout:180000,env:{+ ESTELLA_SHOT:path.join(out,axis+'.png'),ESTELLA_SHOT_PROJECT:project,ESTELLA_SHOT_SCENE:'assets/scenes/main.esscene',+ ESTELLA_SHOT_EVAL:`(async()=>{const e=window.__estellaEditor;e.runCommand('mode.scene');e.surface.setViewPerspective(true);e.surface.setViewOrbit(45,30);e.surface.select(1);e.frame([1]);await new Promise(r=>setTimeout(r,750));e.runCommand('tool.${mode}');return true;})()`,+ ESTELLA_SHOT_EDITOR_DRAG:JSON.stringify({selector:'.viewport__stage canvas',point,dx:axis==='xyz'?58:11,dy:axis==='xyz'?0:7,read})}});+ assert.equal(run.status,0,run.stderr);const line=run.stdout.split('\n').find(l=>l.startsWith('[editorDrag] '));assert(line,'Missing trusted spatial drag');+ const result=JSON.parse(line.slice('[editorDrag] '.length));records.push({axis,...result});+ fs.writeFileSync(path.join(out,'observations.json'),JSON.stringify({status:'checking',records},null,2));+ const before=result.before.pose,after=result.after.pose;+ assert.deepEqual(result.after.undone,before,'Single undo did not restore the pose');+ assert.deepEqual(after.rotation,before.rotation,'Plane drag also rotated the subject');+ if(axis==='xyz'){+ assert.deepEqual(after.position,before.position);const s=after.scale;+ assert(s.x>1.8&&s.x<2.2,'Uniform scale missed its center handle');+ assert(Math.abs(s.x-s.y)<1e-6&&Math.abs(s.y-s.z)<1e-6,'Spatial center did not scale XYZ equally');+ }else{+ assert.deepEqual(after.scale,before.scale);const delta={x:after.position.x-before.position.x,y:after.position.y-before.position.y,z:after.position.z-before.position.z};+ if(axis==='view'){+ const n=result.before.layout.normal;assert(n,'Missing committed view normal');+ assert(Math.abs(delta.x*n.x+delta.y*n.y+delta.z*n.z)<1e-4,'Free move left the screen plane');+ assert(Math.hypot(delta.x,delta.y,delta.z)>1e-4,'Free move did nothing');+ }else for(const a of ['x','y','z']){+ if(axis.includes(a))assert(Math.abs(delta[a])>1e-4,axis+' failed to move '+a);+ else assert(Math.abs(delta[a])<1e-4,axis+' changed its constrained '+a);+ }+ }+ assert(fs.existsSync(path.join(out,axis+'.png')),'Missing restored-pose screenshot');+ }+ fs.writeFileSync(path.join(out,'checks.json'),JSON.stringify({status:'checks-passed',records},null,2));+ console.log('Spatial gizmos: XY/YZ/ZX, screen movement, XYZ scale and single-step undo pass');+}finally{if(!project.startsWith(out+path.sep))throw Error('Unexpected cleanup path');fs.rmSync(project,{recursive:true,force:true,maxRetries:10,retryDelay:50});}