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): 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.ts
index 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.mdx
index 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 panel
diff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
index 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 面板