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(ecs): setEntityVisible knew three renderers, the scene manager knew six

esenginee00187cd3c15
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 3a8f057b1..ca3247348 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1443 stable · 17 beta · 1 deprecated
+Symbols: 1444 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -9632,6 +9632,11 @@ FsmPlugin
(): boolean
```
+## hasVisibility — function
+```
+(world: World, entity: Entity): boolean
+```
+
## headlessBasePlugins — const
```
() => Plugin[]
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 14598791b..89e228845 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1462 stable · 22 beta · 1 deprecated
+Symbols: 1463 stable · 22 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -9842,6 +9842,11 @@ FsmPlugin
(): boolean
```
+## hasVisibility — function
+```
+(world: World, entity: Entity): boolean
+```
+
## headlessBasePlugins — const
```
() => Plugin[]
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 779411b40..007829ad5 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1442 stable · 19 beta · 1 deprecated
+Symbols: 1443 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -9627,6 +9627,11 @@ FsmPlugin
(): boolean
```
+## hasVisibility — function
+```
+(world: World, entity: Entity): boolean
+```
+
## headlessBasePlugins — const
```
() => Plugin[]
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 659ddd156..052723bbf 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1463 stable · 17 beta · 1 deprecated
+Symbols: 1464 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -9877,6 +9877,11 @@ FsmPlugin
(): boolean
```
+## hasVisibility — function
+```
+(world: World, entity: Entity): boolean
+```
+
## headlessBasePlugins — const
```
() => Plugin[]
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index aeb01e0e4..6e2e27751 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1453 stable · 17 beta · 1 deprecated
+Symbols: 1454 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -9654,6 +9654,11 @@ FsmPlugin
(): boolean
```
+## hasVisibility — function
+```
+(world: World, entity: Entity): boolean
+```
+
## headlessBasePlugins — const
```
() => Plugin[]
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 26215ea83..1b9438aaa 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -59,7 +59,7 @@ export {
// Entity Utils
// =============================================================================
-export { setEntityVisible, isEntityVisible, setEntityActive, isEntityActive } from './ecs/entityUtils';
+export { setEntityVisible, isEntityVisible, hasVisibility, setEntityActive, isEntityActive } from './ecs/entityUtils';
export { CacheBitmap, type BitmapCache } from './render/cacheBitmap';
export {
CacheAsBitmap,
diff --git a/sdk/src/ecs/entityUtils.ts b/sdk/src/ecs/entityUtils.ts
index ecdf39e7e..92542d15e 100644
--- a/sdk/src/ecs/entityUtils.ts
+++ b/sdk/src/ecs/entityUtils.ts
@@ -1,36 +1,76 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file entityUtils.ts
+ * @brief Showing / hiding an entity, and taking it out of the frame.
+ *
+ * Two different questions that read alike. `visible` is about drawing: the
+ * entity is still simulated, still hit by queries, just not on screen.
+ * `active` is about existing at all: a `Disabled` entity is skipped by the
+ * systems that respect the tag.
+ */
import type { Entity } from '../types';
import type { World } from './world';
-import { Sprite, ShapeRenderer, BitmapText, Disabled } from './component';
+import {
+ Sprite, SpineAnimation, BitmapText, ShapeRenderer, ParticleEmitter, Disabled,
+ type AnyComponentDef,
+} from './component';
+import { UINode, UIDisplay, type UINodeData } from '../ui/core/ui-node';
+import { UIVisual } from '../ui/core/ui-visual';
+/**
+ * Every component that draws something, each carrying its own `enabled` bit.
+ *
+ * ONE list, because scene sleep/wake and the helpers below ask the same
+ * question — and answered it differently for long enough that
+ * {@link setEntityVisible} silently did nothing to a Spine armature, a particle
+ * system or a UI element. A new renderer belongs here, not in a second list.
+ */
+export const RENDERABLE_COMPONENTS: readonly AnyComponentDef[] = [
+ Sprite, SpineAnimation, BitmapText, ShapeRenderer, ParticleEmitter, UIVisual,
+];
+
+/**
+ * Whether hiding this entity would do anything — it has a UI node, or at least
+ * one renderer of its own. False for a bare transform, whose children draw but
+ * which has nothing of its own to hide.
+ */
+export function hasVisibility(world: World, entity: Entity): boolean {
+ if (world.has(entity, UINode)) return true;
+ return RENDERABLE_COMPONENTS.some((comp) => world.has(entity, comp));
+}
+
+/**
+ * Show or hide an entity.
+ *
+ * A UI node hides through `display`, which the layout pass resolves down the
+ * tree — hiding a panel hides everything under it, and that is what hiding a UI
+ * element means. Nothing else has hierarchical visibility in the runtime, so
+ * for the rest the write lands on this entity's own renderers and its children
+ * keep drawing.
+ */
export function setEntityVisible(world: World, entity: Entity, visible: boolean): void {
- if (world.has(entity, Sprite)) {
- const sprite = world.get(entity, Sprite);
- sprite.enabled = visible;
- world.insert(entity, Sprite, sprite);
+ if (world.has(entity, UINode)) {
+ const node = world.get(entity, UINode) as UINodeData;
+ node.display = visible ? UIDisplay.Flex : UIDisplay.None;
+ world.set(entity, UINode, node);
+ return;
}
- if (world.has(entity, ShapeRenderer)) {
- const shape = world.get(entity, ShapeRenderer);
- shape.enabled = visible;
- world.insert(entity, ShapeRenderer, shape);
- }
- if (world.has(entity, BitmapText)) {
- const text = world.get(entity, BitmapText);
- text.enabled = visible;
- world.insert(entity, BitmapText, text);
+ for (const comp of RENDERABLE_COMPONENTS) {
+ if (!world.has(entity, comp)) continue;
+ const data = world.get(entity, comp) as { enabled: boolean };
+ data.enabled = visible;
+ world.set(entity, comp, data as never);
}
}
+/** The reading {@link setEntityVisible} writes. An entity with nothing to hide is visible. */
export function isEntityVisible(world: World, entity: Entity): boolean {
- if (world.has(entity, Sprite)) {
- return world.get(entity, Sprite).enabled;
- }
- if (world.has(entity, ShapeRenderer)) {
- return world.get(entity, ShapeRenderer).enabled;
+ if (world.has(entity, UINode)) {
+ return (world.get(entity, UINode) as UINodeData).display !== UIDisplay.None;
}
- if (world.has(entity, BitmapText)) {
- return world.get(entity, BitmapText).enabled;
+ for (const comp of RENDERABLE_COMPONENTS) {
+ if (world.has(entity, comp)) return (world.get(entity, comp) as { enabled: boolean }).enabled;
}
return true;
}
diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.ts
index 55404b9c6..630c2bd00 100644
--- a/sdk/src/scene/sceneManager.ts
+++ b/sdk/src/scene/sceneManager.ts
@@ -18,20 +18,12 @@ import { registerDrawCallback, unregisterDrawCallback } from '../render/customDr
import { PostProcess, PostProcessStack } from '../postprocess';
import { defineResource } from '../ecs/resource';
import { SceneTransitionController } from './SceneTransitionController';
-import {
- SceneOwner, Disabled, Sprite, SpineAnimation, BitmapText,
- ShapeRenderer, ParticleEmitter,
- type AnyComponentDef,
-} from '../ecs/component';
-import { UIVisual } from '../ui/core/ui-visual';
+import { SceneOwner, Disabled, type AnyComponentDef } from '../ecs/component';
+import { RENDERABLE_COMPONENTS } from '../ecs/entityUtils';
import { Assets } from '../asset/AssetPlugin';
import { RuntimeConfig } from '../defaults';
import { log } from '../util/logger';
-const RENDERABLE_COMPONENTS: AnyComponentDef[] = [
- Sprite, SpineAnimation, BitmapText, ShapeRenderer, ParticleEmitter, UIVisual,
-];
-
// =============================================================================
// Types
// =============================================================================
diff --git a/sdk/tests/entity-visibility.test.ts b/sdk/tests/entity-visibility.test.ts
index e5bef2153..8506b6234 100644
--- a/sdk/tests/entity-visibility.test.ts
+++ b/sdk/tests/entity-visibility.test.ts
@@ -1,19 +1,24 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect } from 'vitest';
-import { setEntityVisible, isEntityVisible, setEntityActive, isEntityActive } from '../src/ecs/entityUtils';
+import { setEntityVisible, isEntityVisible, hasVisibility, setEntityActive, isEntityActive } from '../src/ecs/entityUtils';
+import { UIDisplay } from '../src/ui/core/ui-node';
describe('Entity visibility helpers', () => {
const mockWorld = () => {
const components = new Map<string, any>();
+ const key = (comp: any) => comp._name ?? comp.name;
return {
- has: (_e: number, comp: any) => components.has(comp._name ?? comp.name),
- get: (_e: number, comp: any) => components.get(comp._name ?? comp.name),
+ has: (_e: number, comp: any) => components.has(key(comp)),
+ get: (_e: number, comp: any) => components.get(key(comp)),
+ set: (_e: number, comp: any, data: any) => {
+ components.set(key(comp), data);
+ },
insert: (_e: number, comp: any, data: any) => {
- components.set(comp._name ?? comp.name, data);
+ components.set(key(comp), data);
},
remove: (_e: number, comp: any) => {
- components.delete(comp._name ?? comp.name);
+ components.delete(key(comp));
},
_components: components,
} as any;
@@ -50,6 +55,62 @@ describe('Entity visibility helpers', () => {
const world = mockWorld();
expect(isEntityVisible(world, 1 as any)).toBe(true);
});
+
+ // These three used to be silent no-ops: the helper knew only Sprite,
+ // ShapeRenderer and BitmapText, while the scene manager's sleep/wake kept
+ // the real list. Hiding a Spine armature simply did nothing.
+ it.each(['SpineAnimation', 'ParticleEmitter', 'UIVisual'])('hides a %s', (comp) => {
+ const world = mockWorld();
+ world._components.set(comp, { enabled: true });
+
+ expect(isEntityVisible(world, 1 as any)).toBe(true);
+ setEntityVisible(world, 1 as any, false);
+ expect(world._components.get(comp).enabled).toBe(false);
+ expect(isEntityVisible(world, 1 as any)).toBe(false);
+ });
+
+ it('hides every renderer the entity carries', () => {
+ const world = mockWorld();
+ world._components.set('Sprite', { enabled: true });
+ world._components.set('BitmapText', { enabled: true });
+
+ setEntityVisible(world, 1 as any, false);
+ expect(world._components.get('Sprite').enabled).toBe(false);
+ expect(world._components.get('BitmapText').enabled).toBe(false);
+ });
+
+ // A UI node hides through `display`, which the layout pass resolves down
+ // the tree — hiding a panel has to hide what is inside it.
+ it('hides a UI node through display, not its own visual', () => {
+ const world = mockWorld();
+ world._components.set('UINode', { display: UIDisplay.Flex });
+ world._components.set('UIVisual', { enabled: true });
+
+ setEntityVisible(world, 1 as any, false);
+ expect(world._components.get('UINode').display).toBe(UIDisplay.None);
+ expect(world._components.get('UIVisual').enabled).toBe(true); // untouched
+ expect(isEntityVisible(world, 1 as any)).toBe(false);
+
+ setEntityVisible(world, 1 as any, true);
+ expect(world._components.get('UINode').display).toBe(UIDisplay.Flex);
+ expect(isEntityVisible(world, 1 as any)).toBe(true);
+ });
+ });
+
+ describe('hasVisibility', () => {
+ it('is false for a bare transform and true once something draws', () => {
+ const world = mockWorld();
+ expect(hasVisibility(world, 1 as any)).toBe(false);
+
+ world._components.set('ShapeRenderer', { enabled: true });
+ expect(hasVisibility(world, 1 as any)).toBe(true);
+ });
+
+ it('is true for a UI node with no visual of its own', () => {
+ const world = mockWorld();
+ world._components.set('UINode', { display: UIDisplay.Flex });
+ expect(hasVisibility(world, 1 as any)).toBe(true);
+ });
});
describe('setEntityActive / isEntityActive', () => {