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
fix(editor): a locked entity has no handles, so the viewport can't move it
yhhb0a1f70a0739
diff --git a/desktop/src/engine/SceneModel.ts b/desktop/src/engine/SceneModel.tsindex a6e8e741c..1c8d8ecc4 100644--- a/desktop/src/engine/SceneModel.ts+++ b/desktop/src/engine/SceneModel.ts@@ -379,13 +379,27 @@ export class SceneModelImpl {return !!e && isEnvironmentEntity(e);}- /** Whether the viewport may grab an entity: not locked, not editor-hidden, and not- * environment. One predicate so click, marquee, and UI picking cannot drift apart.- * An id the model doesn't know (an engine-owned helper entity) stays grabbable. */- isPickable(sourceId: number): boolean {- const e = this.entityBySource(sourceId) as (SceneEntity & { hidden?: boolean; locked?: boolean }) | undefined;+ /**+ * Whether the viewport may WRITE an entity: not locked, not environment. The+ * gate for every viewport gesture that edits — the transform gizmo and the+ * free body drag — so a lock means what it says however the entity got+ * selected (a viewport click, the outliner, a marquee, Select All).+ *+ * Visibility deliberately does NOT gate this: hiding is about the eye, and a+ * hidden entity's gizmo is still where the user put it. Locking is the "don't+ * touch this" flag, and it is the one that stops a write.+ */+ isEditable(sourceId: number): boolean {+ const e = this.entityBySource(sourceId) as (SceneEntity & { locked?: boolean }) | undefined;if (!e) return true;- return !e.locked && !e.hidden && !isEnvironmentEntity(e);+ return !e.locked && !isEnvironmentEntity(e);+ }++ /** Whether the viewport may grab an entity: editable AND not editor-hidden. One+ * predicate so click, marquee, and UI picking cannot drift apart. An id the+ * model doesn't know (an engine-owned helper entity) stays grabbable. */+ isPickable(sourceId: number): boolean {+ return this.isEditable(sourceId) && !this.isHidden(sourceId);}// ── Sibling order (outliner drag-reorder; render order = `data.entities` order) ──diff --git a/desktop/src/i18n/messages/viewport.ts b/desktop/src/i18n/messages/viewport.tsindex 9cd34cfc5..3e0598e41 100644--- a/desktop/src/i18n/messages/viewport.ts+++ b/desktop/src/i18n/messages/viewport.ts@@ -158,4 +158,8 @@ export const viewportMessages = defineMessages({en: 'This UI node is Relative (flow-positioned) — set Position to Absolute to move it freely.',zh: '此 UI 节点为相对定位(随布局流动)——将“位置”设为“绝对定位”后才能自由移动。',},+ 'vp.lockedHint': {+ en: 'Locked entities aren’t moved by the viewport — unlock them in the World Outliner.',+ zh: '锁定的实体不会被视口移动——请在世界大纲中解锁。',+ },});diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsxindex 5a5cae93a..71cd22946 100644--- a/desktop/src/panels/Viewport.tsx+++ b/desktop/src/panels/Viewport.tsx@@ -1076,7 +1076,12 @@ export function Viewport() {const uig = uiGizmoRef.current;if (uig) {const pid = useSelection.getState().selectedId;- const prt = ready && pid != null && selIds.length === 1 ? SceneModel.runtimeFor(pid) : undefined;+ // A locked node gets no resize handles either — same gate as the transform+ // gizmo, so one lock silences every viewport handle the selection has.+ const editable = pid != null && SceneModel.isEditable(pid);+ const prt = ready && pid != null && editable && selIds.length === 1+ ? SceneModel.runtimeFor(pid)+ : undefined;const uir = prt != null && EngineHost.world?.has(prt, UINode) ? ViewportController.getEntityScreenRect(prt) : null;if (uir && showG) {uig.style.transform = `translate(${uir.x}px, ${uir.y}px)`;diff --git a/desktop/src/tools/transformTools.ts b/desktop/src/tools/transformTools.tsindex e423c8b9b..8826d0ba7 100644--- a/desktop/src/tools/transformTools.ts+++ b/desktop/src/tools/transformTools.ts@@ -136,9 +136,34 @@ export function isOrphanUINode(sourceId: EntityId): boolean {let flowHintAt = 0;let canvasHintAt = 0;+let lockHintAt = 0;++/**+ * The subset of a selection the viewport may transform: locked (and environment)+ * entities are dropped.+ *+ * This is the whole of what a lock does to a gesture, and it sits here because+ * both halves of the gizmo read it — the tool, to decide what a drag writes, and+ * the viewport, to place (or hide) the gizmo. Picking already refuses a locked+ * entity, but the outliner selects one happily, and until this existed the gizmo+ * that appeared for it dragged like any other: the lock stopped the click and+ * nothing else. A locked entity can still be selected and inspected (that is how+ * you unlock it) — it just has no handles, so the viewport reads the space it+ * occupies as empty.+ */+export function transformableIds(ids: readonly EntityId[]): EntityId[] {+ return ids.filter((id) => SceneModel.isEditable(id));+}function captureTargets(ids: readonly EntityId[], kind: Kind = 'move'): Target[] {- let kept = pruneDescendants(ids);+ const pruned = pruneDescendants(ids);+ let kept = transformableIds(pruned);+ // Say so once per burst when a lock is what swallowed part of the gesture —+ // otherwise dragging a mixed selection looks like the editor lost some of it.+ if (kept.length < pruned.length && Date.now() - lockHintAt > 4000) {+ lockHintAt = Date.now();+ Toasts.push(t('vp.lockedHint'), 'info');+ }if (kind === 'move') {// A UI element with no Canvas has no layout box — it can't be positioned at all.// Exclude it and point to the fix (the inspector's "Place under a Canvas").@@ -193,34 +218,41 @@ function primaryRotationRad(ids: readonly EntityId[]): number {/*** The gizmo pivot for the current `pivotMode`: the active entity's own position* ('pivot'), else the selection centroid ('center'). Shared by the tool and the- * viewport's gizmo placement so both agree.+ * viewport's gizmo placement so both agree — including on there being no gizmo at+ * all when nothing in the selection may be transformed (an all-locked selection+ * returns null, which reads as "no handles" at both ends).*/export function selectionPivot(ids: readonly EntityId[]): Pt | null {+ const editable = transformableIds(ids);+ if (editable.length === 0) return null;if (useEditorStore.getState().pivotMode === 'pivot') {- const id = primaryOf(ids);+ const id = primaryOf(editable);const rt = id != null ? SceneModel.runtimeFor(id) : null;const pos = rt != null ? ViewportController.getEntityWorldXY(rt) : null;if (pos) return pos;}- return pivotOf(ids);+ return pivotOf(editable);}/** The gizmo's on-screen rotation (radians): the negated active rotation in local* space (screen y is down), else 0. Shared with the viewport's gizmo render. */export function gizmoScreenAngleRad(ids: readonly EntityId[]): number {- return useEditorStore.getState().coordSpace === 'local' ? -primaryRotationRad(ids) : 0;+ return useEditorStore.getState().coordSpace === 'local'+ ? -primaryRotationRad(transformableIds(ids))+ : 0;}/*** Alt-drag: clone each id and return targets that drag from the *originals'* start* transforms (so the copies track the cursor exactly, the clone offset overwritten* on the first move). Selects the new copies. Each clone is its own undo step,- * preceding the move gesture.+ * preceding the move gesture. Locked members are left out, like every other+ * viewport write — an Alt-drag over a mixed selection clones what it can move.*/function altDuplicateTargets(ids: readonly EntityId[]): { targets: Target[]; pivot: Pt | null } {const targets: Target[] = [];const pts: Pt[] = [];- for (const sid of pruneDescendants(ids)) {+ for (const sid of transformableIds(pruneDescendants(ids))) {const t = readTarget(sid);if (!t) continue;const copy = SceneCommands.duplicateEntity(sid);diff --git a/desktop/tests/transform-tool.test.ts b/desktop/tests/transform-tool.test.tsindex 3a7c42ff0..d5918ab58 100644--- a/desktop/tests/transform-tool.test.ts+++ b/desktop/tests/transform-tool.test.ts@@ -13,6 +13,7 @@ import { GIZMO } from '@/tools/gizmo';const h = vi.hoisted(() => ({pick: { entity: null as number | null, rect: [] as number[], stack: undefined as number[] | undefined },pos: new Map<number, { x: number; y: number }>(),+ locked: new Set<number>(),calls: { setXY: [] as Array<[number, number, number]>, dup: [] as number[], commit: 0, abort: 0 },}));@@ -48,11 +49,12 @@ vi.mock('@/engine/SceneModel', () => ({runtimeFor: (s: number) => s,sourceFor: (r: number) => r,entityBySource: () => undefined, // no hierarchy in these tests+ isEditable: (s: number) => !h.locked.has(s),subscribe: () => {},},}));-import { TRANSFORM_TOOLS } from '@/tools/transformTools';+import { TRANSFORM_TOOLS, selectionPivot } from '@/tools/transformTools';import { Marquee } from '@/tools/marquee';import { useSelection } from '@/store/selectionStore';import { useEditorStore } from '@/store/editorStore';@@ -67,6 +69,7 @@ beforeEach(() => {h.pick.rect = [];h.pick.stack = undefined;h.pos.clear();+ h.locked.clear();h.calls.setXY = [];h.calls.dup = [];h.calls.commit = 0;@@ -234,3 +237,46 @@ describe('gizmo handle → axis-constrained group transform', () => {expect(h.calls.setXY.at(-1)).toEqual([7, 225, 215]);});});++describe('locked entities are not transformed by the viewport', () => {+ // Picking already refuses a locked entity, but the OUTLINER selects one happily —+ // and until selectionPivot answered for the editable subset, the gizmo that+ // appeared for it dragged like any other, so a lock stopped the click and nothing+ // else. This is the whole of what a lock does to a gesture.+ it('a locked selection has no gizmo pivot, so the drag writes nothing and marquees', () => {+ useSelection.getState().select(7);+ h.pos.set(7, { x: 200, y: 200 });+ h.locked.add(7);+ expect(selectionPivot([7])).toBeNull(); // no pivot → the viewport draws no gizmo+ const t = TRANSFORM_TOOLS.move;+ const downX = 200 + GIZMO.axisLen - 4;+ t.onPointerDown(ev(downX, 200), ctx);+ t.onPointerMove(ev(downX + 40, 240), ctx);+ // No handle and (picking already refuses it) no body: the spot is empty space,+ // so the gesture is a box-select — the same thing it is over bare grid.+ expect(Marquee.get()).not.toBeNull();+ t.onPointerUp(ev(downX + 40, 240), ctx);+ expect(h.calls.setXY).toEqual([]);+ });++ it('a mixed selection transforms only its unlocked members', () => {+ useSelection.getState().selectMany([7, 8], 7);+ h.pos.set(7, { x: 200, y: 200 });+ h.pos.set(8, { x: 200, y: 200 });+ h.locked.add(8);+ const t = TRANSFORM_TOOLS.move;+ const downX = 200 + GIZMO.axisLen - 4;+ expect(t.onPointerDown(ev(downX, 200), ctx)).toBe(true); // 7 still has handles+ t.onPointerMove(ev(downX + 40, 200), ctx);+ t.onPointerUp(ev(downX + 40, 200), ctx);+ expect(h.calls.setXY.map(([id]) => id)).toEqual([7]);+ });++ it('unlocking restores the pivot', () => {+ h.pos.set(7, { x: 200, y: 200 });+ h.locked.add(7);+ expect(selectionPivot([7])).toBeNull();+ h.locked.delete(7);+ expect(selectionPivot([7])).toEqual({ x: 200, y: 200 });+ });+});diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdxindex b9e8c9fb4..c05e26489 100644--- a/docs/astro/src/content/docs/guides/editor.mdx+++ b/docs/astro/src/content/docs/guides/editor.mdx@@ -206,7 +206,10 @@ The Outliner is the scene's hierarchy. You can:jump to the matching entity.- **Rename** with `F2`, **Duplicate** with Ctrl/⌘ + D, **Delete** with Delete.- **Hide/Show** and **Lock/Unlock** entities (independent of whether the component is- enabled at runtime).+ enabled at runtime). Hiding takes the entity out of the edit viewport — sprites,+ skeletons, tilemaps, particles, lights and all — without editing the scene the game+ loads. Locking leaves it visible and selectable but gives it no handles: the+ viewport won't pick it, and the transform gizmo won't appear for it.- **Create Prefab** from a selection, then drop instances back into the scene.### The Details paneldiff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor.mdxindex d58384b3e..7d10bad3b 100644--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx@@ -173,7 +173,9 @@ Outliner 是场景的层级。你可以:- 把实体拖到彼此上重设父子,并用**文件夹**归类。- **按名跳转** — 树聚焦时,输入名字的前几个字母即可跳到匹配的实体。- 用 `F2` **重命名**、`mod + D` **复制**、`Delete` **删除**。-- **隐藏/显示**和**锁定/解锁**实体(与组件在运行时是否 enabled 解耦)。+- **隐藏/显示**和**锁定/解锁**实体(与组件在运行时是否 enabled 解耦)。隐藏是把实体从编辑视口里+ 拿掉——精灵、骨架、瓦片图、粒子、灯光一概如此——而不改动游戏真正加载的场景。锁定则仍然可见、可选中,+ 只是不再有把手:视口不会拾取它,变换 Gizmo 也不会为它出现。- 从选择**创建预制体**,再把实例拖回场景。### Details 面板