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.

docs(components): Name, Disabled and RuntimeOnly were documented nowhere

yhhe0392e421ea8
diff --git a/docs/astro/src/content/docs/core-concepts/components.mdx b/docs/astro/src/content/docs/core-concepts/components.mdx
index d7f7f65ea..36e68a48a 100644
--- a/docs/astro/src/content/docs/core-concepts/components.mdx
+++ b/docs/astro/src/content/docs/core-concepts/components.mdx
@@ -75,13 +75,32 @@ for per-frame runtime state), and `replicatedFields` (synced by
## Built-in components
-The SDK ships ~30 engine components you query alongside your own — `Transform`,
+The engine registers 77 components you query alongside your own — `Transform`,
`Sprite`, `ShapeRenderer`, `Camera`, `Light2D`, `ParticleEmitter`,
`SpineAnimation`, `TilemapLayer`, the UI set, the physics colliders, and more.
-Each is documented in its subsystem guide:
-[Sprites & Rendering](/docs/graphics/sprites/), [Camera](/docs/graphics/camera/),
-[2D Lighting](/docs/graphics/lighting/), [Physics](/docs/gameplay/physics/),
-[Tilemaps](/docs/world/tilemaps/), [UI](/docs/ui/overview/).
+Each subsystem guide teaches the ones it owns; the
+[component reference](/docs/reference/components/core/) lists every one of them
+with its fields, types and authoring defaults, derived from the same registry the
+editor's Details panel reads.
+
+### The ones the engine reads about your entities
+
+Four of them carry no subsystem of their own — they are how the engine and the
+editor describe an entity to themselves, and you will meet them in the Outliner
+and in scene files before you ever query them.
+
+| Component | What it is |
+|---|---|
+| `Name` | The entity's display name — what the World Outliner shows and what name lookups resolve against. |
+| `Parent` / `Children` | The hierarchy. The engine keeps the pair in step; see [Transforms](/docs/core-concepts/transforms/#parenting--hierarchy). |
+| `Disabled` | A tag. `setEntityActive(entity, false)` adds it and `isEntityActive` is simply its absence, so "active" is a question about one component rather than a flag to keep in sync. |
+| `RuntimeOnly` | A tag for an entity a system *derives* rather than one you authored — the layer entities a `Tilemap` projects, runtime tile colliders. Scene saving skips them, because persisting a derived entity would duplicate it against the next derivation. |
+
+Both tags are ordinary components: query them with `.with(Disabled)` /
+`.without(Disabled)` like any other, and add or remove them directly if you
+prefer that to `setEntityActive`. Note that the Outliner's eye is a *different*
+thing — an edit-time visibility fold that never touches `Disabled`, so hiding an
+entity while you work does not change what the running game does with it.
## Reading and writing
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 ba1f1f9ff..c13d95892 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
@@ -70,12 +70,27 @@ const Turret = defineComponent('Turret', {
## 内置组件
-SDK 自带约 30 个引擎组件,与你自己的组件一起查询——`Transform`、`Sprite`、
+引擎注册了 77 个组件,与你自己的组件一起查询——`Transform`、`Sprite`、
`ShapeRenderer`、`Camera`、`Light2D`、`ParticleEmitter`、`SpineAnimation`、
-`TilemapLayer`、UI 组件族、物理碰撞体等等。各自在对应的子系统指南里有完整文档:
-[精灵与渲染](/docs/zh-cn/graphics/sprites/)、[相机](/docs/zh-cn/graphics/camera/)、
-[2D 光照](/docs/zh-cn/graphics/lighting/)、[物理](/docs/zh-cn/gameplay/physics/)、
-[瓦片地图](/docs/zh-cn/world/tilemaps/)、[UI](/docs/zh-cn/ui/overview/)。
+`TilemapLayer`、UI 组件族、物理碰撞体等等。每个子系统指南讲它自己那一批;
+[组件参考](/docs/zh-cn/reference/components/core/)则逐个列出全部组件的字段、类型与
+创作默认值——数据来自编辑器 Details 面板读的同一份注册表。
+
+### 引擎用来描述实体的那几个
+
+有四个不属于任何子系统——它们是引擎和编辑器用来描述一个实体本身的方式,你在 Outliner
+里和场景文件里遇到它们,会远早于你去查询它们。
+
+| 组件 | 是什么 |
+|---|---|
+| `Name` | 实体的显示名——World Outliner 显示的就是它,按名字查找也解析到它。 |
+| `Parent` / `Children` | 层级关系。引擎保证这一对同步;见[变换](/docs/zh-cn/core-concepts/transforms/#父子层级)。 |
+| `Disabled` | 一个标签。`setEntityActive(entity, false)` 加上它,而 `isEntityActive` 就是「它不在」——所以「是否激活」是关于一个组件的问题,而不是一个要额外同步的标志位。 |
+| `RuntimeOnly` | 标记一个由系统**派生**出来、而非你手工创作的实体——`Tilemap` 投影出的层实体、运行时瓦片碰撞体。场景保存会跳过它们,因为把派生实体存下来,会在下一次派生时变成重复。 |
+
+这两个标签都是普通组件:像别的组件一样用 `.with(Disabled)` / `.without(Disabled)` 查询,
+你也可以直接增删它们而不走 `setEntityActive`。注意 Outliner 的眼睛是**另一回事**——那是
+编辑期的可见性折叠,完全不碰 `Disabled`,所以编辑时把实体藏起来不会改变运行中的游戏。
## 读取与写入
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index 22c38b2f2..dcee81dd2 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -54,11 +54,11 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
Transform: { category: 'core', summary: 'Position, rotation and scale — plus the read-only world-space values the engine composes down the parent chain.', doc: 'core-concepts/transforms', anchor: 'the-transform-component', anchorZh: 'transform-组件' },
Parent: { category: 'core', summary: 'The entity this one hangs under. The engine keeps it and `Children` in step; set it through the hierarchy API.', doc: 'core-concepts/transforms', anchor: 'parenting--hierarchy', anchorZh: '父子层级' },
Children: { category: 'core', summary: "The entity's children, maintained by the engine alongside `Parent`. Its order is the order children draw in.", doc: 'core-concepts/transforms', anchor: 'parenting--hierarchy', anchorZh: '父子层级' },
- Name: { category: 'core', summary: "The entity's display name — what the World Outliner shows and what name lookups resolve against.", doc: null },
+ Name: { category: 'core', summary: "The entity's display name — what the World Outliner shows and what name lookups resolve against.", doc: 'core-concepts/components', anchor: 'the-ones-the-engine-reads-about-your-entities', anchorZh: '引擎用来描述实体的那几个' },
Velocity: { category: 'core', summary: 'Constant linear and angular motion applied every frame, with no physics body involved.', doc: 'scripting/overview', anchor: 'constant-motion-the-velocity-component', anchorZh: '匀速运动velocity-组件' },
SceneOwner: { category: 'core', summary: 'Which additively-loaded scene owns the entity, and whether it survives that scene being unloaded.', doc: 'world/scenes', anchor: 'persistent-entities', anchorZh: '持久化实体' },
- Disabled: { category: 'core', summary: 'Tag added by `setEntityActive(false)`: an entity counts as active exactly while it is absent.', doc: null },
- RuntimeOnly: { category: 'core', summary: 'Tag for a world-only derived entity (the layers a `Tilemap` projects, runtime tile colliders). Scene saves skip it, because persisting one would duplicate it against the next derivation.', doc: null },
+ Disabled: { category: 'core', summary: 'Tag added by `setEntityActive(false)`: an entity counts as active exactly while it is absent.', doc: 'core-concepts/components', anchor: 'the-ones-the-engine-reads-about-your-entities', anchorZh: '引擎用来描述实体的那几个' },
+ RuntimeOnly: { category: 'core', summary: 'Tag for a world-only derived entity (the layers a `Tilemap` projects, runtime tile colliders). Scene saves skip it, because persisting one would duplicate it against the next derivation.', doc: 'core-concepts/components', anchor: 'the-ones-the-engine-reads-about-your-entities', anchorZh: '引擎用来描述实体的那几个' },
// ── Graphics ───────────────────────────────────────────────────────────────
Sprite: { category: 'graphics', summary: 'Draws a texture in the world — tint, size, pivot, sorting layer, flipping, tiling and parallax.', doc: 'graphics/sprites', anchor: 'sprite-fields', anchorZh: 'sprite-字段' },