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): hiding a parent hides what it contains

yhha1c519ea8147
diff --git a/desktop/src/engine/Reconciler.ts b/desktop/src/engine/Reconciler.ts
index ad81678cd..67a982bb4 100644
--- a/desktop/src/engine/Reconciler.ts
+++ b/desktop/src/engine/Reconciler.ts
@@ -8,6 +8,7 @@ import { PerfMonitor } from './PerfMonitor';
import { SceneModel, SceneModelImpl, type ModelEvent } from './SceneModel';
import { assetFieldType, spineSlotType, componentByName, componentDefaults, componentEntityFields, isRenderComponent, componentEnable, readonlyFieldsFor, type AnyComp, type WorldT } from './schema';
import { EntityRefIndex } from './EntityRefIndex';
+import { hiddenInTreeResolver, type HiddenNode } from './hiddenInTree';
/**
* Projects the model into the World.
@@ -47,10 +48,16 @@ const STRUCTURAL = new Set(['Name', 'Parent', 'Children']);
* stays complete.
*/
function worldProjection(data: SceneData): SceneData {
+ const entities = data.entities ?? [];
+ // Resolved down the hierarchy, not read off each entity: hiding a parent has
+ // to hide what it contains. Memoized across the whole pass — a UI package is
+ // a deep tree, and walking every entity's chain on its own is quadratic.
+ const byId = new Map(entities.map((e) => [e.id, e as HiddenNode]));
+ const isHidden = hiddenInTreeResolver((id) => byId.get(id));
return {
...data,
- entities: (data.entities ?? []).map((e) => {
- const hidden = !!(e as { hidden?: boolean }).hidden;
+ entities: entities.map((e) => {
+ const hidden = isHidden(e.id);
return {
...e,
components: (e.components ?? [])
@@ -251,7 +258,7 @@ 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);
+ const hidden = this.model.isHiddenInTree(sourceId);
for (const comp of entity.components) {
const c = hidden ? foldHidden(comp) : comp;
this.insertComponent(world, rt, c.type, c.data as Record<string, unknown>);
@@ -343,7 +350,7 @@ export class ReconcilerImpl {
if (!comp) return;
// 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 src = this.model.isHiddenInTree(sourceId) ? foldHidden(comp) : comp;
const data = this.projectData(type, def, src.data as Record<string, unknown>);
if (world.has(rt, def)) {
// Readonly fields (Transform's world-space transform) are ENGINE-computed each
@@ -362,10 +369,30 @@ export class ReconcilerImpl {
}
/** Re-project an entity's render components when its editor visibility flips. */
+ /**
+ * Re-fold editor-hidden over an entity AND everything under it.
+ *
+ * The subtree is the point: visibility is inherited, so the entity whose flag
+ * changed is the only one whose FLAG changed and the last one whose rendering
+ * did. Toggling a parent used to re-project just that parent, which is why
+ * hiding a group left every child on screen.
+ *
+ * Whole-subtree rather than "descendants that are not hidden themselves": a
+ * child with its own flag set is already folded off, so re-projecting it is a
+ * write of the value it already has, and stopping at it would mean tracking
+ * why we stopped.
+ */
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);
+ const seen = new Set<number>();
+ const walk = (id: number): void => {
+ if (seen.has(id)) return; // a malformed parent chain must not hang the editor
+ seen.add(id);
+ const entity = this.model.entityBySource(id);
+ if (!entity) return;
+ for (const c of entity.components) if (isRenderComponent(c.type)) this.projectComponent(id, c.type);
+ for (const child of entity.children) walk(child);
+ };
+ walk(sourceId);
}
private removeComponent(sourceId: number, type: string): void {
@@ -388,6 +415,11 @@ export class ReconcilerImpl {
// drops the child out of the UI layout's buildDFS walk.
if (pr != null) world.setParent(rt, pr);
else world.removeParent(rt);
+ // Visibility is inherited, so a move changes it: dragged under a hidden
+ // group the subtree has to go, dragged back out it has to return. Nothing
+ // about the entity's own flag changed, which is why this cannot wait for a
+ // hiddenChanged that will never come.
+ this.projectHidden(sourceId);
}
private projectName(sourceId: number): void {
diff --git a/desktop/src/engine/SceneModel.ts b/desktop/src/engine/SceneModel.ts
index 1c8d8ecc4..847367fbf 100644
--- a/desktop/src/engine/SceneModel.ts
+++ b/desktop/src/engine/SceneModel.ts
@@ -3,6 +3,7 @@
import type { SceneData } from 'esengine';
import type { EntityId } from '@/types';
import { isEnvironmentEntity } from './prefabEnvironment';
+import { hiddenInTree, type HiddenNode } from './hiddenInTree';
type SceneEntity = SceneData['entities'][number];
type SceneComponent = SceneEntity['components'][number];
@@ -343,11 +344,19 @@ export class SceneModelImpl {
// 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). */
+ /** Whether an entity carries the hidden flag ITSELF — what the eye toggles.
+ * For "is it actually visible", ask {@link isHiddenInTree}: hiding a parent
+ * hides what it contains, and only that one answers for a child. */
isHidden(sourceId: number): boolean {
return !!(this.entityBySource(sourceId) as { hidden?: boolean } | undefined)?.hidden;
}
+ /** Whether an entity is hidden by its own flag or by an ancestor's — the
+ * question every consumer of visibility actually has. */
+ isHiddenInTree(sourceId: number): boolean {
+ return hiddenInTree(sourceId, (id) => this.entityBySource(id) as HiddenNode | undefined);
+ }
+
/** 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;
@@ -399,7 +408,7 @@ export class SceneModelImpl {
* 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);
+ return this.isEditable(sourceId) && !this.isHiddenInTree(sourceId);
}
// ── Sibling order (outliner drag-reorder; render order = `data.entities` order) ──
diff --git a/desktop/src/engine/SceneQuery.ts b/desktop/src/engine/SceneQuery.ts
index 310fb5b27..9a5c07eb0 100644
--- a/desktop/src/engine/SceneQuery.ts
+++ b/desktop/src/engine/SceneQuery.ts
@@ -43,22 +43,25 @@ export function buildSceneTree(data: SceneData | null): SceneNode[] {
roots.push(e); // no parent, or a dangling parent → a scene root
}
}
- const build = (e: SceneEntity): SceneNode => {
+ // `hiddenAbove` rides the walk rather than being resolved per row: the tree is
+ // already being built top-down, so inheritance costs nothing here.
+ const build = (e: SceneEntity, hiddenAbove: boolean): SceneNode => {
const kind = modelKindOf(e);
- const kids = childrenOf.get(e.id)?.map(build);
// `visible`/`locked` are editor-only per-entity flags, distinct from any
// component's gameplay `enabled`.
const flags = e as { hidden?: boolean; locked?: boolean };
+ const kids = childrenOf.get(e.id)?.map((c) => build(c, hiddenAbove || !!flags.hidden));
return {
id: e.id,
name: modelNameOf(e, kind),
kind,
visible: !flags.hidden,
+ ...(hiddenAbove ? { hiddenByAncestor: true } : {}),
locked: !!flags.locked,
children: kids && kids.length ? kids : undefined,
};
};
- return roots.map(build);
+ return roots.map((e) => build(e, false));
}
/** One entity's identity: what it is, and (for a prefab instance) what it came from. */
diff --git a/desktop/src/engine/hiddenInTree.ts b/desktop/src/engine/hiddenInTree.ts
new file mode 100644
index 000000000..bc6b139a2
--- /dev/null
+++ b/desktop/src/engine/hiddenInTree.ts
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file hiddenInTree.ts
+ * @brief Editor visibility, resolved down the hierarchy.
+ *
+ * The eye in the Outliner sets a per-entity `hidden` flag, and five places asked
+ * that flag directly: the bulk world projection, entity spawn, component
+ * re-projection, viewport picking, and the tree the Outliner draws. Each of them
+ * therefore answered for ONE entity — so hiding a parent left every child
+ * drawing, and pickable, and shown as visible.
+ *
+ * Hiding a parent has to hide what it contains, the way it does in every editor
+ * anyone comes from. That is one rule, so it is one function, and the five
+ * callers ask it instead of reading the flag.
+ *
+ * Pure — a lookup, not a model — so the same definition serves the SceneModel
+ * (which has entities by id) and the raw `SceneData` of a bulk load (which has
+ * an array), and so it is testable without a scene.
+ */
+
+/** The two fields resolving visibility needs of any entity shape. */
+export interface HiddenNode {
+ parent?: number | null;
+ hidden?: boolean;
+}
+
+/**
+ * Whether `sourceId` is hidden — by its own flag, or by any ancestor's.
+ *
+ * A parent chain that loops would hang this; the scene model does not build
+ * one, but an `.esscene` on disk is a file a person can edit, and a hang has no
+ * error message. Bounded by the number of nodes visited instead.
+ */
+export function hiddenInTree(
+ sourceId: number,
+ lookup: (id: number) => HiddenNode | undefined,
+): boolean {
+ const seen = new Set<number>();
+ let at: number | null | undefined = sourceId;
+ while (at != null && !seen.has(at)) {
+ seen.add(at);
+ const node = lookup(at);
+ if (!node) return false;
+ if (node.hidden) return true;
+ at = node.parent;
+ }
+ return false;
+}
+
+/**
+ * The same answer for many entities at once, without re-walking shared ancestry.
+ *
+ * A bulk load resolves every entity in the scene; walking each one's chain
+ * separately is quadratic in a deep hierarchy, and a UI package is exactly that.
+ * Returns a predicate rather than a set so the memo stays private.
+ */
+export function hiddenInTreeResolver(
+ lookup: (id: number) => HiddenNode | undefined,
+): (sourceId: number) => boolean {
+ const memo = new Map<number, boolean>();
+ return (sourceId: number): boolean => {
+ // The chain from `sourceId` up to the first answer we already have.
+ const pending: number[] = [];
+ const seen = new Set<number>();
+ let at: number | null | undefined = sourceId;
+ let answer = false;
+ while (at != null && !seen.has(at)) {
+ const known = memo.get(at);
+ if (known !== undefined) { answer = known; break; }
+ seen.add(at);
+ const node = lookup(at);
+ if (!node) break;
+ pending.push(at);
+ if (node.hidden) { answer = true; break; }
+ at = node.parent;
+ }
+ // Every node on the way up shares the answer: if an ancestor hid them they
+ // are all hidden, and if none did, none of them is.
+ for (const id of pending) memo.set(id, answer);
+ return answer;
+ };
+}
diff --git a/desktop/src/outliner/OutlinerRow.tsx b/desktop/src/outliner/OutlinerRow.tsx
index 4574eaa56..bda8991a6 100644
--- a/desktop/src/outliner/OutlinerRow.tsx
+++ b/desktop/src/outliner/OutlinerRow.tsx
@@ -80,6 +80,10 @@ function OutlinerRowInner(props: OutlinerRowProps) {
const name = item.kind === 'folder' ? item.name : item.node.name;
const visible = item.kind === 'entity' ? item.node.visible : true;
+ // Dimmed the same way, because it IS the same fact on screen — the row is not
+ // being drawn. The eye still reads this row's own flag, so clicking it is not
+ // a no-op that quietly does nothing.
+ const hiddenByAncestor = item.kind === 'entity' && !!item.node.hiddenByAncestor;
const locked = item.kind === 'entity' ? item.node.locked : false;
const canRename = !!props.onCommitRename;
@@ -92,7 +96,7 @@ function OutlinerRowInner(props: OutlinerRowProps) {
`row${selected ? ' sel' : ''}` +
`${props.cursored ? ' cursor' : ''}` +
`${expanded ? ' open' : ''}` +
- `${visible ? '' : ' hidden'}` +
+ `${visible && !hiddenByAncestor ? '' : ' hidden'}` +
`${locked ? ' locked' : ''}` +
`${prefabRole ? ' prefab' : ''}` +
`${prefabRole === 'root' ? ' prefab-root' : ''}` +
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index d68bca97b..96831270f 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -21,7 +21,13 @@ export interface SceneNode {
id: EntityId;
name: string;
kind: NodeKind;
+ /** This entity's OWN eye. What the toggle writes, so it stays meaningful on a
+ * child whose parent is hidden — that child is not visible, but its own flag
+ * is still the thing the eye sets. */
visible: boolean;
+ /** Hidden because something above it is. Not visible, but not by its own
+ * doing — which is why it is a second bit rather than folded into `visible`. */
+ hiddenByAncestor?: boolean;
locked: boolean;
children?: SceneNode[];
}
diff --git a/desktop/tests/engine-model-sync.test.ts b/desktop/tests/engine-model-sync.test.ts
index 305488a57..61d490593 100644
--- a/desktop/tests/engine-model-sync.test.ts
+++ b/desktop/tests/engine-model-sync.test.ts
@@ -314,4 +314,88 @@ describe.skipIf(!HAS_WASM)('Model-authoritative projection + lossless save', ()
expect(host.world.has(newChildRt, Parent)).toBe(true);
expect((host.world.get(newChildRt, Parent) as { entity: number }).entity).toBe(runtime1);
});
+
+ /**
+ * Editor visibility is INHERITED. Five places used to read the flag off one
+ * entity, so hiding a group left every child drawing and pickable.
+ */
+ describe('hiding a parent', () => {
+ /** Group → Child, both with a Sprite, both spawned. */
+ const pair = (): { group: number; child: number; childRt: number } => {
+ const group = S.model.addEntity('Group', [{ type: 'Sprite', data: {} }] as never);
+ const child = S.model.addEntity('Child', [{ type: 'Sprite', data: {} }] as never, group);
+ return { group, child, childRt: S.model.runtimeFor(child)! };
+ };
+ const enabled = (rt: number): boolean => (host.world.get(rt, Sprite) as { enabled: boolean }).enabled;
+
+ it('takes the children with it, and gives them back', () => {
+ const { group, childRt } = pair();
+ expect(enabled(childRt)).toBe(true);
+
+ S.commands.setEntityVisible(group, false);
+ expect(enabled(childRt)).toBe(false);
+
+ S.commands.setEntityVisible(group, true);
+ expect(enabled(childRt)).toBe(true);
+ });
+
+ it('does not un-hide a child that was hidden on its own', () => {
+ const { group, child, childRt } = pair();
+ S.commands.setEntityVisible(child, false);
+ S.commands.setEntityVisible(group, false);
+ S.commands.setEntityVisible(group, true);
+ // The group is visible again; the child's own eye is still shut.
+ expect(enabled(childRt)).toBe(false);
+ });
+
+ it('leaves the authored gameplay enable alone', () => {
+ const { group, child } = pair();
+ S.commands.setEntityVisible(group, false);
+ const data = S.model.entityBySource(child)!.components.find((c) => c.type === 'Sprite')!.data as Record<string, unknown>;
+ expect(data.enabled).toBeUndefined();
+ });
+
+ it('stops the viewport grabbing what it cannot draw', () => {
+ const { group, child } = pair();
+ expect(S.model.isPickable(child)).toBe(true);
+ S.commands.setEntityVisible(group, false);
+ expect(S.model.isPickable(child)).toBe(false);
+ });
+
+ it('follows a drag INTO a hidden group, and back out', () => {
+ const { group } = pair();
+ const loose = S.model.addEntity('Loose', [{ type: 'Sprite', data: {} }] as never);
+ const looseRt = S.model.runtimeFor(loose)!;
+ S.commands.setEntityVisible(group, false);
+ expect(enabled(looseRt)).toBe(true);
+
+ S.commands.setParent(loose, group);
+ expect(enabled(looseRt)).toBe(false);
+
+ S.commands.setParent(loose, null);
+ expect(enabled(looseRt)).toBe(true);
+ });
+
+ it('reaches a grandchild, not just the first level', () => {
+ const { group, child } = pair();
+ const grand = S.model.addEntity('Grand', [{ type: 'Sprite', data: {} }] as never, child);
+ const grandRt = S.model.runtimeFor(grand)!;
+ S.commands.setEntityVisible(group, false);
+ expect(enabled(grandRt)).toBe(false);
+ });
+
+ it('is applied by a bulk load too, not only by the toggle', () => {
+ const scene = (): SceneData => ({
+ version: '1.0',
+ name: 'nested',
+ entities: [
+ { id: 10, name: 'Group', parent: null, children: [11], hidden: true, components: [{ type: 'Sprite', data: {} }] },
+ { id: 11, name: 'Child', parent: 10, children: [], components: [{ type: 'Sprite', data: {} }] },
+ ],
+ }) as unknown as SceneData;
+ S.reconciler.adopt(scene(), scene());
+ expect(enabled(S.model.runtimeFor(11)!)).toBe(false);
+ });
+ });
+
});
diff --git a/desktop/tests/hidden-in-tree.test.ts b/desktop/tests/hidden-in-tree.test.ts
new file mode 100644
index 000000000..2879e2517
--- /dev/null
+++ b/desktop/tests/hidden-in-tree.test.ts
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Editor visibility resolved down the hierarchy — the rule five callers
+ * used to each answer for one entity, which is why hiding a parent left
+ * its children drawing, pickable, and shown as visible.
+ */
+import { describe, it, expect } from 'vitest';
+import { hiddenInTree, hiddenInTreeResolver, type HiddenNode } from '../src/engine/hiddenInTree';
+import { buildSceneTree } from '../src/engine/SceneQuery';
+import type { SceneData } from 'esengine';
+
+/** `1 → 2 → 3` with whichever of them carry the flag. */
+const chain = (...hidden: number[]): Map<number, HiddenNode> => new Map([
+ [1, { parent: null, hidden: hidden.includes(1) || undefined }],
+ [2, { parent: 1, hidden: hidden.includes(2) || undefined }],
+ [3, { parent: 2, hidden: hidden.includes(3) || undefined }],
+]);
+
+const ask = (m: Map<number, HiddenNode>) => (id: number) => hiddenInTree(id, (i) => m.get(i));
+
+describe('hiddenInTree', () => {
+ it('is false for a chain nobody hid', () => {
+ const is = ask(chain());
+ expect([is(1), is(2), is(3)]).toEqual([false, false, false]);
+ });
+
+ it('hides everything under the entity that carries the flag', () => {
+ const is = ask(chain(1));
+ expect([is(1), is(2), is(3)]).toEqual([true, true, true]);
+ });
+
+ it('leaves what is ABOVE the flag alone', () => {
+ const is = ask(chain(2));
+ expect([is(1), is(2), is(3)]).toEqual([false, true, true]);
+ });
+
+ it('an unknown entity is not hidden — an engine-owned helper has no row', () => {
+ expect(hiddenInTree(99, () => undefined)).toBe(false);
+ });
+
+ it('a dangling parent stops the walk instead of throwing', () => {
+ const m = new Map<number, HiddenNode>([[2, { parent: 404 }]]);
+ expect(hiddenInTree(2, (i) => m.get(i))).toBe(false);
+ });
+
+ it('a parent cycle terminates — an .esscene is a file a person can edit', () => {
+ const m = new Map<number, HiddenNode>([[1, { parent: 2 }], [2, { parent: 1 }]]);
+ expect(hiddenInTree(1, (i) => m.get(i))).toBe(false);
+ });
+
+ it('a cycle whose member is hidden still answers true', () => {
+ const m = new Map<number, HiddenNode>([[1, { parent: 2 }], [2, { parent: 1, hidden: true }]]);
+ expect(hiddenInTree(1, (i) => m.get(i))).toBe(true);
+ });
+});
+
+describe('hiddenInTreeResolver', () => {
+ it('agrees with the single-entity walk, memoized', () => {
+ const m = chain(2);
+ const resolve = hiddenInTreeResolver((i) => m.get(i));
+ expect([resolve(3), resolve(2), resolve(1)]).toEqual([true, true, false]);
+ });
+
+ it('visits each ancestor once across a whole pass', () => {
+ const m = chain();
+ let reads = 0;
+ const resolve = hiddenInTreeResolver((i) => { reads++; return m.get(i); });
+ resolve(3); resolve(2); resolve(1);
+ // 3 walks the chain; 2 and 1 are already answered. Without the memo this is
+ // 3 + 2 + 1 — the shape that makes a deep UI tree quadratic.
+ expect(reads).toBe(3);
+ });
+
+ it('caches the answer for every node it passed, not just the one asked', () => {
+ const m = chain(1);
+ let reads = 0;
+ const resolve = hiddenInTreeResolver((i) => { reads++; return m.get(i); });
+ expect(resolve(3)).toBe(true);
+ const after = reads;
+ expect(resolve(2)).toBe(true);
+ expect(reads).toBe(after);
+ });
+});
+
+describe('the outliner tree', () => {
+ const scene = (hidden: number[]): SceneData => ({
+ version: '1.0',
+ name: 'S',
+ entities: [
+ { id: 1, name: 'Group', parent: null, children: [2], components: [], ...(hidden.includes(1) ? { hidden: true } : {}) },
+ { id: 2, name: 'Child', parent: 1, children: [], components: [], ...(hidden.includes(2) ? { hidden: true } : {}) },
+ ],
+ } as unknown as SceneData);
+
+ it('marks a child of a hidden parent, without touching its own eye', () => {
+ const [group] = buildSceneTree(scene([1]));
+ const child = group.children![0];
+ expect(group).toMatchObject({ visible: false });
+ // Its OWN flag is untouched — so the eye still toggles something.
+ expect(child.visible).toBe(true);
+ expect(child.hiddenByAncestor).toBe(true);
+ });
+
+ it('says nothing about ancestry when there is none to report', () => {
+ const [group] = buildSceneTree(scene([]));
+ expect(group.hiddenByAncestor).toBeUndefined();
+ expect(group.children![0].hiddenByAncestor).toBeUndefined();
+ });
+
+ it('a child hidden on its own is not blamed on its parent', () => {
+ const [group] = buildSceneTree(scene([2]));
+ const child = group.children![0];
+ expect(child.visible).toBe(false);
+ expect(child.hiddenByAncestor).toBeUndefined();
+ });
+});