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(viewport): highlight transform handles under the pointer

yhh8d8bce1afbad
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 3a79cbbef..6157d4461 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -706,6 +706,17 @@ jobs:
ESTELLA_MCP_EDITOR_VISIBLE: '1'
run: xvfb-run -a --server-args="-screen 0 1920x1080x24" node scripts/editor-checks/run.mjs --shard ${{ matrix.shard }}/4 || [ $? -eq 2 ]
+ - name: Check trusted transform-handle hover and unchanged scene
+ if: matrix.shard == 1
+ run: node tools/verify-gizmo-hover.mjs
+ - name: Upload transform-handle hover evidence
+ if: always() && matrix.shard == 1
+ uses: actions/upload-artifact@v7
+ with:
+ name: gizmo-hover-editor-checks
+ path: output/gizmo-hover-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.md
index 0aa98de72..4efad801f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Added
+- **Transform handles preview the pointer's target before a drag.** Move/scale axes, the center plane and rotation rings use the same hit decision for hovering and pressing. Hover uses the drag highlight and projected resize cursor; it follows camera and selection changes, clears outside the canvas, and yields to navigation, paint, picking and contributed tools. Hover does not edit scene data. Real editor pointer and screenshot acceptance runs in CI.
+
- **The WeChat starter's publishing profile minifies its game bundle.** The named WeChat profile uses Shipping settings while Web authoring uses Development settings. Both preserve gameplay and host-service behavior. Headless observations record scene-initialization timing separately from actual device cold startup; unchanged-scene bundle comparisons measure the byte savings.
- **The WeChat Mini Game starter combines gameplay and host-service examples.** A CC0 fleet game includes honest login-code/server-exchange status, sharing without false completion rewards, opt-in configured rewarded video and device-local credit restoration. Unreadable or changed saves are preserved. Named Web/WeChat profiles, compressed engine subpackaging, licenses and a creation-to-submission guide are included; real accounts, server authentication and device/platform approval remain separate.
diff --git a/desktop b/desktop
index a129ea9ad..ba1464189 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit a129ea9add5c70029afc08beee174d3d51403fa6
+Subproject commit ba1464189bdbdf445a0d66498749e606b8aa42d4
diff --git a/docs/astro/src/content/docs/editor/shortcuts.mdx b/docs/astro/src/content/docs/editor/shortcuts.mdx
index d7d42803e..07d2702b7 100644
--- a/docs/astro/src/content/docs/editor/shortcuts.mdx
+++ b/docs/astro/src/content/docs/editor/shortcuts.mdx
@@ -19,7 +19,7 @@ Settings → Keyboard Shortcuts.
| Copy / Cut / Paste | `mod + C` / `mod + X` / `mod + V` |
| Delete | `Delete` / `Backspace` |
| Select All | `mod + A` |
-| Select / Move / Rotate / Scale tool | `Q` / `W` / `E` / `R` |
+| Select / Move / Rotate / Scale / Rect tool | `Q` / `W` / `E` / `R` / `T` |
| Nudge selection (×10 with Shift) | Arrow keys |
| Frame Selected | `F` |
| Play · Stop | `F5` · `Esc` |
diff --git a/docs/astro/src/content/docs/editor/viewport.mdx b/docs/astro/src/content/docs/editor/viewport.mdx
index ecc4d28fb..182c19041 100644
--- a/docs/astro/src/content/docs/editor/viewport.mdx
+++ b/docs/astro/src/content/docs/editor/viewport.mdx
@@ -26,9 +26,16 @@ handle:
| Tool | Shortcut | Gizmo |
|---|---|---|
| Select | `Q` | Pick / marquee only, no transform handles. |
-| Move | `W` | Axis arrows (X / Y) plus a center plane for free move. |
-| Rotate | `E` | A rotation ring. |
-| Scale | `R` | Axis boxes plus a uniform-scale center. |
+| Move | `W` | Projected axis arrows plus the center handle for the most visible world plane. Head-on 2D shows X / Y. |
+| 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. |
+| Rect | `T` | The selected sprite or UI node's own rectangle grips. |
+
+Hovering a transform handle highlights the handle that a press will grab. The
+cursor shows moving, rotation or the projected resize direction. Camera or
+selection changes recompute the target; leaving the canvas clears it. Navigation,
+paint, picking and contributed tools keep their own pointer routing. Hover alone
+does not change transforms or begin an undo transaction.
Dragging a handle transforms the whole selection as one, about a shared pivot, and
each drag is a single undo step. **Alt-drag** a selection to duplicate it and drag the
diff --git a/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx b/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx
index f59f35bfd..ca28e8f5d 100644
--- a/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx
+++ b/docs/astro/src/content/docs/zh-cn/editor/shortcuts.mdx
@@ -18,7 +18,7 @@ import { Aside } from '@astrojs/starlight/components';
| 拷贝 / 剪切 / 粘贴 | `mod + C` / `mod + X` / `mod + V` |
| 删除 | `Delete` / `Backspace` |
| 全选 | `mod + A` |
-| 选择 / 移动 / 旋转 / 缩放 工具 | `Q` / `W` / `E` / `R` |
+| 选择 / 移动 / 旋转 / 缩放 / Rect 工具 | `Q` / `W` / `E` / `R` / `T` |
| 微移选择(按 Shift ×10) | 方向键 |
| 聚焦选中 | `F` |
| 运行 · 停止 | `F5` · `Esc` |
diff --git a/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx b/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx
index 9c9629bdb..6b0bdd0c2 100644
--- a/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx
+++ b/docs/astro/src/content/docs/zh-cn/editor/viewport.mdx
@@ -24,9 +24,14 @@ description: "视口导航、变换 gizmo、对齐与分布、显示开关、Sce
| 工具 | 快捷键 | Gizmo |
|---|---|---|
| 选择 | `Q` | 只做拾取/框选,无变换手柄。 |
-| 移动 | `W` | 轴向箭头(X / Y)加一个自由移动的中心面。 |
-| 旋转 | `E` | 一个旋转环。 |
-| 缩放 | `R` | 轴向方块加一个等比缩放中心。 |
+| 移动 | `W` | 投影后的轴向箭头,中心手柄操作最正对视线的世界平面;正对 2D 时显示 X / Y。 |
+| 旋转 | `E` | 投影后的轴向旋转环;正对 2D 时显示 Z 环。 |
+| 缩放 | `R` | 投影后的轴向方块,中心手柄缩放可见平面的两轴。 |
+| Rect | `T` | 选中精灵或 UI 节点自身的矩形手柄。 |
+
+悬停变换手柄会高亮实际按下时将抓到的手柄,光标显示移动、旋转或投影后的
+缩放方向。相机或选择变化会重新判断,离开画布即清除。导航、绘制、拾取和
+贡献工具保留自己的指针路由;仅悬停不会修改变换或开启撤销事务。
拖动手柄会把整个选择当作一体、绕共享轴心变换,每次拖动是一步撤销。**Alt 拖动**选择可复制它并
拖动副本。用**方向键**微移选择(一格;按 **Shift** 为 ×10)。
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 867afeeb8..665aa0bd5 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(viewport): highlight transform handles under the pointer':
+ { note: "Transform handles preview the pointer's target before a drag." },
'fix(checks): report non-TypeScript example failures':
{ internal: 'Example validation reports filesystem and process failures instead of dropping all non-TS diagnostics.' },
'perf(templates): minify the WeChat publishing profile':
diff --git a/tools/verify-gizmo-hover.mjs b/tools/verify-gizmo-hover.mjs
new file mode 100644
index 000000000..2f6ae8d06
--- /dev/null
+++ b/tools/verify-gizmo-hover.mjs
@@ -0,0 +1,24 @@
+// 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 {fileURLToPath} from 'node:url';import assert from 'node:assert/strict';import {runElectron} from './lib/electronRun.mjs';
+if(!process.env.CI)throw Error('This editor acceptance check runs only in CI; local verification must not launch the editor.');
+const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..'),out=path.join(root,'output/gizmo-hover-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:'Hover 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 records=[];
+const read="(() => { const s=document.querySelector('.viewport__stage'); return {hover:s?.dataset.gizmoHover,cursor:s?.style.cursor,scene:JSON.stringify(window.__estellaEditor.surface.serializeScene())}; })()";
+try{
+ for(const c of [{mode:'move',x:30,y:0,id:'move.x',cursor:'move'},{mode:'scale',x:30,y:0,id:'scale.x',cursor:'ew-resize'},{mode:'rotate',x:42,y:0,id:'rotate.z',cursor:'grab'}]){
+ const run=runElectron(['.'],{via:'npx',encoding:'utf8',cwd:path.join(root,'desktop'),timeout:180000,env:{
+ ESTELLA_SHOT:path.join(out,c.mode+'.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.runCommand('view.resetOrbit');e.surface.setGizmoDisplay({show:true,selectedOnly:true,iconSize:16,types:{}});e.surface.select(1);e.frame([1]);await new Promise(resolve=>setTimeout(resolve,750));e.runCommand('tool.${c.mode}');return true;})()`,
+ ESTELLA_SHOT_EDITOR_DRAG:JSON.stringify({selector:'.viewport__stage canvas',ox:c.x,oy:c.y,steps:1,hoverOnly:true,read})}});
+ assert.equal(run.status,0,run.stderr);const line=run.stdout.split('\n').find(line=>line.startsWith('[editorDrag] '));assert(line,'Missing trusted hover observation');
+ const result=JSON.parse(line.slice('[editorDrag] '.length));assert.equal(result.after.hover,c.id);assert.equal(result.after.cursor,c.cursor);assert.equal(result.after.scene,result.before.scene,'Hover edited the scene');
+ assert(fs.existsSync(path.join(out,c.mode+'.png')),'Missing editor screenshot');records.push({mode:c.mode,...result});
+ }
+ fs.writeFileSync(path.join(out,'checks.json'),JSON.stringify({status:'checks-passed',mode:'CI-editor-trusted-hover',records},null,2));
+ console.log('Gizmo hover CI: move/scale/rotate preselection and cursors pass; scene unchanged');
+}finally{if(!project.startsWith(out+path.sep))throw Error('Unexpected cleanup root');fs.rmSync(project,{recursive:true,force:true,maxRetries:10,retryDelay:50});}