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(physics): layers are the single filter for collision, hit, and sensor events

yhh636e5f4d3cd8
diff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/guides/physics.mdx
index a9a4820e2..dff516267 100644
--- a/docs/astro/src/content/docs/guides/physics.mdx
+++ b/docs/astro/src/content/docs/guides/physics.mdx
@@ -104,6 +104,13 @@ const LAYER_GROUND = 0x0008;
});
```
+The layer filter is the **single** control for what interacts — collisions, hit
+events, and **sensor detection** all use it. Colliders don't need to opt in to be
+seen by a sensor: any collider whose layers pass the sensor's filter is detected.
+To keep something out of a sensor, exclude it by layer (not a per-collider flag);
+to keep sensor work cheap in a busy world, put sensors and their targets on
+dedicated layers so the mask narrows what each sensor considers.
+
## Moving bodies — forces & velocity
Read the `PhysicsAPI` resource to drive bodies. Every method takes the world entity:
diff --git a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx b/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
index aea56807e..f46ac1e24 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
@@ -99,6 +99,11 @@ const LAYER_GROUND = 0x0008;
});
```
+碰撞层是**唯一**的交互开关——碰撞、hit 事件、以及**传感器检测**都用它。碰撞体无需单独开启就能
+被传感器检测到:只要它的层通过了传感器的过滤,就会被检测。想让某物**不**触发某传感器,用层排除它
+(而不是某个 per-collider 开关);想在拥挤场景里降低传感器开销,把传感器和它的目标放到专门的层,
+用 mask 缩小每个传感器要考虑的范围。
+
## 移动刚体 —— 力与速度
读 `PhysicsAPI` 资源来驱动刚体。每个方法都取世界实体: