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: cover collision layers and Markers/Trigger Areas (en + zh)

yhhe01ef4178657
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index e2994f8b5..2305fcfb0 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -78,6 +78,7 @@ export default defineConfig({
{ label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'guides/input' },
{ label: 'Camera', translations: { 'zh-CN': '相机' }, slug: 'guides/camera' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
+ { label: 'Markers & Trigger Areas', translations: { 'zh-CN': '标记与触发区' }, slug: 'guides/markers' },
{ label: 'Gameplay AI', translations: { 'zh-CN': '游戏 AI' }, slug: 'guides/ai' },
{ label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'guides/animation' },
{ label: 'Timeline', translations: { 'zh-CN': '时间轴' }, slug: 'guides/timeline' },
diff --git a/docs/astro/src/assets/guides/en/collision-palette.png b/docs/astro/src/assets/guides/en/collision-palette.png
new file mode 100644
index 000000000..c838e6c26
Binary files /dev/null and b/docs/astro/src/assets/guides/en/collision-palette.png differ
diff --git a/docs/astro/src/assets/guides/en/marker-inspector.png b/docs/astro/src/assets/guides/en/marker-inspector.png
new file mode 100644
index 000000000..154116940
Binary files /dev/null and b/docs/astro/src/assets/guides/en/marker-inspector.png differ
diff --git a/docs/astro/src/assets/guides/zh/collision-palette.png b/docs/astro/src/assets/guides/zh/collision-palette.png
new file mode 100644
index 000000000..f87c906d3
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/collision-palette.png differ
diff --git a/docs/astro/src/assets/guides/zh/marker-inspector.png b/docs/astro/src/assets/guides/zh/marker-inspector.png
new file mode 100644
index 000000000..0e0531a12
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/marker-inspector.png differ
diff --git a/docs/astro/src/content/docs/guides/markers.mdx b/docs/astro/src/content/docs/guides/markers.mdx
new file mode 100644
index 000000000..1d906c888
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/markers.mdx
@@ -0,0 +1,171 @@
+---
+title: Markers & Trigger Areas
+description: Place named gameplay points and trigger zones as real entities — spawn points, waypoints, doors, and sensor regions you author in the editor and read with Query(Marker).
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+A **Marker** is a named point of gameplay interest — a spawn point, a waypoint, a
+door, a pickup location — placed in the editor as a real ECS entity. A **Trigger
+Area** is a Marker plus a sensor collider: a region that fires overlap events when a
+body enters it. Together they are Estella's modern "object layer": instead of a
+parallel data structure you reach through a loader, gameplay objects are plain
+entities you select, edit in the Inspector, serialize with the scene, and read with
+`Query(Marker)`.
+
+## How it works
+
+A Marker is just the `Marker` component (a `type` string and a free-form
+`properties` map) on an entity that also has a `Transform`. On its own it's a
+point — the game asks "where do I spawn the player?" by querying markers of a given
+`type`. Add a static [`RigidBody`](/docs/guides/physics/) and a sensor collider and
+the same entity becomes a trigger zone; the **Trigger Area** preset wires all of
+that up for you.
+
+Because a Marker is pure ECS, there is nothing special to load or parse:
+
+- It **serializes** with the scene like any component.
+- It shows in the **Inspector**, including a key→value editor for its properties.
+- It's **`Query`-able** — one code path reads markers you placed by hand *and*
+ markers imported from a [Tiled](/docs/guides/tilemap/) `.tmj` object layer.
+
+The `type` vocabulary is entirely yours: `spawn`, `waypoint`, `door`, `chest`,
+`checkpoint` — the game defines what the strings mean.
+
+## Setup
+
+`Marker` lives in the main `esengine` barrel — no plugin needed to place or query
+one. A **Trigger Area** carries a sensor collider, so it needs [physics](/docs/guides/physics/):
+in the editor and web runtime the physics module loads automatically when a scene
+uses physics components; in a custom app, add the plugin yourself:
+
+```typescript
+import { PhysicsPlugin } from 'esengine/physics';
+
+app.addPlugin(new PhysicsPlugin('physics.js'));
+```
+
+## Place one in the editor
+
+**Create → Common → Marker** drops a named point at the scene origin; **Create →
+Physics → Trigger Area** drops a sensor region (Transform + static RigidBody + sensor
+BoxCollider + Marker). A Marker shows a **pin gizmo** in the viewport; a Trigger Area
+also draws its collider outline, which you shape with the same
+[collider gizmo](/docs/guides/physics/) as any other body.
+
+In the Inspector, set the marker's **Type** and add any number of custom
+**properties** (a key→value map — `targetScene: "level2"`, `team: "red"`, and so on).
+Both survive save/load and travel into the build.
+
+![The Marker component in the Inspector — a Type field and a key→value Properties map with an Add-property button](../../../assets/guides/en/marker-inspector.png)
+
+*A `spawn` marker in the Inspector: the **Type** drives `Query(Marker)`, and each
+**Properties** row is one entry of the free-form string→string map.*
+
+## Quick start
+
+Place a few Markers of type `spawn` in the editor, then read them at startup to
+position the player:
+
+```typescript
+import { defineSystem, Commands, Query, Marker, Transform } from 'esengine';
+
+// Runs once: find every spawn marker and place the player at the first one.
+const placePlayer = defineSystem([Commands(), Query(Marker, Transform)], (cmds, markers) => {
+ for (const [entity, marker, transform] of markers) {
+ if (marker.type !== 'spawn') continue;
+ cmds.spawn().insert(Transform, { position: { ...transform.position } });
+ // …then chain .insert(Player, {…}), .insert(Sprite, {…}), and so on.
+ break;
+ }
+});
+```
+
+`marker.properties` carries the per-marker data — read `marker.properties.targetScene`,
+`marker.properties.team`, and the like as plain strings.
+
+## `Marker` component reference
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `type` | string | `''` | Gameplay identity — the kind of marker (`spawn`, `waypoint`, `door`, …). `Query(Marker)` filters on it. Free-form; the game defines the vocabulary. |
+| `properties` | `Record<string, string>` | `{}` | Arbitrary per-marker data (`team`, `targetScene`, `event`, …), edited as a key→value map in the Inspector. Imported `.tmj` object properties land here too. |
+
+<Aside type="note">
+ `properties` values are **strings**. Parse them where you read them
+ (`Number(marker.properties.hp)`, `marker.properties.locked === 'true'`) — the
+ editor stores whatever you type.
+</Aside>
+
+## Trigger Areas
+
+A **Trigger Area** is the Create preset for a sensor region: a `Transform`, a static
+`RigidBody` (`bodyType: 0`), a `BoxCollider` with `isSensor: true`, and a `Marker`.
+Because the collider is a sensor it detects overlaps **without** a physical response —
+nothing bounces off a trigger; it just reports who entered.
+
+Read entries and exits from the `PhysicsEvents` resource. Each sensor event names the
+`sensorEntity` (the trigger) and the `visitorEntity` (the body that crossed it), so
+you can look up the trigger's `Marker` to decide what it does:
+
+```typescript
+import { defineSystem, Res, Query, Marker } from 'esengine';
+import { PhysicsEvents } from 'esengine/physics';
+
+const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, markers) => {
+ const markerOf = (e) => {
+ for (const [entity, marker] of markers) if (entity === e) return marker;
+ return null;
+ };
+ for (const s of events.sensorEnters) {
+ const m = markerOf(s.sensorEntity);
+ if (m?.type === 'door') loadScene(m.properties.targetScene);
+ if (m?.type === 'hazard') damage(s.visitorEntity, Number(m.properties.dps));
+ }
+ for (const s of events.sensorExits) { /* left the zone — clear an effect, etc. */ }
+});
+```
+
+Keep sensors cheap in a busy world by putting triggers and the bodies that should
+notice them on dedicated [collision layers](/docs/guides/physics/#collision-filtering),
+so each sensor's mask narrows what it considers. See
+[Collision & sensor events](/docs/guides/physics/#collision--sensor-events) for the
+full event surface.
+
+## Imported from Tiled
+
+When a [`Tilemap`](/docs/guides/tilemap/) loads a `.tmj` map, its **object layers**
+converge onto the same entities you author by hand — no separate structure to walk:
+
+| Tiled object | Becomes |
+|---|---|
+| **Point** | A `Marker` (its `type` = the Tiled class, its custom properties → `Marker.properties`). |
+| **Rectangle / ellipse / polygon / polyline** | A trigger **Region** — a `Marker` plus a matching sensor collider (or solid geometry when the object group is named `collision`). |
+| **Tile object** (has a gid) | A sprite child of the map. |
+
+So one `Query(Marker)` reads spawn points whether you dropped them in the Estella
+editor or drew them in Tiled. (Imported objects are re-derived from the `.tmj` on each
+load, so they exist in play mode only; hand-authored Markers are ordinary serialized
+entities.) The raw object-group data is still available through `getTilemapSource`
+if you need a shape's exact vertices.
+
+## Best practices
+
+- **Type by role, detail by properties.** A small, stable set of `type` values the
+ game switches on, with the variable data in `properties` — not a new `type` per
+ instance.
+- **Query once where you can.** Spawn points, waypoint graphs, and patrol routes are
+ usually read at scene start; cache the result instead of re-querying every frame.
+- **Reuse one marker vocabulary** across hand-authored scenes and imported Tiled maps
+ — the query code doesn't care where the marker came from.
+- **Trigger Areas are sensors** — for anything you want to *block* (a wall, a ledge),
+ paint a [collision layer](/docs/guides/tilemap/#collision-obstacle-layers) or use a
+ non-sensor collider instead.
+
+## See also
+
+- [Tilemaps](/docs/guides/tilemap/) — collision (obstacle) layers and Tiled object
+ layers that feed the same Markers.
+- [Physics](/docs/guides/physics/) — sensors, collision filtering, and the
+ `PhysicsEvents` resource behind Trigger Areas.
+- [Scenes](/docs/guides/scene/) — Markers and Trigger Areas serialize with the scene.
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index ada867f7f..0614ab673 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -1,6 +1,6 @@
---
title: Tilemaps
-description: The complete guide to tile layers — painting in the editor, loading Tiled maps, the Tilemap/TilemapLayer components, building and editing layers in code, multi-tileset layers, animation, infinite chunked maps, and collision.
+description: The complete guide to tile layers — painting in the editor, loading Tiled maps, the Tilemap/TilemapLayer components, building and editing layers in code, multi-tileset layers, animation, infinite chunked maps, collision, and paint-over-a-background collision layers.
---
import { Aside } from '@astrojs/starlight/components';
@@ -293,11 +293,67 @@ one collider per tile — and the tile properties `oneway` / `sensor` /
edit world or serialized.
</Aside>
+## Collision (obstacle) layers
+
+Not every level is a tileset. When your art is a **single background image** — a
+hand-painted room, an exported illustration — you still want walls, floors, and
+slopes the player collides with. A **collision layer** paints exactly that: a
+`TilemapLayer` that draws **nothing** and instead stamps collider cells over
+whatever is behind it.
+
+A collision layer is an ordinary tile layer whose tileset reference is the sentinel
+`builtin:collision` instead of an `.estileset`. That one change routes it to a fixed
+palette of collider brushes, so it reuses the whole painting pipeline you already
+know — brush / rectangle / fill tools, chunk storage, flip, and the greedy
+box-merge — with no second system to learn. At Play the painted cells spawn static
+colliders, exactly like per-tile collision.
+
+**Create → 2D → Collision Layer** (or the *New Collision Layer* command) makes one,
+seeds a 32 px grid, and opens the painter with the collision palette instead of a
+tileset.
+
+![The collision-brush palette — Solid, ramps, half-tiles, One-way, and Trigger brushes, with per-layer friction and bounce fields](../../../assets/guides/en/collision-palette.png)
+
+*The **collision palette** replaces the tileset: pick **Solid**, a **ramp** or
+**half-tile**, **One-way ↑**, or **Trigger**, then paint over your background. The
+**Friction** and **Bounce** fields set a physics material for the whole layer.*
+
+The brushes:
+
+| Brush | Cell | Use |
+|---|---|---|
+| **Solid** | Full box | Walls, floors, ceilings. Greedy-merged into large static colliders. |
+| **Ramp ◢ / ◣** | Triangle | 45° slopes rising to the right / left. |
+| **Half** (bottom / top / left / right) | Half box | Ledges, low walls, thin floors. |
+| **One-way ↑** | Solid-top box | Jump-through platforms — solid from above, pass-through from below. Flip to reorient it (a ceiling, a wall). |
+| **Trigger** | Sensor box | A non-solid region that fires overlap events — see [Markers & Trigger Areas](/docs/guides/markers/). |
+
+Paint them like tiles; the **collision overlay** draws exactly what Play will spawn.
+Each collision layer can also carry its own **physics material** (friction / bounce /
+density), applied to every cell it spawns — set it in the Inspector.
+
+<Aside type="note">
+ Collision layers spawn their colliders **at Play**, like tile and object collision —
+ the colliders are never in the edit world or serialized as entities. The painted
+ cells themselves *are* saved, in the layer's chunk data.
+</Aside>
+
+Gameplay code reads a collision layer through the same [collision
+queries](#tilemaps-api-reference) as any painted layer — `isTileSolid`,
+`tileCollisionAt`, `tileCollisionAtWorld` — so nothing downstream needs to know the
+cells came from the built-in palette.
+
## Object layers
-Tiled **object layers** (spawn points, triggers, region shapes) load with the map.
-Query them by the map's source path with `getTilemapSource` — each group carries its
-objects with position, size, `type` (Tiled's class), `shape`, and custom `properties`:
+Tiled **object layers** (spawn points, triggers, region shapes) load with the map. The
+modern way to read them is `Query(Marker)`: on load, point objects converge into
+[**Marker**](/docs/guides/markers/) entities and shape objects into **Trigger Area**
+regions — the very same entities you author by hand — so one query reads objects
+whether they came from Tiled or the Estella editor.
+
+The raw group data is still available by the map's source path with `getTilemapSource`
+— each group carries its objects with position, size, `type` (Tiled's class), `shape`,
+and custom `properties`:
```typescript
import { getTilemapSource } from 'esengine';
@@ -366,6 +422,8 @@ specially), and `tileCollisionAtWorld(...)` addresses in world pixels.
## See also
+- [Markers & Trigger Areas](/docs/guides/markers/) — place gameplay points and trigger
+ zones over your level as real, queryable entities.
- [Physics](/docs/guides/physics/) — tile colliders participate in the physics world.
- [Assets](/docs/guides/assets/) — loading `.tmj` maps and `.estileset` tilesets.
- [Scenes](/docs/guides/scene/) — tilemap layers serialize with the scene.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/markers.mdx b/docs/astro/src/content/docs/zh-cn/guides/markers.mdx
new file mode 100644
index 000000000..a26888d43
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/markers.mdx
@@ -0,0 +1,150 @@
+---
+title: 标记与触发区
+description: 把命名的玩法点位和触发区作为真实体铺进关卡——出生点、路点、门、传感区域,在编辑器里创建、用 Query(Marker) 读取。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+**Marker(标记)** 是一个命名的玩法关注点——出生点、路点、门、拾取位置——在编辑器里作为
+一个真实的 ECS 实体放置。**Trigger Area(触发区)** 则是 Marker 加一个传感器碰撞体:一块
+区域,当有刚体进入时触发重叠事件。二者合起来就是 Estella 现代的“对象层”:玩法对象不再是一个
+要经加载器读取的并行数据结构,而是你能选中、在 Inspector 里编辑、随场景序列化、用
+`Query(Marker)` 读取的普通实体。
+
+## 工作原理
+
+Marker 就是 `Marker` 组件(一个 `type` 字符串加一个自由形式的 `properties` 映射),挂在一个
+同时带 `Transform` 的实体上。单独存在时它是一个点——游戏通过查询某个 `type` 的标记来问“该在
+哪里生成玩家?”。给同一个实体加上一个静态 [`RigidBody`](/docs/zh-cn/guides/physics/) 和一个
+传感器碰撞体,它就变成一块触发区;**Trigger Area** 预设会替你把这些一次接好。
+
+因为 Marker 是纯 ECS,没有任何特殊的东西要加载或解析:
+
+- 它和任何组件一样**随场景序列化**。
+- 它出现在 **Inspector** 里,包括一个键→值属性编辑器。
+- 它**可 `Query`**——同一条代码路径既读你手工放置的标记,*也*读从
+ [Tiled](/docs/zh-cn/guides/tilemap/) `.tmj` 对象层导入的标记。
+
+`type` 的词汇完全由你定义:`spawn`、`waypoint`、`door`、`chest`、`checkpoint`——字符串的含义由
+游戏说了算。
+
+## 安装
+
+`Marker` 在主 `esengine` barrel 里——放置或查询它无需任何插件。**Trigger Area** 带一个传感器
+碰撞体,因此需要[物理](/docs/zh-cn/guides/physics/):在编辑器和 Web 运行时,当场景用到物理
+组件时物理模块会自动加载;在自定义 app 里,请自己加上插件:
+
+```typescript
+import { PhysicsPlugin } from 'esengine/physics';
+
+app.addPlugin(new PhysicsPlugin('physics.js'));
+```
+
+## 在编辑器里放置
+
+**Create → Common → Marker** 在场景原点放一个命名点;**Create → Physics → Trigger Area**
+放一块传感区域(Transform + 静态 RigidBody + 传感器 BoxCollider + Marker)。Marker 在视口里显示
+一个**图钉 gizmo**;Trigger Area 还会画出它的碰撞体轮廓,你用与任何其他刚体相同的
+[碰撞体 gizmo](/docs/zh-cn/guides/physics/) 来塑形。
+
+在 Inspector 里设置标记的 **Type**,并添加任意多个自定义 **properties**(一个键→值映射——
+`targetScene: "level2"`、`team: "red"` 等等)。二者都能存/读并进入构建。
+
+![Inspector 里的 Marker 组件——一个 Type 字段和一个键→值 Properties 映射,带“添加属性”按钮](../../../../assets/guides/zh/marker-inspector.png)
+
+*Inspector 里的一个 `spawn` 标记:**Type** 驱动 `Query(Marker)`,每一行 **Properties** 就是
+自由形式 string→string 映射里的一条。*
+
+## 快速上手
+
+在编辑器里放几个 `spawn` 类型的 Marker,然后在启动时读取它们来放置玩家:
+
+```typescript
+import { defineSystem, Commands, Query, Marker, Transform } from 'esengine';
+
+// 只跑一次:找到每个 spawn 标记,把玩家放到第一个上。
+const placePlayer = defineSystem([Commands(), Query(Marker, Transform)], (cmds, markers) => {
+ for (const [entity, marker, transform] of markers) {
+ if (marker.type !== 'spawn') continue;
+ cmds.spawn().insert(Transform, { position: { ...transform.position } });
+ // ……然后链式 .insert(Player, {…})、.insert(Sprite, {…}) 等等。
+ break;
+ }
+});
+```
+
+`marker.properties` 携带逐标记的数据——像读普通字符串一样读 `marker.properties.targetScene`、
+`marker.properties.team` 等等。
+
+## `Marker` 组件参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `type` | string | `''` | 玩法身份——标记的种类(`spawn`、`waypoint`、`door` 等)。`Query(Marker)` 据此筛选。自由形式,词汇由游戏定义。 |
+| `properties` | `Record<string, string>` | `{}` | 任意的逐标记数据(`team`、`targetScene`、`event` 等),在 Inspector 里作为键→值映射编辑。导入的 `.tmj` 对象属性也落到这里。 |
+
+<Aside type="note">
+ `properties` 的值都是**字符串**。在读取处自行解析(`Number(marker.properties.hp)`、
+ `marker.properties.locked === 'true'`)——编辑器存的是你键入的原文。
+</Aside>
+
+## 触发区(Trigger Areas)
+
+**Trigger Area** 是传感区域的 Create 预设:一个 `Transform`、一个静态 `RigidBody`
+(`bodyType: 0`)、一个 `isSensor: true` 的 `BoxCollider`,加一个 `Marker`。因为碰撞体是传感器,
+它检测重叠但**不产生**物理响应——没有东西会从触发区弹开;它只报告谁进来了。
+
+从 `PhysicsEvents` 资源读取进入与离开。每个传感事件都给出 `sensorEntity`(触发区)和
+`visitorEntity`(穿过它的刚体),于是你可以查出触发区的 `Marker` 来决定它做什么:
+
+```typescript
+import { defineSystem, Res, Query, Marker } from 'esengine';
+import { PhysicsEvents } from 'esengine/physics';
+
+const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, markers) => {
+ const markerOf = (e) => {
+ for (const [entity, marker] of markers) if (entity === e) return marker;
+ return null;
+ };
+ for (const s of events.sensorEnters) {
+ const m = markerOf(s.sensorEntity);
+ if (m?.type === 'door') loadScene(m.properties.targetScene);
+ if (m?.type === 'hazard') damage(s.visitorEntity, Number(m.properties.dps));
+ }
+ for (const s of events.sensorExits) { /* 离开区域——清除某个效果等 */ }
+});
+```
+
+在繁忙的世界里让传感器保持廉价:把触发区和应当感知它们的刚体放到专门的
+[碰撞层](/docs/zh-cn/guides/physics/#碰撞过滤)上,让每个传感器的掩码收窄它要考虑的范围。完整
+事件面见 [碰撞与传感事件](/docs/zh-cn/guides/physics/#碰撞与传感事件)。
+
+## 从 Tiled 导入
+
+当 [`Tilemap`](/docs/zh-cn/guides/tilemap/) 加载一张 `.tmj` 地图时,它的**对象层**汇聚到你
+手工创建的同一批实体上——没有单独的结构要遍历:
+
+| Tiled 对象 | 变成 |
+|---|---|
+| **点(Point)** | 一个 `Marker`(它的 `type` = Tiled 的 class,它的自定义属性 → `Marker.properties`)。 |
+| **矩形 / 椭圆 / 多边形 / 折线** | 一块触发 **Region**——一个 `Marker` 加一个匹配的传感器碰撞体(当对象组名为 `collision` 时则是实心几何体)。 |
+| **瓦片对象**(带 gid) | 地图的一个精灵子实体。 |
+
+于是一条 `Query(Marker)` 就能读到出生点,无论你是在 Estella 编辑器里放的还是在 Tiled 里画的。
+(导入的对象在每次加载时从 `.tmj` 重新派生,因此只在播放模式存在;手工创建的 Marker 是普通的
+序列化实体。)如果你需要某个形状的精确顶点,原始的对象组数据仍可经 `getTilemapSource` 取得。
+
+## 最佳实践
+
+- **用 type 表角色,用 properties 表细节。** 让游戏 switch 的 `type` 值保持小而稳定,把易变的
+ 数据放进 `properties`——不要给每个实例都起一个新 `type`。
+- **能查一次就查一次。** 出生点、路点图、巡逻路线通常在场景开始时读一次;缓存结果,别每帧重查。
+- **复用同一套标记词汇**,横跨手工创建的场景与导入的 Tiled 地图——查询代码不关心标记从哪来。
+- **Trigger Area 是传感器**——要*挡住*的东西(墙、台沿),请画一块
+ [碰撞层](/docs/zh-cn/guides/tilemap/#碰撞障碍层)或用非传感器碰撞体。
+
+## 参见
+
+- [瓦片地图](/docs/zh-cn/guides/tilemap/) —— 碰撞(障碍)层与喂给同一批 Marker 的 Tiled 对象层。
+- [物理](/docs/zh-cn/guides/physics/) —— 传感器、碰撞过滤,以及 Trigger Area 背后的 `PhysicsEvents` 资源。
+- [场景](/docs/zh-cn/guides/scene/) —— Marker 与 Trigger Area 随场景序列化。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
index 9a775a4c7..530427e11 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -257,11 +257,55 @@ Tiled 地图享受同等待遇:在 **Tiled 瓦片碰撞编辑器** 里画的形
生成——它们从不在编辑世界里,也不被序列化。
</Aside>
+## 碰撞(障碍)层
+
+不是每个关卡都用图集。当你的美术是**一张背景大图**——手绘的房间、导出的插画——你仍然
+希望角色能撞到墙、地板和斜坡。**碰撞层**画的正是这些:一个**什么都不渲染**的
+`TilemapLayer`,只在背后的图上盖碰撞格子。
+
+碰撞层就是一个普通瓦片层,只不过它的图集引用是哨兵值 `builtin:collision` 而非
+`.estileset`。这一处改动把它路由到一套固定的碰撞笔刷,于是它复用你已经熟悉的整条绘制
+管线——笔刷 / 矩形 / 填充工具、分块存储、翻转、贪心合并盒——没有第二套系统要学。播放时
+所画的格子生成静态碰撞体,与逐瓦片碰撞完全一样。
+
+**Create → 2D → Collision Layer**(或 *New Collision Layer* 命令)创建一个,预置 32px
+网格,并打开画笔面板——此时调色板是碰撞笔刷而非图集。
+
+![碰撞笔刷调色板——实心、斜坡、半砖、单向、触发器,以及逐层的摩擦力与弹性字段](../../../../assets/guides/zh/collision-palette.png)
+
+***碰撞调色板**取代了图集:挑 **实心**、一个**斜坡**或**半砖**、**单向 ↑** 或
+**触发器**,然后在背景上刷。**摩擦力** 和 **弹性** 字段为整个图层设一份物理材质。*
+
+笔刷:
+
+| 笔刷 | 格子 | 用途 |
+|---|---|---|
+| **Solid(实心)** | 整格盒 | 墙、地板、天花板。会被贪心合并成大的静态碰撞体。 |
+| **Ramp ◢ / ◣(斜坡)** | 三角 | 向右 / 向左升的 45° 斜坡。 |
+| **Half(半砖:下 / 上 / 左 / 右)** | 半格盒 | 台沿、矮墙、薄地板。 |
+| **One-way ↑(单向)** | 顶部实心盒 | 可跳穿平台——上方实心、下方可穿过。翻转即可改朝向(天花板、墙)。 |
+| **Trigger(触发器)** | 传感器盒 | 非实心区域,触发重叠事件——见 [标记与触发区](/docs/zh-cn/guides/markers/)。 |
+
+像画瓦片一样画它们;**碰撞叠加层**画出的正是播放时会生成的东西。每个碰撞层还能携带自己的
+**物理材质**(摩擦力 / 弹性 / 密度),作用于它生成的每个格子——在 Inspector 里设置。
+
+<Aside type="note">
+ 碰撞层和瓦片、对象碰撞一样,在**播放时**才生成碰撞体——碰撞体从不在编辑世界里,也不作为
+ 实体被序列化。所画的格子本身*会*保存,存在图层的分块数据里。
+</Aside>
+
+游戏代码通过与任意绘制层相同的[碰撞查询](#tilemaps-api-参考)读取碰撞层——`isTileSolid`、
+`tileCollisionAt`、`tileCollisionAtWorld`——所以下游完全不必知道这些格子来自内置调色板。
+
## 对象层
-Tiled 的**对象层**(出生点、触发器、区域形状)随地图一起加载。用地图的源路径经
-`getTilemapSource` 查询——每个组携带它的对象,含位置、尺寸、`type`(Tiled 的 class)、
-`shape` 和自定义 `properties`:
+Tiled 的**对象层**(出生点、触发器、区域形状)随地图一起加载。现代的读法是
+`Query(Marker)`:加载时点对象汇聚成 [**Marker**](/docs/zh-cn/guides/markers/) 实体、形状对象汇聚成
+**Trigger Area** 区域——正是你手工创建的那些实体——于是一条查询就能读到对象,无论它来自
+Tiled 还是 Estella 编辑器。
+
+原始的组数据仍可用地图的源路径经 `getTilemapSource` 查询——每个组携带它的对象,含位置、
+尺寸、`type`(Tiled 的 class)、`shape` 和自定义 `properties`:
```typescript
import { getTilemapSource } from 'esengine';
@@ -321,6 +365,7 @@ origin / 每单位像素 / 播放模式生命周期。
## 参见
+- [标记与触发区](/docs/zh-cn/guides/markers/) —— 把玩法点位和触发区作为可查询的真实体铺在关卡上。
- [物理](/docs/zh-cn/guides/physics/) —— 瓦片碰撞体参与物理世界。
- [资源](/docs/zh-cn/guides/assets/) —— 加载 `.tmj` 地图与 `.estileset` 图集。
- [场景](/docs/zh-cn/guides/scene/) —— 瓦片图层随场景序列化。