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
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.mdxindex 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 writingdiff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdxindex 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.tsindex 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-字段' },