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: describe imported scene components and refresh reference data

yhh01c6f760253d
diff --git a/desktop b/desktop
index 1cd96fa3a..25b02f870 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 1cd96fa3a95f83852abe1e959d3ede863bf8129b
+Subproject commit 25b02f870a7258686271666e25b3ebb01185bc96
diff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdx
index 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. Sele
either joint in the editor to inspect its limits. Viewport limits are read-only;
edit their numbers in Details. These components are experimental. Headless Jolt
checks 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.mdx
index 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 **Preview
FX** 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.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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.json
index 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.ts
index 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.json
index 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",