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(tilemap): document the rich per-tile collision + complete the API table

esengine0b0158722f5d
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index e0ed2e3ee..7ecfa01b9 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -168,12 +168,29 @@ tilemap.setChunkTiles(layer, chunkX, chunkY, tiles, 32, 32);
## Tilesets & collision
The engine's first-class tileset asset is **`.estileset`** — it references an atlas
-texture and carries per-tile collision, animation, and terrain/auto-tile data.
+texture and carries per-tile collision, animation, terrain/auto-tile data, and
+custom key/value properties.
+
+Per-tile collision goes well beyond solid squares. In the tileset editor's
+**Collision** mode you author, per tile:
+
+- **Shapes** — full-cell **box** (drag-paints), fitted **circle** (drag-paints),
+ or a freeform **polygon** via the vertex editor; one-click **slope / half-tile
+ presets** stamp the common ramps (drag to stamp a run of them).
+- **Modifiers**, riding on whatever shape you paint: **one-way** (jump-through
+ platforms with a solid-top normal), **sensor** (overlap events, no contact
+ response), and physics-material overrides (**friction / bounce / density**).
+
+Plain solid boxes are greedy-merged into large static colliders at spawn; shaped,
+one-way, sensor, and material tiles spawn one collider each, with tile flip flags
+reorienting the geometry to match the rendering. The scene viewport draws the
+selected layer's whole collision as an overlay (Show Flags → tile collision) —
+WYSIWYG with what Play spawns.
<Aside type="note">
- Tile **collision is play-mode only**: static colliders are spawned from collidable
- tiles (marked in the `.estileset`) when the scene runs — they are never in the edit
- world or serialized.
+ Tile **collision is play-mode only**: static colliders are spawned from the
+ `.estileset`'s per-tile collision when the scene runs — they are never in the
+ edit world or serialized.
</Aside>
## Object layers
@@ -224,6 +241,9 @@ origin / pixels-per-unit / play-mode lifecycle as tile collision.
| `setChunkTiles(layer, cx, cy, tiles, w, h)` | Write a chunk (infinite layers). |
| `exportChunks(layer)` / `importChunks(layer, data)` | Serialize / restore chunk data. |
| `setTint(layer, color)` / `setVisible(layer, on)` / `setRenderProps(...)` | Live visual overrides. |
+| `setTileProperty(...)` / `getTileProperty(...)` | Per-tile custom key/value properties. |
+| `setGridType(layer, type)` / `setHexParams(...)` | Orientation (orthogonal / isometric / hex). |
+| `destroyLayer(layer)` | Tear a layer down. |
## Best practices
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 b154b79db..a2a4a2279 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -154,11 +154,22 @@ tilemap.setChunkTiles(layer, chunkX, chunkY, tiles, 32, 32);
## 图集与碰撞
-引擎的一等图集资源是 **`.estileset`**——它引用一张图集纹理,并携带逐瓦片的碰撞、动画和
-地形/自动拼接(auto-tile)数据。
+引擎的一等图集资源是 **`.estileset`**——它引用一张图集纹理,并携带逐瓦片的碰撞、动画、
+地形/自动拼接(auto-tile)数据与自定义键值属性。
+
+逐瓦片碰撞远不止实心方块。在图集编辑器的 **碰撞** 模式里,你可以为每个瓦片编辑:
+
+- **形状**——整格 **方块**(可拖刷)、内切 **圆形**(可拖刷),或经顶点编辑器的自由
+ **多边形**;一键 **坡度 / 半砖预设** 盖章常用斜坡(拖动可连续铺一排)。
+- **修饰符**,叠加在任何画出的形状上:**单向**(可从下方跳上的平台,固定实心朝上法线)、
+ **传感器**(只发重叠事件、无碰撞响应),以及物理材质覆盖(**摩擦 / 弹性 / 密度**)。
+
+普通实心方块在生成时会贪心合并成大块静态碰撞体;带形状、单向、传感器或材质的瓦片各自
+生成一个碰撞体,并按瓦片翻转标志重定向几何、与渲染严格一致。场景视口会把所选图层的完整
+碰撞画成覆盖层(显示标志 → 瓦片碰撞)——与 Play 生成的完全一致。
<Aside type="note">
- 瓦片**碰撞仅在播放模式**存在:静态碰撞体在场景运行时从可碰撞瓦片(在 `.estileset` 里标记)
+ 瓦片**碰撞仅在播放模式**存在:静态碰撞体在场景运行时从 `.estileset` 的逐瓦片碰撞
生成——它们从不在编辑世界里,也不被序列化。
</Aside>
@@ -207,6 +218,9 @@ origin / 每单位像素 / 播放模式生命周期。
| `setChunkTiles(layer, cx, cy, tiles, w, h)` | 写一个块(无限图层)。 |
| `exportChunks(layer)` / `importChunks(layer, data)` | 序列化 / 恢复分块数据。 |
| `setTint(layer, color)` / `setVisible(layer, on)` / `setRenderProps(...)` | 实时视觉覆盖。 |
+| `setTileProperty(...)` / `getTileProperty(...)` | 逐瓦片自定义键值属性。 |
+| `setGridType(layer, type)` / `setHexParams(...)` | 朝向(正交 / 等距 / 六边形)。 |
+| `destroyLayer(layer)` | 销毁图层。 |
## 最佳实践