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(ecs): setEntityVisible knew three renderers, the scene manager knew six
esenginee00187cd3c15
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 55404b9c6..630c2bd00 100644--- a/sdk/src/scene/sceneManager.ts+++ b/sdk/src/scene/sceneManager.ts@@ -18,20 +18,12 @@ import { registerDrawCallback, unregisterDrawCallback } from '../render/customDrimport { 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.tsindex 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 Teamimport { 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', () => {