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: describe imported scene components and refresh reference data
yhh01c6f760253d
diff --git a/desktop b/desktopindex 1cd96fa3a..25b02f870 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 1cd96fa3a95f83852abe1e959d3ede863bf8129b+Subproject commit 25b02f870a7258686271666e25b3ebb01185bc96diff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdxindex 022c361de..d592461c9 100644--- a/docs/astro/src/content/docs/gameplay/physics-3d.mdx+++ b/docs/astro/src/content/docs/gameplay/physics-3d.mdx@@ -619,3 +619,17 @@ Press **J** to reverse their motors; **F1** toggles collider debug drawing. Seleeither joint in the editor to inspect its limits. Viewport limits are read-only;edit their numbers in Details. These components are experimental. Headless Joltchecks cover limits and motors; target-device acceptance is recorded separately.++## Imported compound colliders++`CompoundCollider3D` combines boxes, spheres and capsules into one native body on+the same entity as `RigidBody3D`. Each `parts` entry has a local `position` and+`rotation`, plus `halfExtents`, `radius` or capsule `halfHeight`. These dimensions+and offsets are in model units: the entity's composed scale places them in world+space before the physics unit conversion. Both Jolt and PhysX consume the same+component and packet layout.++Use finite positive placement scales. A rotated box or capsule under non-uniform+scale needs baked collision geometry; the component rejects that unsupported+case instead of creating a mismatched shape. Mesh and convex colliders also apply+the model's composed scale to their source vertices.diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdxindex dc3c8dd60..582c1fa6b 100644--- a/docs/astro/src/content/docs/world/particles.mdx+++ b/docs/astro/src/content/docs/world/particles.mdx@@ -643,6 +643,18 @@ without WebGPU matters to you.- In game code particles advance in **play mode**; in the editor the **PreviewFX** toggle keeps them live while you author.+## Imported particle units++`ParticleModelUnits` preserves an imported emitter's size ranges, speed ranges+and gravity in model units. With this component beside `ParticleEmitter`, the+particle plugin multiplies those values by the largest absolute axis of the+composed world scale, including parent scale. Emitter position still follows+`Transform`. This is a scalar conversion for world-space particles, not an+anisotropic particle simulation.++Edit the values on `ParticleModelUnits` when changing these imported properties:+the plugin derives the corresponding `ParticleEmitter` fields from them.+## See also- [Materials & Shaders](/docs/graphics/materials/) — custom particle materials.diff --git a/docs/astro/src/content/docs/world/scenes.mdx b/docs/astro/src/content/docs/world/scenes.mdxindex 9dd3349bd..e623d8f88 100644--- a/docs/astro/src/content/docs/world/scenes.mdx+++ b/docs/astro/src/content/docs/world/scenes.mdx@@ -339,6 +339,18 @@ the owning plugin (see `tilemapPlugin`) does it at startup.[persistent](#persistent-entities), or because nothing owns it (a leak).</Aside>+## Imported node visibility++`NodeVisibility.visible` is an animatable gate over a visual subtree. Setting it+to `false` masks the registered renderer flags of the entity and its descendants;+showing it again restores their authored flags. Scene serialization preserves+those authored values while the gate is closed. Cameras, physics bodies and+gameplay entities remain active.++For particle emitters the registered flag is `enabled`, so hiding such a subtree+also affects its particle simulation. Put an emitter outside the hidden visual+subtree when it must continue running independently.+## See also- [Prefabs](/docs/world/prefabs/) — spawn reusable entity trees within a scene.diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdxindex fb02a6291..83bb25593 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx@@ -532,3 +532,14 @@ Inspector 以度显示角度,文件和脚本仍存弧度。平移限位、线现有 **3D Physics** 示例包含肩/上臂和受限滑块。按 **J** 反转马达,**F1** 切换碰撞体调试绘制。在编辑器选中关节即可检查限位;视口提供只读显示,通过细节面板改数值。两种组件仍为实验性接口。无窗口 Jolt 检查覆盖限位和马达,目标设备验收另行记录。++## 导入的复合碰撞体++`CompoundCollider3D` 将多个盒体、球体和胶囊体组成一个原生刚体,与+`RigidBody3D` 放在同一实体上。`parts` 的每项包含局部 `position`、`rotation`,+以及 `halfExtents`、`radius` 或胶囊圆柱段的 `halfHeight`。这些尺寸和偏移采用+模型单位:先应用实体合成后的世界缩放,再换算为物理单位。Jolt 与 PhysX+共享同一组件和数据包格式。++放置缩放必须为有限正数。非均匀缩放下带旋转的盒体或胶囊需要预先烘焙碰撞几何;+组件会明确拒绝该情况。网格和凸包碰撞体也会将模型的合成缩放应用到源顶点。diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdxindex aaddc20d9..31a08aa47 100644--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx@@ -585,6 +585,16 @@ world.insert(entity, ParticleEmitter, {- **复用发射器**:用 `reset` + `play` 而不是生成/销毁。- 游戏代码里粒子在**播放模式**推进;编辑器里 **Preview FX** 开关让它们在创作时保持鲜活。+## 导入粒子的单位++`ParticleModelUnits` 保存导入发射器在模型单位下的尺寸范围、速度范围和重力。+与 `ParticleEmitter` 同时存在时,粒子插件会将这些值乘以合成世界缩放中绝对值+最大的轴,其中包含父实体缩放。发射位置仍跟随 `Transform`。这是世界空间粒子的+统一尺度换算,不是按各轴分别缩放的粒子模拟。++修改这些导入属性时,应编辑 `ParticleModelUnits`;插件会据此更新对应的+`ParticleEmitter` 字段。+## 参见- [材质与着色器](/docs/zh-cn/graphics/materials/) —— 自定义粒子材质。diff --git a/docs/astro/src/content/docs/zh-cn/world/scenes.mdx b/docs/astro/src/content/docs/zh-cn/world/scenes.mdxindex 2e1825083..c5b84fe9e 100644--- a/docs/astro/src/content/docs/zh-cn/world/scenes.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/scenes.mdx@@ -287,6 +287,15 @@ registerSceneComponentCodec('MyVoxelChunk', {要么根本没人拥有它(那是泄漏)。</Aside>+## 导入节点的可见性++`NodeVisibility.visible` 是可动画控制的子树可见性开关。设为 `false` 时,+它会屏蔽本实体与后代实体已注册的渲染开关;重新显示时恢复原有设置。+即使当前隐藏,场景序列化仍保存原有渲染设置。摄像机、物理刚体和玩法实体继续运行。++粒子发射器注册的开关是 `enabled`,因此隐藏包含发射器的子树也会影响粒子模拟。+需要独立继续播放的发射器,应放在这棵隐藏的可视子树之外。+## 参见- [预制体](/docs/zh-cn/world/prefabs/) —— 在场景内生成可复用的实体树。diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 550f42f13..2dd5afd66 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 115,"beta": 176,- "experimental": 2853,+ "experimental": 2858,"deprecated": 3},- "total": 3144,+ "total": 3149,"subsystems": [{"id": "mobile-controls",diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.tsindex 694c9e4ab..eef8f919e 100644--- a/docs/astro/src/data/componentDocs.ts+++ b/docs/astro/src/data/componentDocs.ts@@ -51,6 +51,7 @@ export const CATEGORY_LABELS: Record<ComponentCategory, string> = {export const COMPONENT_DOCS: Record<string, ComponentDoc> = {// ── Core ───────────────────────────────────────────────────────────────────+ NodeVisibility: { category: 'core', summary: 'An animatable visual gate for an entity subtree that preserves authored renderer flags; particle emitters use their enabled flag while hidden.', doc: 'world/scenes' },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 UI lays out and draws children in, and what hierarchy-order layers stack by.", doc: 'core-concepts/transforms', anchor: 'parenting--hierarchy', anchorZh: '父子层级' },@@ -161,6 +162,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {PolygonCollider2D: { category: 'physics', summary: 'A convex polygon collision shape from your own points.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },ChainCollider2D: { category: 'physics', summary: 'A polyline of edges — open or looped — for static terrain.', doc: 'gameplay/physics', anchor: 'colliders', anchorZh: '碰撞体' },RigidBody3D: { category: 'physics', summary: 'Puts the entity under the 3D solver — its own component set, so a 2D scene keeps the world it already has.', doc: 'gameplay/physics-3d', anchor: 'bodies', anchorZh: '刚体' },+ CompoundCollider3D: { category: 'physics', summary: 'Boxes, spheres and capsules with local positions and rotations, combined into one native rigid body using the model placement scale.', doc: 'gameplay/physics-3d' },BoxCollider3D: { category: 'physics', summary: 'A box collision shape in 3D. Half-extents are in world units.', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: '形状' },SphereCollider3D: { category: 'physics', summary: 'A sphere collision shape in 3D.', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: '形状' },CapsuleCollider3D: { category: 'physics', summary: 'An upright capsule — what a 3D character is. Total height is 2*(halfHeight + radius).', doc: 'gameplay/physics-3d', anchor: 'shapes', anchorZh: '形状' },@@ -207,6 +209,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {// ── World ──────────────────────────────────────────────────────────────────Tilemap: { category: 'world', summary: 'A Tiled map asset projected into the scene; the engine derives one layer entity per map layer.', doc: 'world/tilemaps', anchor: 'load-a-tiled-map', anchorZh: '加载-tiled-地图' },TilemapLayer: { category: 'world', summary: 'One layer of tiles — its tileset, cell size, orientation, sorting and collision.', doc: 'world/tilemaps', anchor: 'the-tilemaplayer-component', anchorZh: 'tilemaplayer-组件' },+ ParticleModelUnits: { category: 'world', summary: 'Imported particle sizes, speeds and gravity in model units; the particle plugin applies the largest absolute world-scale axis to the emitter.', doc: 'world/particles' },ParticleEmitter: { category: 'world', summary: 'A particle system: emission, lifetime, shape, forces, noise, colour and size over life, sub-emitters and trails.', doc: 'world/particles', anchor: 'particleemitter-reference', anchorZh: 'particleemitter-字段参考' },ParticleForceField: { category: 'world', summary: 'A field that pushes particles around — point, directional, vortex or drag.', doc: 'world/particles', anchor: 'force-fields', anchorZh: '力场' },Marker: { category: 'world', summary: 'A named point or region of gameplay interest — spawn point, waypoint, trigger zone — queryable like any component.', doc: 'gameplay/markers', anchor: 'marker-component-reference', anchorZh: 'marker-组件参考' },diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 54f700a7b..06af68079 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -1163,6 +1163,47 @@"moving"]},+ {+ "name": "CompoundCollider3D",+ "source": "ts",+ "fields": [+ {+ "key": "parts",+ "type": "array",+ "default": "empty"+ },+ {+ "key": "friction",+ "type": "number",+ "default": "0.3"+ },+ {+ "key": "restitution",+ "type": "number",+ "default": "0"+ },+ {+ "key": "isSensor",+ "type": "boolean",+ "default": "false"+ },+ {+ "key": "mass",+ "type": "number",+ "default": "1"+ },+ {+ "key": "enabled",+ "type": "boolean",+ "default": "true"+ }+ ],+ "animatable": [+ "friction",+ "restitution",+ "mass"+ ]+ },{"name": "ContentRect","source": "cpp",@@ -3764,6 +3805,20 @@"fields": [],"tag": true},+ {+ "name": "NodeVisibility",+ "source": "ts",+ "fields": [+ {+ "key": "visible",+ "type": "boolean",+ "default": "true"+ }+ ],+ "animatable": [+ "visible"+ ]+ },{"name": "Occluder","source": "cpp",@@ -4359,6 +4414,58 @@}]},+ {+ "name": "ParticleModelUnits",+ "source": "ts",+ "fields": [+ {+ "key": "startSizeMin",+ "type": "number",+ "default": "1"+ },+ {+ "key": "startSizeMax",+ "type": "number",+ "default": "1"+ },+ {+ "key": "endSizeMin",+ "type": "number",+ "default": "1"+ },+ {+ "key": "endSizeMax",+ "type": "number",+ "default": "1"+ },+ {+ "key": "speedMin",+ "type": "number",+ "default": "0"+ },+ {+ "key": "speedMax",+ "type": "number",+ "default": "0"+ },+ {+ "key": "gravity",+ "type": "Vec3",+ "default": "(0, 0, 0)"+ }+ ],+ "animatable": [+ "startSizeMin",+ "startSizeMax",+ "endSizeMin",+ "endSizeMax",+ "speedMin",+ "speedMax",+ "gravity.x",+ "gravity.y",+ "gravity.z"+ ]+ },{"name": "PathFollower","source": "ts",