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(outliner): real editor visibility + lock, decoupled from component enabled
esenginebedfadb85a91
diff --git a/desktop/src/engine/Reconciler.ts b/desktop/src/engine/Reconciler.tsindex 38586d9d4..cb84a3832 100644--- a/desktop/src/engine/Reconciler.ts+++ b/desktop/src/engine/Reconciler.ts@@ -5,7 +5,7 @@ import type { SceneData } from 'esengine';import type { EntityId } from '@/types';import { EngineHost } from './EngineHost';import { SceneModel, SceneModelImpl, type ModelEvent } from './SceneModel';-import { componentByName, componentDefaults, type AnyComp, type WorldT } from './schema';+import { componentByName, componentDefaults, isRenderComponent, componentEnable, type AnyComp, type WorldT } from './schema';/*** Projects the model into the World.@@ -38,13 +38,33 @@ const STRUCTURAL = new Set(['Name', 'Parent', 'Children']);function worldProjection(data: SceneData): SceneData {return {...data,- entities: (data.entities ?? []).map((e) => ({- ...e,- components: (e.components ?? []).filter((c) => !!getComponent(c.type)),- })),+ entities: (data.entities ?? []).map((e) => {+ const hidden = !!(e as { hidden?: boolean }).hidden;+ return {+ ...e,+ components: (e.components ?? [])+ .filter((c) => !!getComponent(c.type))+ .map((c) => (hidden ? foldHidden(c) : c)),+ };+ }),};}+type SceneComp = SceneData['entities'][number]['components'][number];++/**+ * Fold editor-hidden into a render component for the World projection: force its+ * enable flag off, WITHOUT mutating the model (a fresh component object), so the+ * entity disappears from the viewport while its authored `enabled` (gameplay)+ * stays intact. Non-render components pass through untouched.+ */+function foldHidden(c: SceneComp): SceneComp {+ if (!isRenderComponent(c.type)) return c;+ const en = componentEnable(c.type, c.data as Record<string, unknown>);+ if (!en) return c;+ return { ...c, data: { ...c.data, [en.key]: false } };+}+type AssetResolver = (uuid: string) => number;const UNRESOLVED: AssetResolver = () => 0;@@ -122,6 +142,8 @@ export class ReconcilerImpl {return this.projectParent(ev.sourceId);case 'nameChanged':return this.projectName(ev.sourceId);+ case 'hiddenChanged':+ return this.projectHidden(ev.sourceId);}}@@ -133,8 +155,10 @@ export class ReconcilerImpl {const rt = world.spawn();this.model.bindRuntime(sourceId, rt);if (entity.name) world.insert(rt, Name, { value: entity.name } as never);+ const hidden = this.model.isHidden(sourceId);for (const comp of entity.components) {- this.insertComponent(world, rt, comp.type, comp.data as Record<string, unknown>);+ const c = hidden ? foldHidden(comp) : comp;+ this.insertComponent(world, rt, c.type, c.data as Record<string, unknown>);}// Link to a parent that is already spawned…if (entity.parent != null) {@@ -166,11 +190,21 @@ export class ReconcilerImpl {if (!def) return; // unknown component — lives in the model onlyconst comp = entity.components.find((c) => c.type === type);if (!comp) return;- const data = this.projectData(def, comp.data as Record<string, unknown>);+ // Re-fold editor-hidden each time we project a render component, so a field+ // edit on a hidden entity doesn't quietly un-hide it in the viewport.+ const src = this.model.isHidden(sourceId) ? foldHidden(comp) : comp;+ const data = this.projectData(def, src.data as Record<string, unknown>);if (world.has(rt, def)) world.set(rt, def, data as Parameters<WorldT['set']>[2]);else world.insert(rt, def, data as never);}+ /** Re-project an entity's render components when its editor visibility flips. */+ private projectHidden(sourceId: number): void {+ const entity = this.model.entityBySource(sourceId);+ if (!entity) return;+ for (const c of entity.components) if (isRenderComponent(c.type)) this.projectComponent(sourceId, c.type);+ }+private removeComponent(sourceId: number, type: string): void {if (STRUCTURAL.has(type)) return;const world = EngineHost.mutableWorld();diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.tsindex 65f4fff3b..ba6bf1f9d 100644--- a/desktop/src/engine/SceneCommands.ts+++ b/desktop/src/engine/SceneCommands.ts@@ -9,8 +9,6 @@ import { expandInstance } from './PrefabInstance';import {componentByName,componentDefaults,- componentEnable,- isRenderComponent,userSchema,angleZToQuat,hexToRgba,@@ -611,22 +609,36 @@ export class SceneCommandsImpl {}/**- * Toggle an entity's editor visibility by flipping the `enabled` field of each- * of its components that has one (coalesced into one undo step). Lossless +- * persisted; SceneQuery reflects it as the row's visibility.+ * Toggle an entity's editor visibility (UE5 `bHiddenInEditor`) — a dedicated+ * editor-only flag the reconciler folds into the render projection. Distinct+ * from a component's gameplay `enabled`: hiding never edits component data, so+ * the running game (which loads the raw model) is unaffected. Undoable.*/setEntityVisible(sourceId: EntityId, visible: boolean): void {- const entity = this.model.entityBySource(sourceId);- if (!entity) return;- this.beginGesture(visible ? 'Show' : 'Hide');- // Toggle only RENDER components' enable flag (each via its own key — Sprite- // uses `enabled`, TilemapLayer `visible`), so hiding never disables physics.- for (const comp of entity.components) {- if (!isRenderComponent(comp.type)) continue;- const en = componentEnable(comp.type, comp.data as Record<string, unknown>);- if (en) this.setField(sourceId, comp.type, en.key, 'bool', visible);- }- this.endGesture();+ if (!this.model.entityBySource(sourceId)) return;+ const before = this.model.isHidden(sourceId);+ const after = !visible;+ if (before === after) return;+ this.model.setHidden(sourceId, after);+ this.history.record(+ visible ? 'Show' : 'Hide',+ () => this.model.setHidden(sourceId, after),+ () => this.model.setHidden(sourceId, before),+ );+ }++ /** Lock/unlock an entity (UE5 actor lock) — editor-only; blocks viewport+ * picking/transform. Undoable. */+ setEntityLocked(sourceId: EntityId, locked: boolean): void {+ if (!this.model.entityBySource(sourceId)) return;+ const before = this.model.isLocked(sourceId);+ if (before === locked) return;+ this.model.setLocked(sourceId, locked);+ this.history.record(+ locked ? 'Lock' : 'Unlock',+ () => this.model.setLocked(sourceId, locked),+ () => this.model.setLocked(sourceId, before),+ );}/**diff --git a/desktop/src/engine/SceneModel.ts b/desktop/src/engine/SceneModel.tsindex 5377236d7..cd2752fc5 100644--- a/desktop/src/engine/SceneModel.ts+++ b/desktop/src/engine/SceneModel.ts@@ -24,7 +24,12 @@ export type ModelEvent =// An entity's outliner folder path changed (organizational; not a World/ECS change).| { kind: 'folderChanged'; sourceId: number }// The scene's explicit-folder set changed (create/rename/delete of a folder).- | { kind: 'foldersChanged' };+ | { kind: 'foldersChanged' }+ // An entity's editor visibility (`bHiddenInEditor`) changed — the reconciler+ // folds it into the render projection; it never touches component data.+ | { kind: 'hiddenChanged'; sourceId: number }+ // An entity's editor lock changed — pure editor state (picking/selection only).+ | { kind: 'lockChanged'; sourceId: number };type Listener = (ev: ModelEvent) => void;@@ -295,6 +300,41 @@ export class SceneModelImpl {this.emit({ kind: 'foldersChanged' });}+ // ── Editor visibility / lock (per-entity, editor-only — UE5 bHiddenInEditor) ──+ // Like `folder`: an editor-only per-entity field, lossless, never a World+ // component. `hidden` the reconciler folds into the render projection (without+ // touching the component's gameplay `enabled`, so play — which loads the raw+ // model — ignores it). `locked` is pure editor state (blocks viewport picking).+ // Storing the default (false) removes the field (cleaner JSON).++ /** Whether an entity is hidden in the editor viewport (independent of gameplay). */+ isHidden(sourceId: number): boolean {+ return !!(this.entityBySource(sourceId) as { hidden?: boolean } | undefined)?.hidden;+ }++ /** Set an entity's editor visibility (`hidden` = not shown in the viewport). */+ setHidden(sourceId: number, hidden: boolean): void {+ const e = this.entityBySource(sourceId) as (SceneEntity & { hidden?: boolean }) | undefined;+ if (!e) return;+ if (hidden) e.hidden = true;+ else delete e.hidden;+ this.emit({ kind: 'hiddenChanged', sourceId });+ }++ /** Whether an entity is locked (not selectable/movable in the viewport). */+ isLocked(sourceId: number): boolean {+ return !!(this.entityBySource(sourceId) as { locked?: boolean } | undefined)?.locked;+ }++ /** Set an entity's editor lock. */+ setLocked(sourceId: number, locked: boolean): void {+ const e = this.entityBySource(sourceId) as (SceneEntity & { locked?: boolean }) | undefined;+ if (!e) return;+ if (locked) e.locked = true;+ else delete e.locked;+ this.emit({ kind: 'lockChanged', sourceId });+ }+// ── Source↔runtime map (Reconciler-only writers) ─────────────────────────/** Bind a source id to its current runtime entity (Reconciler, on spawn). */diff --git a/desktop/src/engine/SceneQuery.ts b/desktop/src/engine/SceneQuery.tsindex d8ad7338c..4d5ad05a6 100644--- a/desktop/src/engine/SceneQuery.ts+++ b/desktop/src/engine/SceneQuery.ts@@ -12,7 +12,6 @@ import {modelInspectableComponents,modelKindOf,modelNameOf,- modelIsVisible,} from './schema';type SceneEntity = SceneData['entities'][number];@@ -40,7 +39,17 @@ export function buildSceneTree(data: SceneData | null): SceneNode[] {const build = (e: SceneEntity): SceneNode => {const kind = modelKindOf(e);const kids = childrenOf.get(e.id)?.map(build);- return { id: e.id, name: modelNameOf(e, kind), kind, visible: modelIsVisible(e), locked: false, children: kids && kids.length ? kids : undefined };+ // `visible`/`locked` are editor-only per-entity flags (UE5 bHiddenInEditor /+ // actor lock), distinct from any component's gameplay `enabled`.+ const flags = e as { hidden?: boolean; locked?: boolean };+ return {+ id: e.id,+ name: modelNameOf(e, kind),+ kind,+ visible: !flags.hidden,+ locked: !!flags.locked,+ children: kids && kids.length ? kids : undefined,+ };};return roots.map(build);}diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.tsindex e43321dc7..846b51abd 100644--- a/desktop/src/engine/ViewportController.ts+++ b/desktop/src/engine/ViewportController.ts@@ -3,6 +3,7 @@import { Camera, CameraView, EditorView, Sprite, Transform } from 'esengine';import type { EntityId } from '@/types';import { EngineHost } from './EngineHost';+import { SceneModel } from './SceneModel';// Structural shape of the engine's CameraView resource (screen<->world).interface CameraViewLike {@@ -67,6 +68,9 @@ export const ViewportController = {let bestLayer = -Infinity;for (const e of world.getAllEntities()) {if (!world.has(e, Sprite) || !world.has(e, Transform)) continue;+ // Locked / editor-hidden entities aren't click-selectable in the viewport.+ const src = SceneModel.sourceFor(e);+ if (src != null && (SceneModel.isLocked(src) || SceneModel.isHidden(src))) continue;const t = world.get(e, Transform);const sp = world.get(e, Sprite);const w = sp.size.x * t.scale.x;diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.tsindex e20ff03b4..1397253ec 100644--- a/desktop/src/engine/schema.ts+++ b/desktop/src/engine/schema.ts@@ -484,13 +484,3 @@ export function modelNameOf(entity: SceneEntityLike, kind: NodeKind): string {return entity.name || `${cap(kind)} ${entity.id}`;}-/** Hidden iff a RENDER component is disabled — a disabled physics/audio/script- * component leaves the entity visible (only its behaviour is off). */-export function modelIsVisible(entity: SceneEntityLike): boolean {- for (const c of entity.components) {- if (!RENDER_COMPONENTS.has(c.type)) continue;- const en = componentEnable(c.type, c.data as Record<string, unknown>);- if (en && !en.value) return false;- }- return true;-}diff --git a/desktop/src/outliner/OutlinerRow.tsx b/desktop/src/outliner/OutlinerRow.tsxindex 2a7d65f3a..c5089a8a3 100644--- a/desktop/src/outliner/OutlinerRow.tsx+++ b/desktop/src/outliner/OutlinerRow.tsx@@ -10,7 +10,7 @@* handlers — the PIE tree passes none and gets a click-to-select read-only row.*/import type React from 'react';-import { ChevronRight, Eye, EyeOff, Lock, Folder, FolderOpen } from 'lucide-react';+import { ChevronRight, Eye, EyeOff, Lock, LockOpen, Folder, FolderOpen } from 'lucide-react';import { NodeIcon } from '@/components/icons';import type { EntityId, NodeKind } from '@/types';import type { OutlinerItem } from './OutlinerModel';@@ -44,6 +44,7 @@ export interface OutlinerRowProps {onStartRename?: (item: OutlinerItem) => void;onCommitRename?: (item: OutlinerItem, name: string) => void;onToggleVisible?: (id: EntityId, visible: boolean) => void;+ onToggleLock?: (id: EntityId, locked: boolean) => void;draggable?: boolean;onDragStart?: (item: OutlinerItem, e: React.DragEvent) => void;onDragOver?: (item: OutlinerItem, e: React.DragEvent) => void;@@ -70,7 +71,10 @@ export function OutlinerRow(props: OutlinerRowProps) {}const canRename = !!props.onCommitRename;- const showVis = !!props.onToggleVisible && item.kind === 'entity';+ const isEntity = item.kind === 'entity';+ const entityId = item.kind === 'entity' ? item.id : -1;+ const showVis = !!props.onToggleVisible && isEntity;+ const showLock = !!props.onToggleLock && isEntity;const collapsible = props.collapsible !== false;const showTwist = hasChildren && collapsible;@@ -80,6 +84,7 @@ export function OutlinerRow(props: OutlinerRowProps) {`row${selected ? ' sel' : ''}` +`${expanded ? ' open' : ''}` +`${visible ? '' : ' hidden'}` ++ `${locked ? ' locked' : ''}` +`${prefab ? ' prefab' : ''}` +`${isFolder ? ' folder' : ''}` +`${isDrop ? ' drop' : ''}`@@ -138,22 +143,29 @@ export function OutlinerRow(props: OutlinerRowProps) {<span className="rtype">{typeLabel}</span>+ {showLock && (+ <span+ className="rlock"+ title={locked ? 'Unlock' : 'Lock'}+ onClick={(e) => {+ e.stopPropagation();+ props.onToggleLock!(entityId, !locked);+ }}+ >+ {locked ? <Lock size={12} strokeWidth={1.85} /> : <LockOpen size={12} strokeWidth={1.85} />}+ </span>+ )}+{showVis && (<spanclassName="rvis"title="Toggle visibility"onClick={(e) => {e.stopPropagation();- props.onToggleVisible!((item as { id: EntityId }).id, !visible);+ props.onToggleVisible!(entityId, !visible);}}>- {locked ? (- <Lock size={12} strokeWidth={1.85} />- ) : visible ? (- <Eye size={13} strokeWidth={1.85} />- ) : (- <EyeOff size={13} strokeWidth={1.85} />- )}+ {visible ? <Eye size={13} strokeWidth={1.85} /> : <EyeOff size={13} strokeWidth={1.85} />}</span>)}</div>diff --git a/desktop/src/panels/Outliner.tsx b/desktop/src/panels/Outliner.tsxindex d5d230338..241febb5f 100644--- a/desktop/src/panels/Outliner.tsx+++ b/desktop/src/panels/Outliner.tsx@@ -250,6 +250,7 @@ export function Outliner() {];}const id = ctx.item.id;+ const { visible, locked } = ctx.item.node;return [{ label: 'Rename', shortcut: 'F2', onClick: () => setRenaming(entityKey(id)) },{@@ -270,6 +271,9 @@ export function Outliner() {},},{ sep: true },+ { label: visible ? 'Hide' : 'Show', onClick: () => selectionOrTarget(id).forEach((i) => SceneCommands.setEntityVisible(i, !visible)) },+ { label: locked ? 'Unlock' : 'Lock', onClick: () => selectionOrTarget(id).forEach((i) => SceneCommands.setEntityLocked(i, !locked)) },+ { sep: true },{ label: 'New Folder from Selection', onClick: () => newFolder('', selectionOrTarget(id)) },{ label: 'Move to Root', onClick: () => SceneCommands.moveToFolder(selectionOrTarget(id), null) },{ label: 'Unparent', onClick: () => selectionOrTarget(id).forEach((i) => SceneCommands.setParent(i, null)) },@@ -296,6 +300,7 @@ export function Outliner() {onStartRename={onStartRename}onCommitRename={commitRename}onToggleVisible={(id, visible) => SceneCommands.setEntityVisible(id, visible)}+ onToggleLock={(id, locked) => SceneCommands.setEntityLocked(id, locked)}onDragStart={onDragStartRow}onDragOver={onDragOverRow}onDrop={onDropRow}diff --git a/desktop/src/theme/outliner.css b/desktop/src/theme/outliner.cssindex 7e3d7adeb..b2eb0875c 100644--- a/desktop/src/theme/outliner.css+++ b/desktop/src/theme/outliner.css@@ -44,7 +44,7 @@}.outliner-cols .c-name { flex: 1; }.outliner-cols .c-type { width: 78px; flex-shrink: 0; }-.outliner-cols .c-vis { width: 24px; text-align: center; flex-shrink: 0; }+.outliner-cols .c-vis { width: 48px; text-align: center; flex-shrink: 0; } /* lock + eye *//* Rows */.row {@@ -85,12 +85,17 @@}.row .rtype { width: 78px; font-size: var(--fs-2xs); color: var(--text-mute); font-family: var(--mono); flex-shrink: 0; }.row.sel .rtype { color: rgba(255, 255, 255, 0.72); }-.row .rvis { width: 24px; display: grid; place-items: center; color: var(--text-mute); opacity: 0; transition: opacity var(--t-fast), color var(--t-fast); flex-shrink: 0; }+.row .rvis, .row .rlock { width: 24px; display: grid; place-items: center; color: var(--text-mute); opacity: 0; transition: opacity var(--t-fast), color var(--t-fast); flex-shrink: 0; }.row:hover .rvis, .row.sel .rvis, .row.hidden .rvis { opacity: 1; }-.row.sel .rvis { color: rgba(255, 255, 255, 0.8); }-.row .rvis:hover { color: var(--text); }-.row.sel .rvis:hover { color: #fff; }+.row:hover .rlock, .row.sel .rlock, .row.locked .rlock { opacity: 1; }+.row.sel .rvis, .row.sel .rlock { color: rgba(255, 255, 255, 0.8); }+.row .rvis:hover, .row .rlock:hover { color: var(--text); }+.row.sel .rvis:hover, .row.sel .rlock:hover { color: #fff; }.row.hidden .rname { color: var(--text-mute); }+/* Locked rows: a dimmed name + a lit lock glyph (UE5 actor lock). */+.row.locked .rname { color: var(--text-mute); }+.row.locked .rlock { color: var(--info-warm); }+.row.sel.locked .rlock { color: #fff; }/* Folder rows (organizational path-folders) — read a touch stronger than entities. */.row.folder .ricon { color: var(--info-warm); }diff --git a/desktop/tests/inspector-model.test.ts b/desktop/tests/inspector-model.test.tsindex bdc903429..7d356fda9 100644--- a/desktop/tests/inspector-model.test.ts+++ b/desktop/tests/inspector-model.test.ts@@ -517,31 +517,63 @@ describe('Advanced fields (D5)', () => {});});-describe('Polish: render-scoped visibility + batch undo', () => {+describe('Editor visibility / lock (UE5 bHiddenInEditor + actor lock) + batch undo', () => {const TF = { position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 }, scale: { x: 1, y: 1, z: 1 } };- it('a disabled non-render component leaves the entity visible; a disabled renderer hides it', () => {+ it('outliner visibility/lock = editor flags, decoupled from component enabled', () => {const S = EditorSession.create();S.model.adopt({version: '1.0',name: 'v',entities: [- {- id: 1,- name: 'A',- parent: null,- children: [],- components: [{ type: 'Sprite', data: { enabled: true } }, { type: 'RigidBody', data: { enabled: false } }],- },+ { id: 1, name: 'A', parent: null, children: [], components: [{ type: 'Sprite', data: { enabled: true } }] },+ // A component disabled for gameplay is NOT editor-hidden — still shown.{ id: 2, name: 'B', parent: null, children: [], components: [{ type: 'Sprite', data: { enabled: false } }] },+ // The editor `hidden`/`locked` flags drive the row, regardless of components.+ { id: 3, name: 'C', parent: null, children: [], hidden: true, locked: true, components: [{ type: 'Sprite', data: { enabled: true } }] },],} as unknown as SceneData,- new Map([[1, 1], [2, 2]]),+ new Map([[1, 1], [2, 2], [3, 3]]),);const tree = S.query.readSceneTree();- expect(tree.find((n) => n.id === 1)!.visible).toBe(true); // physics off, still rendered- expect(tree.find((n) => n.id === 2)!.visible).toBe(false); // sprite off → hidden+ expect(tree.find((n) => n.id === 2)!.visible).toBe(true); // disabled component ≠ editor-hidden+ expect(tree.find((n) => n.id === 3)!.visible).toBe(false); // editor-hidden+ expect(tree.find((n) => n.id === 3)!.locked).toBe(true);+ });++ it('setEntityVisible toggles the editor hidden flag — never the component enabled; undoable', () => {+ const S = EditorSession.create();+ S.model.adopt(+ { version: '1.0', name: 'v', entities: [{ id: 1, name: 'A', parent: null, children: [], components: [{ type: 'Sprite', data: { enabled: true } }] }] } as unknown as SceneData,+ new Map([[1, 1]]),+ );+ S.commands.setEntityVisible(1, false);+ expect(S.query.readSceneTree()[0].visible).toBe(false);+ expect(S.model.isHidden(1)).toBe(true);+ // The Sprite's gameplay enable is untouched (play, loading the raw model, ignores hidden).+ expect((S.model.entityBySource(1)!.components[0].data as { enabled: boolean }).enabled).toBe(true);+ S.history.undo();+ expect(S.query.readSceneTree()[0].visible).toBe(true);+ expect(S.model.isHidden(1)).toBe(false);+ });++ it('setEntityLocked toggles the lock flag (undoable); flags round-trip through serialize', () => {+ const S = EditorSession.create();+ S.model.adopt(+ { version: '1.0', name: 'v', entities: [{ id: 1, name: 'A', parent: null, children: [], components: [] }] } as unknown as SceneData,+ new Map([[1, 1]]),+ );+ S.commands.setEntityLocked(1, true);+ expect(S.query.readSceneTree()[0].locked).toBe(true);+ S.commands.setEntityVisible(1, false);+ const out = S.model.serialize() as SceneData;+ const e1 = out.entities[0] as { hidden?: boolean; locked?: boolean };+ expect(e1.hidden).toBe(true);+ expect(e1.locked).toBe(true);+ S.history.undo(); // un-hide+ S.history.undo(); // un-lock+ expect(S.model.isLocked(1)).toBe(false);});it('multi-select add then remove component is one undo step each', () => {