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): three lists answered "what draws here", and none of them agreed

esenginea3ff33347966
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c24c4dfb6..3d1f32356 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,18 @@ published separately; it ships inside the editor.
component and restore it afterwards. A name that matches no bool field on the
component fails the build rather than reading as "draws nothing".
+### Fixed
+
+- **A slept scene kept drawing its characters, and hiding an entity still missed
+ renderers.** 0.45.0 unified two of the three lists that answer "what draws
+ here"; the editor's eye derived a different thirteen, and neither runtime list
+ knew about a mesh, a trail, a DragonBones armature, a tilemap layer, a `Text` or
+ a light — which is why a slept scene kept drawing its characters and kept
+ lighting the level. Each component now declares what gates its drawing (see
+ Added), so all three lists read one answer instead of three, and a tilemap layer
+ is switched through its own `visible` field rather than an `enabled` it does not
+ have.
+
## [0.45.0] - 2026-08-07
### Added
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 1ce7735af..4ccaafd20 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -39,40 +39,19 @@ export type AnyComp = Parameters<WorldT['has']>[1];
// plus UIController/UIGear, whose authoring surface is the Controllers panel and
// the Details gear dots (their array-of-object data has no generic field control).
const HIDDEN_COMPONENTS = new Set(['Parent', 'Children', 'Name', 'UIController', 'UIGear', 'EventBinding']);
-// Which components the Outliner's eye reaches: hiding an entity forces the enable
-// flag off on each of them (see Reconciler.foldHidden). Disabling a NON-render
-// component (physics, audio, a script) turns that behaviour off without hiding
-// anything, so those must stay out.
-//
-// The scene-space renderables are DERIVED, not listed: a component that names a
-// sorting layer is a thing the renderer draws in scene order, which is exactly the
-// set the eye has to reach. That derivation is what a hand-kept list kept getting
-// wrong — DragonBonesAnimation, Mesh2D and TrailRenderer were all renderables the
-// eye silently skipped, and every future one would have joined them.
-const SORTING_LAYER_SOURCE = 'sortingLayers';
-// The rest, which the registry gives no such marker for and so are named here:
-// BitmapText — draws in a sorting layer, but its `layer` field predates the
-// named-layer dropdown, so it carries no enumSource.
-// UIVisual — UI draws in tree order, not a sorting layer.
-// Text — same, and it has no enable flag of its own (a no-op fold, kept
-// so adding one later doesn't quietly change what the eye covers).
-// Light2D / ShadowCaster2D — not drawn, but a hidden entity must stop LIGHTING
-// and shadowing the scene too, not just stop drawing its own pixels.
-const EXTRA_RENDER_COMPONENTS = new Set(['BitmapText', 'UIVisual', 'Text', 'Light2D', 'ShadowCaster2D']);
-const renderComponentCache = new Map<string, boolean>();
-
-/** Whether a component's enable flag participates in the entity's render visibility. */
+/**
+ * Which components the Outliner's eye reaches: hiding an entity forces the gating
+ * flag off on each of them (see Reconciler.foldHidden). Not the editor's answer —
+ * each component declares `renderable=<field>` at its own site, so the eye reaches
+ * exactly what `setEntityVisible` and scene sleep/wake reach.
+ */
export function isRenderComponent(name: string): boolean {
- const cached = renderComponentCache.get(name);
- if (cached !== undefined) return cached;
- const def = registryDef(name);
- const meta = def ? getComponentFieldMeta(name) : {};
- const drawsInLayer = Object.values(meta).some((f) => f.enumSource === SORTING_LAYER_SOURCE);
- const result = drawsInLayer || EXTRA_RENDER_COMPONENTS.has(name);
- // A name the registry doesn't know yet (a project component registered later)
- // isn't memoised — its answer would be a guess made before it existed.
- if (def) renderComponentCache.set(name, result);
- return result;
+ return renderableFieldOf(name) !== null;
+}
+
+/** The declared bool field gating a component's visibility, or null. */
+function renderableFieldOf(name: string): string | null {
+ return registryDef(name)?.renderableField ?? null;
}
// Computed world-space mirrors on Transform — never editable.
const DERIVED_FIELDS = new Set(['worldPosition', 'worldRotation', 'worldScale']);
@@ -835,6 +814,14 @@ export function componentEnable(
const def = componentByName(compType);
const defaults = def ? componentDefaults(def) : userSchema(compType)?.default;
const src = defaults ?? data;
+ // A renderable says which field gates it, so no guessing is needed. ENABLE_KEYS
+ // below is for the rest — a collider, a rigid body, a project component — whose
+ // header checkbox is a convention rather than a declaration.
+ const declared = renderableFieldOf(compType);
+ if (declared !== null) {
+ const raw = declared in data ? data[declared] : src[declared];
+ return { key: declared, value: raw !== false };
+ }
for (const key of ENABLE_KEYS) {
if (typeof src[key] === 'boolean') {
const raw = key in data ? data[key] : src[key];
diff --git a/desktop/tests/schema.test.ts b/desktop/tests/schema.test.ts
index e9dc92c33..4132aedd5 100644
--- a/desktop/tests/schema.test.ts
+++ b/desktop/tests/schema.test.ts
@@ -90,19 +90,21 @@ describe('spineSlotType', () => {
});
describe('isRenderComponent', () => {
- // The eye's reach used to be a hand-kept list, and three renderables were
- // missing from it — so the set is derived from the engine schema (a component
- // that names a sorting layer is drawn) with only the unmarked ones listed.
- it('covers every component that names a sorting layer', () => {
+ // The eye reaches what each component DECLARES (`renderable=<field>` at its
+ // ES_COMPONENT site, `renderableField` for a TS-defined one) — not a list the
+ // editor keeps, which would drift from the runtime's answer.
+ it('covers every renderer, scene-space and UI', () => {
for (const name of [
'Sprite', 'ShapeRenderer', 'SpineAnimation', 'DragonBonesAnimation',
'TilemapLayer', 'ParticleEmitter', 'Mesh2D', 'TrailRenderer',
+ 'BitmapText', 'UIVisual', 'Text',
]) {
expect(isRenderComponent(name), name).toBe(true);
}
});
- it('covers the ones the registry marks no layer on: UI text/visuals and lighting', () => {
- for (const name of ['BitmapText', 'UIVisual', 'Text', 'Light2D', 'ShadowCaster2D']) {
+ // Not drawn, but hiding an entity has to stop it lighting the scene too.
+ it('covers lighting', () => {
+ for (const name of ['Light2D', 'ShadowCaster2D']) {
expect(isRenderComponent(name), name).toBe(true);
}
});
@@ -110,6 +112,13 @@ describe('isRenderComponent', () => {
for (const name of [
'Transform', 'Camera', 'RigidBody', 'BoxCollider', 'CircleCollider',
'Interactable', 'UIScroll', 'UIMask', 'ParticleForceField', 'NotAComponent',
+ // Each carries an `enabled` / `visible` field that has nothing to do
+ // with drawing — folding `Perception.visible` would corrupt what an AI
+ // agent believes it sees. Hence declared, not sniffed off a field name.
+ 'Animator', 'SpriteAnimator', 'AudioSource', 'CacheAsBitmap', 'Perception',
+ // Video's flag drives PLAYBACK; the frames are drawn by the sibling
+ // Sprite / UIVisual / Mesh2D, which hides on its own declaration.
+ 'Video',
]) {
expect(isRenderComponent(name), name).toBe(false);
}
diff --git a/docs/astro/src/content/docs/core-concepts/components.mdx b/docs/astro/src/content/docs/core-concepts/components.mdx
index 36e68a48a..e3bd901bc 100644
--- a/docs/astro/src/content/docs/core-concepts/components.mdx
+++ b/docs/astro/src/content/docs/core-concepts/components.mdx
@@ -70,8 +70,17 @@ Other component-level metadata: `assetFields` (marks a field as an asset
reference, so Details renders a picker and the cook ships the dependency),
`animatableFields` (which fields the [Sequencer](/docs/animation/timeline/) can
key — defaults to all numeric fields), `transient` (never saved into the scene —
-for per-frame runtime state), and `replicatedFields` (synced by
-[networking](/docs/scripting/networking/)'s state replication).
+for per-frame runtime state), `replicatedFields` (synced by
+[networking](/docs/scripting/networking/)'s state replication), and
+`renderableField`.
+
+`renderableField` names the boolean field that gates your component's drawing —
+declare it if the component draws something of its own (say through a custom
+draw callback), and hiding the entity reaches it: the Outliner's eye,
+`setEntityVisible`, and a sleeping scene all switch that field off and restore it
+afterwards. Leave it out for a component that only carries data or behaviour;
+plenty of those have an `enabled` field that has nothing to do with drawing, and
+switching it off would stop the wrong thing.
## Built-in components
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx
index c13d95892..5bb90fcf3 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx
@@ -65,8 +65,14 @@ const Turret = defineComponent('Turret', {
存储选项的整数值)、`flags`(位掩码多选)、`tooltip`。其他组件级元数据:
`assetFields`(把字段标记为资产引用,Details 渲染选择器、cook 会带上依赖)、
`animatableFields`([Sequencer](/docs/zh-cn/animation/timeline/) 可打关键帧的字段
-——默认为全部数字字段)、`transient`(永不存进场景——用于逐帧运行时状态),以及
-`replicatedFields`(由[联网](/docs/zh-cn/scripting/networking/)的状态复制同步)。
+——默认为全部数字字段)、`transient`(永不存进场景——用于逐帧运行时状态)、
+`replicatedFields`(由[联网](/docs/zh-cn/scripting/networking/)的状态复制同步),以及
+`renderableField`。
+
+`renderableField` 指出哪个布尔字段控制你的组件绘不绘制——如果组件自己画东西
+(比如通过自定义绘制回调),就声明它,隐藏实体便能作用到它:Outliner 的眼睛、
+`setEntityVisible`、以及场景休眠都会关掉该字段并在之后恢复。只携带数据或行为的
+组件不要声明——这类组件里有不少也有 `enabled` 字段,但与绘制无关,关掉它停错东西。
## 内置组件
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 440c4bfbf..f571670c2 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1209,6 +1209,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1712,6 +1713,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1725,6 +1727,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: string[] | undefined
fields: Record<string, FieldMeta> | undefined
readonlyFields: string[] | undefined
+renderableField: string | undefined
replicatedFields: string[] | undefined
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 55db5dfc7..606567b4d 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1209,6 +1209,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1712,6 +1713,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1733,6 +1735,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: string[] | undefined
fields: Record<string, FieldMeta> | undefined
readonlyFields: string[] | undefined
+renderableField: string | undefined
replicatedFields: string[] | undefined
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 2c916cb0b..bda4561be 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1204,6 +1204,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1707,6 +1708,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1720,6 +1722,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: string[] | undefined
fields: Record<string, FieldMeta> | undefined
readonlyFields: string[] | undefined
+renderableField: string | undefined
replicatedFields: string[] | undefined
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index ad64152b5..2a0f2f9a6 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1204,6 +1204,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1707,6 +1708,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1720,6 +1722,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: string[] | undefined
fields: Record<string, FieldMeta> | undefined
readonlyFields: string[] | undefined
+renderableField: string | undefined
replicatedFields: string[] | undefined
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e59edabb2..134a0b0b1 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1204,6 +1204,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1707,6 +1708,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: readonly string[]
fieldMeta: Readonly<Record<string, FieldMeta>>
readonlyFields: readonly string[]
+renderableField: string | null
replicatedFields: readonly string[]
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
@@ -1720,6 +1722,7 @@ discoverAssets: ((data: Record<string, unknown>) => AssetRef[]) | undefined
entityFields: string[] | undefined
fields: Record<string, FieldMeta> | undefined
readonlyFields: string[] | undefined
+renderableField: string | undefined
replicatedFields: string[] | undefined
skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index cddd78223..f371c0a12 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -38,6 +38,19 @@ export interface ComponentMetaEntry {
* these over `defaults`; `defaults` alone is the runtime ctor truth.
*/
editorDefaults?: Record<string, unknown>;
+ /**
+ * The bool field that gates this component's part in the entity's
+ * visibility, authored `renderable=<field>` at the C++ ES_COMPONENT
+ * site. Absent = nothing of this component is hidden by hiding its
+ * entity. ONE answer for both realms: the runtime folds visibility
+ * onto these fields, and the editor's eye reaches exactly them.
+ */
+ renderableField?: string;
+ /**
+ * Runtime-only state that must never persist, authored `transient` at
+ * the C++ ES_COMPONENT site — scene serialization omits it.
+ */
+ transient?: boolean;
assetFields: AssetFieldMeta[];
skeletal?: SkeletalFieldMeta;
entityFields: string[];
@@ -74,6 +87,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
font: 0,
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [{ field: 'font', type: 'font' as AssetFieldType }],
entityFields: [],
colorFields: ['color'],
@@ -222,6 +236,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
material: 0,
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [{ field: 'material', type: 'material' as AssetFieldType }],
skeletal: { skeletonField: 'skeletonPath', atlasField: 'atlasPath', runtime: 'dragonbones' },
entityFields: [],
@@ -282,6 +297,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
shadowDistance: 0,
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [],
entityFields: [],
colorFields: ['color'],
@@ -307,6 +323,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
material: 0,
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [{ field: 'texture', type: 'texture' as AssetFieldType }, { field: 'material', type: 'material' as AssetFieldType }],
entityFields: [],
colorFields: ['color'],
@@ -389,6 +406,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
collisionFriction: 0.1,
collisionLifetimeLoss: 0,
},
+ renderableField: 'enabled',
assetFields: [{ field: 'texture', type: 'texture' as AssetFieldType }, { field: 'material', type: 'material' as AssetFieldType }],
entityFields: ['subEmitter'],
colorFields: ['startColor', 'endColor'],
@@ -514,6 +532,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
size: { x: 32, y: 32 },
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [],
entityFields: [],
colorFields: [],
@@ -532,6 +551,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
parallax: { x: 1, y: 1 },
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [],
entityFields: [],
colorFields: ['color'],
@@ -560,6 +580,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
material: 0,
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [{ field: 'material', type: 'material' as AssetFieldType }],
skeletal: { skeletonField: 'skeletonPath', atlasField: 'atlasPath', runtime: 'spine' },
entityFields: [],
@@ -594,6 +615,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
editorDefaults: {
size: { x: 100, y: 100 },
},
+ renderableField: 'enabled',
assetFields: [{ field: 'texture', type: 'texture' as AssetFieldType }, { field: 'material', type: 'material' as AssetFieldType }],
entityFields: [],
colorFields: ['color'],
@@ -628,6 +650,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
parallaxFactor: { x: 1, y: 1 },
visible: true,
},
+ renderableField: 'visible',
assetFields: [{ field: 'tileset', type: 'texture' as AssetFieldType }],
entityFields: [],
colorFields: ['tintColor'],
@@ -658,6 +681,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
material: 0,
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [{ field: 'texture', type: 'texture' as AssetFieldType }, { field: 'material', type: 'material' as AssetFieldType }],
entityFields: [],
colorFields: ['startColor', 'endColor'],
@@ -704,6 +728,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
justPressed: false,
justReleased: false,
},
+ transient: true,
assetFields: [],
entityFields: [],
colorFields: [],
@@ -799,6 +824,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
material: 0,
enabled: true,
},
+ renderableField: 'enabled',
assetFields: [{ field: 'texture', type: 'texture' as AssetFieldType }, { field: 'material', type: 'material' as AssetFieldType }],
entityFields: [],
colorFields: ['color'],
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index f14e17a4a..778b32b33 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -123,8 +123,18 @@ export interface ComponentMetadata {
* skipped by {@link serializeScene} (e.g. per-frame pointer/drag/hover state
* that its driving system rebuilds each frame). Systems still
* read/write it normally; only scene save omits it.
+ *
+ * Builtins author this at the C++ `ES_COMPONENT(transient)` site — same
+ * single-source rule as fieldMeta.
*/
transient?: boolean;
+ /**
+ * The name of the bool field that gates this component's part in an entity's
+ * visibility — set it and {@link setEntityVisible}, the editor's eye and scene
+ * sleep/wake all reach this component. Omitted = the component draws nothing.
+ * Builtins author it at the C++ `ES_COMPONENT(renderable=<field>)` site.
+ */
+ renderableField?: string;
}
/**
@@ -172,6 +182,9 @@ export interface ComponentDef<T> {
readonly discoverAssets?: (data: Record<string, unknown>) => AssetRef[];
/** Runtime-only: omitted from scene serialization. See {@link ComponentMetadata.transient}. */
readonly transient: boolean;
+ /** Bool field gating this component's visibility, or null if it draws nothing.
+ * See {@link ComponentMetadata.renderableField}. */
+ readonly renderableField: string | null;
create(data?: Partial<T>): T;
}
@@ -254,6 +267,14 @@ function createComponentDef<T extends object>(
throw new Error(`Component "${name}": replicatedFields names unknown field "${f}"`);
}
}
+ // Same reason, and the same check EHT makes for a builtin: a renderableField
+ // that names nothing would read as "draws nothing" and quietly stay visible.
+ const renderableField = metadata?.renderableField;
+ if (renderableField !== undefined && typeof defaultsRec[renderableField] !== 'boolean') {
+ throw new Error(
+ `Component "${name}": renderableField "${renderableField}" is not a boolean field of its defaults`,
+ );
+ }
return {
_id: componentId(name),
_name: name,
@@ -269,6 +290,7 @@ function createComponentDef<T extends object>(
fieldMeta: metadata?.fields ?? {},
discoverAssets: metadata?.discoverAssets,
transient: metadata?.transient ?? false,
+ renderableField: renderableField ?? null,
create(data?: Partial<T>): T {
if (keyInfo) {
const result = { ...defaultsRec };
@@ -316,6 +338,7 @@ export function defineComponent<T extends object>(
const def = createComponentDef(name, defaults, metadata);
userComponents().set(name, def);
+ componentRegistryVersion_++;
registerToEditor(name, defaults as Record<string, unknown>, false);
return def;
}
@@ -332,6 +355,7 @@ export function defineTag(name: string): ComponentDef<{}> {
const def = createComponentDef(name, {});
userComponents().set(name, def);
+ componentRegistryVersion_++;
registerToEditor(name, {}, true);
return def;
}
@@ -342,10 +366,12 @@ export function getUserComponent(name: string): ComponentDef<any> | undefined {
export function clearUserComponents(): void {
userComponents().clear();
+ componentRegistryVersion_++;
}
export function unregisterComponent(name: string): void {
userComponents().delete(name);
+ componentRegistryVersion_++;
}
// The engine's own `defineComponent`s (AI, animation, audio, physics joints, UI
@@ -402,8 +428,11 @@ export interface BuiltinComponentDef<T> {
readonly readonlyFields: readonly string[];
readonly fieldMeta: Readonly<Record<string, FieldMeta>>;
readonly discoverAssets?: (data: Record<string, unknown>) => AssetRef[];
- /** Runtime-only: omitted from scene serialization. See {@link ComponentMetadata.transient}. */
+ /** Runtime-only: omitted from scene serialization. Authored `ES_COMPONENT(transient)`. */
readonly transient: boolean;
+ /** Bool field gating this component's visibility, or null if it draws nothing.
+ * Authored `ES_COMPONENT(renderable=<field>)`. */
+ readonly renderableField: string | null;
}
// =============================================================================
@@ -477,6 +506,56 @@ export function getReplicatedFields(name: string): readonly string[] {
return getComponent(name)?.replicatedFields ?? [];
}
+/** A component that gates its drawing on a bool field, so that field is known. */
+export type RenderableComponentDef = AnyComponentDef & { readonly renderableField: string };
+
+/** Bumped by every registry mutation in this module, so the derived views below
+ * can tell "same components as last time" from "looks the same". */
+let componentRegistryVersion_ = 0;
+let renderableCache_: {
+ version: number;
+ userMap: Map<string, AnyComponentDef>;
+ userSize: number;
+ builtinSize: number;
+ list: readonly RenderableComponentDef[];
+} | null = null;
+
+/**
+ * Every registered component taking part in an entity's visibility, with the field
+ * that gates each. Derived per call — a project's own component registers long
+ * after load. The memo key carries both registry sizes and the context's map
+ * identity, so a mutation outside this module (reset, hot reload) still misses it.
+ */
+export function renderableComponents(): readonly RenderableComponentDef[] {
+ const userMap = userComponents();
+ const cached = renderableCache_;
+ if (cached !== null
+ && cached.version === componentRegistryVersion_
+ && cached.userMap === userMap
+ && cached.userSize === userMap.size
+ && cached.builtinSize === builtinRegistry.size) {
+ return cached.list;
+ }
+ const list: RenderableComponentDef[] = [];
+ // Both halves directly rather than through getComponentRegistry(), whose
+ // merged Map would be allocated and thrown away on every miss. A name cannot
+ // be in both: defineComponent and defineBuiltin each refuse the collision.
+ for (const def of builtinRegistry.values()) {
+ if (def.renderableField !== null) list.push(def as RenderableComponentDef);
+ }
+ for (const def of userMap.values()) {
+ if (def.renderableField !== null) list.push(def as RenderableComponentDef);
+ }
+ renderableCache_ = {
+ version: componentRegistryVersion_,
+ userMap,
+ userSize: userMap.size,
+ builtinSize: builtinRegistry.size,
+ list,
+ };
+ return list;
+}
+
/**
* Per-field merge of two FieldMeta maps: `override` wins key-by-key *within* a field
* (not whole-field replacement), so a builtin can author min/tooltip at the C++
@@ -552,10 +631,8 @@ export function defineBuiltin<T>(name: string, defaults: T, metadata?: Component
readonlyFields: meta?.readonlyFields ?? [],
fieldMeta: mergeFieldMeta(meta?.fields ?? {}, metadata?.fields ?? {}),
discoverAssets: metadata?.discoverAssets,
- // Builtins declare transience via the defineBuiltin metadata arg for now;
- // a C++-side ES_COMPONENT(transient) annotation can flow through
- // COMPONENT_META later without touching call sites.
- transient: metadata?.transient ?? false,
+ transient: metadata?.transient ?? meta?.transient ?? false,
+ renderableField: metadata?.renderableField ?? meta?.renderableField ?? null,
};
builtinRegistry.set(name, def);
return def;
diff --git a/sdk/src/ecs/entityUtils.ts b/sdk/src/ecs/entityUtils.ts
index 92542d15e..bc57084d4 100644
--- a/sdk/src/ecs/entityUtils.ts
+++ b/sdk/src/ecs/entityUtils.ts
@@ -8,27 +8,16 @@
* 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.
+ *
+ * WHICH components hiding reaches is not decided here: each declares itself
+ * `renderable=<field>` at its ES_COMPONENT site, and {@link renderableComponents}
+ * answers from the registry. Scene sleep/wake and the editor's eye read the same
+ * declaration, so a renderer cannot be visible to one and invisible to another.
*/
import type { Entity } from '../types';
import type { World } from './world';
-import {
- Sprite, SpineAnimation, BitmapText, ShapeRenderer, ParticleEmitter, Disabled,
- type AnyComponentDef,
-} from './component';
+import { Disabled, renderableComponents } 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
@@ -37,7 +26,7 @@ export const RENDERABLE_COMPONENTS: readonly AnyComponentDef[] = [
*/
export function hasVisibility(world: World, entity: Entity): boolean {
if (world.has(entity, UINode)) return true;
- return RENDERABLE_COMPONENTS.some((comp) => world.has(entity, comp));
+ return renderableComponents().some((comp) => world.has(entity, comp));
}
/**
@@ -56,10 +45,10 @@ export function setEntityVisible(world: World, entity: Entity, visible: boolean)
world.set(entity, UINode, node);
return;
}
- for (const comp of RENDERABLE_COMPONENTS) {
+ for (const comp of renderableComponents()) {
if (!world.has(entity, comp)) continue;
- const data = world.get(entity, comp) as { enabled: boolean };
- data.enabled = visible;
+ const data = world.get(entity, comp) as Record<string, unknown>;
+ data[comp.renderableField] = visible;
world.set(entity, comp, data as never);
}
}
@@ -69,8 +58,9 @@ export function isEntityVisible(world: World, entity: Entity): boolean {
if (world.has(entity, UINode)) {
return (world.get(entity, UINode) as UINodeData).display !== UIDisplay.None;
}
- for (const comp of RENDERABLE_COMPONENTS) {
- if (world.has(entity, comp)) return (world.get(entity, comp) as { enabled: boolean }).enabled;
+ for (const comp of renderableComponents()) {
+ if (!world.has(entity, comp)) continue;
+ return (world.get(entity, comp) as Record<string, unknown>)[comp.renderableField] !== false;
}
return true;
}
diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.ts
index 630c2bd00..92fb1a2ac 100644
--- a/sdk/src/scene/sceneManager.ts
+++ b/sdk/src/scene/sceneManager.ts
@@ -18,8 +18,7 @@ import { registerDrawCallback, unregisterDrawCallback } from '../render/customDr
import { PostProcess, PostProcessStack } from '../postprocess';
import { defineResource } from '../ecs/resource';
import { SceneTransitionController } from './SceneTransitionController';
-import { SceneOwner, Disabled, type AnyComponentDef } from '../ecs/component';
-import { RENDERABLE_COMPONENTS } from '../ecs/entityUtils';
+import { SceneOwner, Disabled, renderableComponents, type RenderableComponentDef } from '../ecs/component';
import { Assets } from '../asset/AssetPlugin';
import { RuntimeConfig } from '../defaults';
import { log } from '../util/logger';
@@ -72,7 +71,7 @@ class SceneInstance {
readonly entities = new Set<Entity>();
readonly drawCallbacks = new Map<string, DrawCallback>();
readonly postProcessBindings = new Map<Entity, PostProcessStack>();
- readonly savedEnabled = new Map<Entity, Map<AnyComponentDef, boolean>>();
+ readonly savedEnabled = new Map<Entity, Map<RenderableComponentDef, boolean>>();
readonly systemIds: symbol[] = [];
loadedTextures: Set<string> | null = null;
loadedMaterials: Set<number> | null = null;
@@ -644,17 +643,20 @@ export class SceneManagerState {
instance.savedEnabled.clear();
const world = this.app_.world;
+ // Hoisted: the same registry answer for every entity in the scene.
+ const renderables = renderableComponents();
for (const entity of instance.entities) {
if (!world.valid(entity)) continue;
world.insert(entity, Disabled, {});
- const entitySaved = new Map<AnyComponentDef, boolean>();
- for (const comp of RENDERABLE_COMPONENTS) {
+ const entitySaved = new Map<RenderableComponentDef, boolean>();
+ for (const comp of renderables) {
if (world.has(entity, comp)) {
- const data = world.get(entity, comp) as { enabled: boolean };
- entitySaved.set(comp, data.enabled);
- if (data.enabled) {
- data.enabled = false;
- world.set(entity, comp, data);
+ const data = world.get(entity, comp) as Record<string, unknown>;
+ const wasEnabled = data[comp.renderableField] !== false;
+ entitySaved.set(comp, wasEnabled);
+ if (wasEnabled) {
+ data[comp.renderableField] = false;
+ world.set(entity, comp, data as never);
}
}
}
@@ -679,9 +681,9 @@ export class SceneManagerState {
if (!entitySaved) continue;
for (const [comp, wasEnabled] of entitySaved) {
if (world.has(entity, comp)) {
- const data = world.get(entity, comp) as { enabled: boolean };
- data.enabled = wasEnabled;
- world.set(entity, comp, data);
+ const data = world.get(entity, comp) as Record<string, unknown>;
+ data[comp.renderableField] = wasEnabled;
+ world.set(entity, comp, data as never);
}
}
}
diff --git a/sdk/src/ui/core/text.ts b/sdk/src/ui/core/text.ts
index f7646d5af..5d207e90c 100644
--- a/sdk/src/ui/core/text.ts
+++ b/sdk/src/ui/core/text.ts
@@ -116,6 +116,10 @@ export const Text = defineComponent<TextData>('Text', {
layer: 0,
enabled: true,
}, {
+ // Text draws itself (the plugin skips a disabled one) rather than through a
+ // sibling UIVisual, so hiding an entity has to reach this flag — the same
+ // declaration the C++ renderables make at their ES_COMPONENT site.
+ renderableField: 'enabled',
// A shipped font is a real asset reference: declaring it here is what gives
// it dependency tracking, cook inclusion, `@uuid:` refs and hot-update for
// free — the same machinery every other asset slot rides.
diff --git a/sdk/src/ui/input/interactable.ts b/sdk/src/ui/input/interactable.ts
index 2935e78a3..6e25ebfa6 100644
--- a/sdk/src/ui/input/interactable.ts
+++ b/sdk/src/ui/input/interactable.ts
@@ -31,13 +31,14 @@ export interface UIInteractionData {
}
// Per-frame pointer state written by the hit-test system — never authored,
-// never persisted. The hit-test getOrEmplaces it on demand.
+// never persisted. The hit-test getOrEmplaces it on demand. `transient` is
+// declared at the C++ ES_COMPONENT site and arrives through COMPONENT_META.
export const UIInteraction = defineBuiltin<UIInteractionData>('UIInteraction', {
hovered: false,
pressed: false,
justPressed: false,
justReleased: false,
-}, { transient: true });
+});
export interface WidgetInteractionInit {
/** Start disabled (Interactable.enabled = false). */
diff --git a/sdk/tests/entity-visibility.test.ts b/sdk/tests/entity-visibility.test.ts
index 8506b6234..c830f5834 100644
--- a/sdk/tests/entity-visibility.test.ts
+++ b/sdk/tests/entity-visibility.test.ts
@@ -1,10 +1,18 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeAll } from 'vitest';
import { setEntityVisible, isEntityVisible, hasVisibility, setEntityActive, isEntityActive } from '../src/ecs/entityUtils';
+import { ensureBuiltinComponentsRegistered, defineComponent, unregisterComponent } from '../src/ecs/component';
import { UIDisplay } from '../src/ui/core/ui-node';
describe('Entity visibility helpers', () => {
+ // Which components visibility reaches comes from the REGISTRY, so it has to be
+ // populated — the app entry does this; a unit test importing one leaf module
+ // must do it too.
+ beforeAll(() => {
+ ensureBuiltinComponentsRegistered();
+ });
+
const mockWorld = () => {
const components = new Map<string, any>();
const key = (comp: any) => comp._name ?? comp.name;
@@ -56,19 +64,78 @@ describe('Entity visibility helpers', () => {
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) => {
+ // The declaration's coverage, not a second copy of it: a component missing
+ // its `renderable=<field>` is a silent no-op here, and the entity keeps
+ // drawing after it was hidden.
+ it.each([
+ ['SpineAnimation', 'enabled'],
+ ['DragonBonesAnimation', 'enabled'],
+ ['ParticleEmitter', 'enabled'],
+ ['UIVisual', 'enabled'],
+ ['Mesh2D', 'enabled'],
+ ['TrailRenderer', 'enabled'],
+ // Not drawn, but hiding an entity has to stop it lighting the scene.
+ ['Light2D', 'enabled'],
+ ['ShadowCaster2D', 'enabled'],
+ // Its flag is `visible`, not `enabled` — which is why the declaration
+ // names the field instead of assuming one.
+ ['TilemapLayer', 'visible'],
+ ])('hides a %s through its %s flag', (comp, flag) => {
const world = mockWorld();
- world._components.set(comp, { enabled: true });
+ world._components.set(comp, { [flag]: true });
expect(isEntityVisible(world, 1 as any)).toBe(true);
setEntityVisible(world, 1 as any, false);
- expect(world._components.get(comp).enabled).toBe(false);
+ expect(world._components.get(comp)[flag]).toBe(false);
expect(isEntityVisible(world, 1 as any)).toBe(false);
});
+ // The discrimination the declaration buys: plenty of components carry an
+ // `enabled` field without drawing anything, and hiding an entity must not
+ // switch its physics off.
+ it.each(['BoxCollider', 'RigidBody', 'UIScroll'])('leaves a non-renderable %s alone', (comp) => {
+ const world = mockWorld();
+ world._components.set('Sprite', { enabled: true });
+ world._components.set(comp, { enabled: true });
+
+ setEntityVisible(world, 1 as any, false);
+ expect(world._components.get('Sprite').enabled).toBe(false);
+ expect(world._components.get(comp).enabled).toBe(true);
+ expect(hasVisibility(world, 1 as any)).toBe(true);
+ });
+
+ it('a non-renderable alone is not something that can be hidden', () => {
+ const world = mockWorld();
+ world._components.set('BoxCollider', { enabled: true });
+ expect(hasVisibility(world, 1 as any)).toBe(false);
+ });
+
+ // Derived per call (memoised on the registry), not snapshotted at load — a
+ // project's own component registers long after the engine's. Asking first
+ // is deliberate: it primes the memo.
+ it('reaches a component registered after the first answer', () => {
+ const world = mockWorld();
+ world._components.set('Radar', { shown: true });
+ expect(hasVisibility(world, 1 as any)).toBe(false);
+
+ defineComponent('Radar', { shown: true, range: 10 }, { renderableField: 'shown' });
+ try {
+ expect(hasVisibility(world, 1 as any)).toBe(true);
+ setEntityVisible(world, 1 as any, false);
+ expect(world._components.get('Radar').shown).toBe(false);
+ } finally {
+ unregisterComponent('Radar');
+ }
+ expect(hasVisibility(world, 1 as any)).toBe(false);
+ });
+
+ it('refuses a renderableField that names no boolean field', () => {
+ expect(() => defineComponent('Beacon', { lit: true }, { renderableField: 'visible' }))
+ .toThrow(/renderableField "visible" is not a boolean field/);
+ expect(() => defineComponent('Beacon2', { lit: 3 }, { renderableField: 'lit' }))
+ .toThrow(/is not a boolean field/);
+ });
+
it('hides every renderer the entity carries', () => {
const world = mockWorld();
world._components.set('Sprite', { enabled: true });
diff --git a/sdk/tests/sceneManager.test.ts b/sdk/tests/sceneManager.test.ts
index 5f4e74d68..7fdb221dc 100644
--- a/sdk/tests/sceneManager.test.ts
+++ b/sdk/tests/sceneManager.test.ts
@@ -43,17 +43,26 @@ vi.mock('../src/ecs/resource', () => ({
})),
}));
-vi.mock('../src/ecs/component', () => ({
- SceneOwner: Symbol('SceneOwner'),
- Disabled: { _id: Symbol('Disabled'), _name: 'Disabled', _builtin: false, _default: {} },
- Sprite: Symbol('Sprite'),
- SpineAnimation: Symbol('SpineAnimation'),
- BitmapText: Symbol('BitmapText'),
- ShapeRenderer: Symbol('ShapeRenderer'),
- ParticleEmitter: Symbol('ParticleEmitter'),
- defineBuiltin: (name: string, defaults: unknown) => Symbol(name),
- defineTag: (name: string) => ({ _id: Symbol(name), _name: name, _builtin: false, _default: {} }),
-}));
+// Renderables carry the field that gates them, because sleep/wake writes THAT
+// field — TilemapLayer's is `visible`, not `enabled`. Everything is built inside
+// the factory: vi.mock is hoisted above this file's own top-level statements.
+vi.mock('../src/ecs/component', () => {
+ const def = (name: string, renderableField = 'enabled') => ({
+ _id: Symbol(name), _name: name, _builtin: true, renderableField,
+ });
+ const renderables = [
+ def('Sprite'), def('SpineAnimation'), def('BitmapText'),
+ def('ShapeRenderer'), def('ParticleEmitter'), def('TilemapLayer', 'visible'),
+ ];
+ return {
+ SceneOwner: Symbol('SceneOwner'),
+ Disabled: { _id: Symbol('Disabled'), _name: 'Disabled', _builtin: false, _default: {} },
+ ...Object.fromEntries(renderables.map((d) => [d._name, d])),
+ renderableComponents: () => renderables,
+ defineBuiltin: (name: string, defaults: unknown) => Symbol(name),
+ defineTag: (name: string) => ({ _id: Symbol(name), _name: name, _builtin: false, _default: {} }),
+ };
+});
vi.mock('../src/asset/AssetPlugin', () => ({
Assets: Symbol('Assets'),
@@ -67,7 +76,7 @@ vi.mock('../src/defaults', () => ({
}));
import { SceneManagerState, SceneLoadCancelled, wrapSceneSystem } from '../src/scene/sceneManager';
-import { SceneOwner, Sprite, SpineAnimation, BitmapText } from '../src/ecs/component';
+import { SceneOwner, Sprite, SpineAnimation, BitmapText, TilemapLayer } from '../src/ecs/component';
import { loadSceneWithAssets } from '../src/scene/scene';
import { registerDrawCallback, unregisterDrawCallback } from '../src/render/customDraw';
import { PostProcess } from '../src/postprocess';
@@ -574,6 +583,26 @@ describe('SceneManager', () => {
expect(bt.enabled).toBe(true);
});
+ // A renderable whose gating flag is not called `enabled`. Sleep wrote a
+ // fixed `enabled` key, so a tilemap layer kept drawing in a slept scene —
+ // and a stray `enabled: false` was left on data that has no such field.
+ it('sleeps and wakes a renderable through its own flag name', async () => {
+ const entityMap = new Map([[100, 1]]);
+ vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
+ const layer = { visible: true, opacity: 1 };
+ app._entities.set(1, new Map([[TilemapLayer, layer]]));
+
+ manager.register({ name: 'level1', data: makeSceneData() });
+ await manager.load('level1');
+
+ manager.sleep('level1');
+ expect(layer.visible).toBe(false);
+ expect('enabled' in layer).toBe(false);
+
+ manager.wake('level1');
+ expect(layer.visible).toBe(true);
+ });
+
it('wake() only on sleeping scenes', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
diff --git a/sdk/tests/ui-node.test.ts b/sdk/tests/ui-node.test.ts
index 87c8e6939..a213d8a02 100644
--- a/sdk/tests/ui-node.test.ts
+++ b/sdk/tests/ui-node.test.ts
@@ -2,6 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect } from 'vitest';
import { UINode } from '../src/ui/core/ui-node';
+import { UIInteraction } from '../src/ui/input/interactable';
import { DimensionUnit } from '../src/ui/core/dimension';
import { getComponent } from '../src/ecs/component';
import { COMPONENT_META } from '../src/ecs/component.generated';
@@ -13,6 +14,15 @@ describe('UINode (REARCH_GUI F3)', () => {
expect(getComponent('UINode')).toBe(UINode);
});
+ // The sibling case, and the one that proves the C++ annotation reaches the
+ // registry: UIInteraction is per-frame pointer state that scene save must
+ // omit, declared `ES_COMPONENT(transient)` and nowhere else.
+ it('UIInteraction is transient, declared in C++ rather than at the TS call site', () => {
+ expect(COMPONENT_META.UIInteraction?.transient).toBe(true);
+ expect(UIInteraction.transient).toBe(true);
+ expect(getComponent('UIInteraction')).toBe(UIInteraction);
+ });
+
it('defaults: size auto, margins 0px, CSS flex defaults', () => {
const d = UINode._default;
expect(d.width).toEqual({ value: 0, unit: DimensionUnit.Auto });
diff --git a/src/esengine/ecs/components/BitmapText.hpp b/src/esengine/ecs/components/BitmapText.hpp
index 2e80bf8d3..a137591de 100644
--- a/src/esengine/ecs/components/BitmapText.hpp
+++ b/src/esengine/ecs/components/BitmapText.hpp
@@ -18,7 +18,7 @@ enum class TextAlign : u8 {
Right
};
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct BitmapText {
ES_PROPERTY()
std::string text;
diff --git a/src/esengine/ecs/components/DragonBonesAnimation.hpp b/src/esengine/ecs/components/DragonBonesAnimation.hpp
index 17a04e4f7..2846df9b7 100644
--- a/src/esengine/ecs/components/DragonBonesAnimation.hpp
+++ b/src/esengine/ecs/components/DragonBonesAnimation.hpp
@@ -31,7 +31,7 @@
namespace esengine::ecs {
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct DragonBonesAnimation {
/** @brief Skeleton data (`*_ske.json` or `.dbbin`) */
ES_PROPERTY(asset = dragonbones_skeleton)
diff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hpp
index e2708a669..57b731ef7 100644
--- a/src/esengine/ecs/components/Light2D.hpp
+++ b/src/esengine/ecs/components/Light2D.hpp
@@ -47,7 +47,7 @@ enum class Light2DType : i32 {
* light.intensity = 1.0f;
* @endcode
*/
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct Light2D {
/** @brief Light kind: 0 = Point, 1 = Directional, 2 = Ambient (see Light2DType). */
ES_PROPERTY(enum=Light2DType, tooltip="Point, Directional, Ambient, or Spot.")
diff --git a/src/esengine/ecs/components/Mesh2D.hpp b/src/esengine/ecs/components/Mesh2D.hpp
index 2ec7e1ab3..b77d89fe2 100644
--- a/src/esengine/ecs/components/Mesh2D.hpp
+++ b/src/esengine/ecs/components/Mesh2D.hpp
@@ -42,7 +42,7 @@ struct MeshVertex2D {
// Mesh2D Component
// =============================================================================
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct Mesh2D {
/** @brief Texture sampled by the mesh UVs (invalid = untextured, vertex colors only) */
ES_PROPERTY(asset = texture)
diff --git a/src/esengine/ecs/components/ParticleEmitter.hpp b/src/esengine/ecs/components/ParticleEmitter.hpp
index dec3a28fe..d4f67c38b 100644
--- a/src/esengine/ecs/components/ParticleEmitter.hpp
+++ b/src/esengine/ecs/components/ParticleEmitter.hpp
@@ -43,7 +43,7 @@ enum class SubEmitterTrigger : i32 {
Birth = 1,
};
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct ParticleEmitter {
// Emission
ES_PROPERTY(min=0, category=Emission)
diff --git a/src/esengine/ecs/components/ShadowCaster2D.hpp b/src/esengine/ecs/components/ShadowCaster2D.hpp
index f97ec141d..8634a5494 100644
--- a/src/esengine/ecs/components/ShadowCaster2D.hpp
+++ b/src/esengine/ecs/components/ShadowCaster2D.hpp
@@ -22,7 +22,7 @@ namespace esengine::ecs {
/**
* @brief A 2D shadow occluder. The box is centered on the entity's world position.
*/
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct ShadowCaster2D {
/** @brief Occluder box size in world units (full width/height; centered on the Transform). */
ES_PROPERTY(animatable, min=0, tooltip="Occluder box size in world units (centered on the entity).")
diff --git a/src/esengine/ecs/components/ShapeRenderer.hpp b/src/esengine/ecs/components/ShapeRenderer.hpp
index 947ea4473..569afcf17 100644
--- a/src/esengine/ecs/components/ShapeRenderer.hpp
+++ b/src/esengine/ecs/components/ShapeRenderer.hpp
@@ -15,7 +15,7 @@ enum class ShapeType : u8 {
RoundedRect = 2,
};
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct ShapeRenderer {
ES_PROPERTY(enum=ShapeType)
u8 shapeType{0};
diff --git a/src/esengine/ecs/components/SpineAnimation.hpp b/src/esengine/ecs/components/SpineAnimation.hpp
index e2ff1dfea..008df4774 100644
--- a/src/esengine/ecs/components/SpineAnimation.hpp
+++ b/src/esengine/ecs/components/SpineAnimation.hpp
@@ -46,7 +46,7 @@ namespace esengine::ecs {
* spine.loop = true;
* @endcode
*/
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct SpineAnimation {
/** @brief Path to skeleton data file (.skel or .json) */
ES_PROPERTY(asset = spine_skeleton)
diff --git a/src/esengine/ecs/components/Sprite.hpp b/src/esengine/ecs/components/Sprite.hpp
index ffeda575a..2dc8cb180 100644
--- a/src/esengine/ecs/components/Sprite.hpp
+++ b/src/esengine/ecs/components/Sprite.hpp
@@ -43,7 +43,7 @@ namespace esengine::ecs {
* sprite.layer = 10; // Render on top
* @endcode
*/
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct Sprite {
/** @brief Texture resource handle (type-safe) */
ES_PROPERTY(asset = texture)
diff --git a/src/esengine/ecs/components/TilemapLayer.hpp b/src/esengine/ecs/components/TilemapLayer.hpp
index 860bab009..5421b82c4 100644
--- a/src/esengine/ecs/components/TilemapLayer.hpp
+++ b/src/esengine/ecs/components/TilemapLayer.hpp
@@ -45,7 +45,7 @@ enum class TilemapStaggerIndex : u8 {
* TilemapSystem's LayerData keyed by this entity. Chunks flow through
* tilemap_exportChunks / tilemap_importChunks during scene I/O.
*/
-ES_COMPONENT()
+ES_COMPONENT(renderable=visible)
struct TilemapLayer {
ES_PROPERTY()
glm::vec2 cellSize{32.0f, 32.0f};
diff --git a/src/esengine/ecs/components/TrailRenderer.hpp b/src/esengine/ecs/components/TrailRenderer.hpp
index a8198369c..f2d372521 100644
--- a/src/esengine/ecs/components/TrailRenderer.hpp
+++ b/src/esengine/ecs/components/TrailRenderer.hpp
@@ -35,7 +35,7 @@ namespace esengine::ecs {
// TrailRenderer Component
// =============================================================================
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct TrailRenderer {
// Trail — how long the streak lives and how densely it samples the path.
/** @brief Seconds each recorded point persists before fading out of the tail. */
diff --git a/src/esengine/ecs/components/UIInteraction.hpp b/src/esengine/ecs/components/UIInteraction.hpp
index a8759956c..172294087 100644
--- a/src/esengine/ecs/components/UIInteraction.hpp
+++ b/src/esengine/ecs/components/UIInteraction.hpp
@@ -7,7 +7,7 @@
namespace esengine::ecs {
-ES_COMPONENT()
+ES_COMPONENT(transient)
struct UIInteraction {
ES_PROPERTY()
bool hovered{false};
diff --git a/src/esengine/ecs/components/UIVisual.hpp b/src/esengine/ecs/components/UIVisual.hpp
index b13350cf9..5c53b0975 100644
--- a/src/esengine/ecs/components/UIVisual.hpp
+++ b/src/esengine/ecs/components/UIVisual.hpp
@@ -80,7 +80,7 @@ enum class UIVisualFit : u8 {
* `uvScale` are the base sub-region (identity = whole texture); Tiled/Filled
* derive their final UV from this base at draw time.
*/
-ES_COMPONENT()
+ES_COMPONENT(renderable=enabled)
struct UIVisual {
ES_PROPERTY()
UIVisualType visualType{UIVisualType::None};