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: user guides catch up to shipped features (en + zh-cn)

yhh7147e0dee12e
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 45e3f36c6..98c3fe51d 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -5,8 +5,10 @@ game engine. It is **descriptive of the current code**. For the
*target* architecture, the root-cause rationale behind the current design, and
the forward roadmap, see the architecture-of-record companions:
-- [`REARCHITECTURE.md`](./REARCHITECTURE.md) — root-cause re-architecture (RC1–RC6, F1–F4).
+- [`REARCHITECTURE.md`](./REARCHITECTURE.md) — root-cause re-architecture: RC1–RC5
+ (correctness), F1–F4 (foundation), RC6 (assets), RC11 (networking).
- `REARCH_2D_PARITY.md` — 2D feature-parity / modernization roadmap (local, gitignored).
+- `REARCH_WGSL.md` — WGSL / WebGPU backend campaign (local, gitignored).
## Overview
@@ -103,11 +105,15 @@ filtered via the per-entity component mask. The SDK exposes this as
### Renderer (`renderer/`)
-WebGL2-based, compiled to WASM. There is **one rendering path**: the legacy
+Compiled to WASM. There is **one rendering path**: the legacy
`Renderer` / `BatchRenderer2D` classes were removed. Everything goes through
`RenderFrame`, and **all** GPU access goes through `GfxDevice` — a
-backend-agnostic RHI shaped so a WebGPU (or native-API) backend can slot in
-beside the WebGL2 one without touching the renderer above it.
+backend-agnostic RHI. Two concrete backends now sit behind it: `GLDevice`
+(WebGL2) and `WebGPUDevice` (Dawn/WebGPU), chosen at the platform edge with no
+`#ifdef` in the renderer above. Shaders carry a source language (`GfxShaderSource`);
+`.esshader` / material-graph / built-in programs emit **both** GLSL ES 300 and
+WGSL twins, and cook-time tooling auto-twins user GLSL to WGSL. The two backends
+are pixel-verified against each other in CI on every push.
```
┌──────────────────────────────────────────────────────────────┐
@@ -120,7 +126,8 @@ beside the WebGL2 one without touching the renderer above it.
│ DrawList (sort + coalesce; multi-texture batch; u32 index) │
│ ▼ │
│ GfxDevice (the render backend boundary / RHI) │
-│ └── GLDevice : public GfxDevice (the one concrete impl) │
+│ ├── GLDevice : public GfxDevice (WebGL2) │
+│ └── WebGPUDevice : public GfxDevice (Dawn/WebGPU) │
│ Shader · Texture · Buffer · Framebuffer · CustomGeometry │
│ all take GfxDevice&; no raw gl* outside GLDevice (CI-guarded)│
└──────────────────────────────────────────────────────────────┘
@@ -150,7 +157,11 @@ Key facts:
A CI guard (`tools/check-gl-boundary.mjs`) rejects raw `gl*` calls outside
`GLDevice.cpp`; a `MockGfxDevice` harness exercises the contract headlessly.
- **`DrawList`** sorts and coalesces draw commands, merging up to 8 textures per
- call; indices are **u32** (no >65535 vertex wraparound).
+ call; indices are **u32** (no >65535 vertex wraparound). A per-layer **y-sort**
+ mask (opt-in via project settings) packs a 24-bit order-preserving world-Y into
+ the sort key so lower-on-screen entities paint on top (top-down occlusion);
+ painter's order deliberately beats batching inside a y-sorted layer, every other
+ layer keeps its key bit-for-bit.
- **`RenderFrame`** owns transient buffers (`TransientBufferPool`), frustum
culling, render-to-texture (`RenderTarget`), masking (`RenderFrameMask`:
scissor + stencil), optional post-processing (`PostProcessPipeline`,
@@ -230,6 +241,25 @@ when their scene is `running`. `sceneManagerPlugin` runs the transition update
each frame. Prefabs expand to tagged entities on load and collapse on save, using
the same expand/collapse core in the SDK as the editor.
+## Networking (SDK)
+
+Multiplayer is **server-authoritative state replication** (RC11), built as an
+ordinary plugin over the existing schedule — no second tick loop. Which fields
+replicate is a single source of truth: EHT emits `replicatedFields` from C++
+annotations and `defineComponent` accepts them for user components, so the wire
+schema is derived, not hand-mirrored. State travels as per-field binary delta
+frames; spawn/despawn reuse the scene-serialization primitives (so late joiners
+get current state for free). Entity handles never cross the wire — a `NetId` map
+does. `NetChannel` adds a typed message/RPC layer over the raw socket; sockets are
+created through `PlatformAdapter.createSocket`. Snapshot interpolation, client
+input upload, and ownership (`Replicated.owner`) round out the client side.
+
+The **same wasm and gameplay code** runs headless on Node via the `esengine/node`
+entry (`createHeadlessApp` + `runHeadless`): a Node platform adapter (filesystem
+assets, global `WebSocket`, `NullAudioBackend`, no DOM). The editor's Play mode
+drives 1–4 players in-process by wiring realms over a `MessagePortTransport` — the
+same `NetSession` stack shipping games use, exercised with zero network.
+
## Performance Considerations
1. **Component iteration** — views touch only matching entities; dense arrays.
@@ -248,15 +278,29 @@ the same expand/collapse core in the SDK as the editor.
## Status / Future Improvements
-Landed root-cause work: RC1 (keystone — generated layout + ABI handshake),
-RC2 (single storage core), RC4 (domain TypeIds), RC5 (single render path +
-`GfxDevice` + u32 index), F2 (single `WasmBridge`), F3 (per-App resources).
-
-In progress / planned (see `REARCHITECTURE.md` and `REARCH_2D_PARITY.md`):
-- [ ] RC3 remainder — always-on C++ boundary validation; per-subsystem abort guards.
-- [ ] F1 — isolate (keep) the native platform backend; F4 — this rewrite.
-- [ ] RC6 / T1 — asset delivery: WeChat subpackages, on-demand loading, auto
- atlas, import-time texture compression, SDK-exposed VRAM budget.
-- [ ] T2 — animation state machines / blend trees; native 2D skeletal rig.
-- [ ] T3 — 2D shadows + normal maps; richer post-processing; GPU particles.
-- [ ] T4 — SDK math library; one-way platforms; hex tilemaps; i18n; netcode.
+The correctness and foundation campaigns are **complete**. Landed:
+- **RC1–RC5** (correctness root causes): generated layout + ABI handshake (RC1),
+ single storage core (RC2), always-on C++ boundary validation via `boundarySpan`
+ (RC3), domain TypeIds (RC4), single render path + `GfxDevice` + u32 index (RC5).
+- **F1–F4** (foundation): native seam closed by deletion — the engine is a pure
+ Emscripten target (F1); single `WasmBridge` base class (F2); per-App resources
+ (F3); this document is the F4 rewrite.
+- **RHI modernization + WGSL/WebGPU**: `GfxDevice` is a backend-neutral RHI with
+ a real `WebGPUDevice` beside `GLDevice`; dual-backend pixel verification runs
+ in CI on every push.
+- **RC6 / T1** (asset delivery): WeChat subpackages (folder convention),
+ `Assets.loadGroup`/`loadByLabel`/`preload`, cook-time auto-atlas, import-time
+ KTX2 compression, texture + audio residency with SDK-exposed VRAM budget + LRU.
+- **RC11** (networking): server-authoritative replication + headless Node server.
+- **T2/T3/T4 parity, landed**: animation state machines + 1D blend + Spine driver;
+ 2D shadows (hard/soft/directional) + normal maps + extended post-processing
+ (color grade, tonemap, FXAA, distortion, pixelate, LUT); pixel-perfect camera +
+ 4-renderable parallax + per-layer y-sort; SDK math library; i18n; save
+ versioning; hex tilemaps; Tiled object layers; single `.tmj` parser.
+
+Remaining capability work (see `REARCH_2D_PARITY.md`, gitignored):
+- [ ] T2 — editor keyframe/curve editing UI; particle visual editor; native 2D
+ skeletal rig (own project).
+- [ ] T3 — GPU particles / trails (transform-feedback or compute).
+- [ ] T4 — one-way platforms + remaining Box2D joints; editor multi-atlas painting;
+ tile-gid objects in tilemaps.
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.md
index 3188e9694..a1dcf61ea 100644
--- a/docs/REARCHITECTURE.md
+++ b/docs/REARCHITECTURE.md
@@ -209,8 +209,8 @@ TS 驱动的主 pass clear 退出边界,`clear` 家族退出公共 RHI:
### CI 常绿门禁(push-gated invariants)— ✅ 已落地(2026-07-07)
此前 `build.yml` 仅 `workflow_dispatch`——boundary guards、全组件 ABI `static_assert`、各测试套件全是"约定"而非"机制"。现在**每次 push master 自动跑**:① web/playable/wechat 构建(编译期即验证生成断言 + ABI 哈希)+ 全部 15 个 C++ doctest harness(node 下执行);② 双 boundary guard + SDK tsc/构建/vitest + examples 检查 + desktop tsc/vitest(后两者此前完全不在 CI);③ headless 像素验证(sprite/mesh2d/parallax-shape/tilemap-flip/ui-mask,electron + xvfb + SwiftShader,需 `ELECTRON_DISABLE_SANDBOX`)。落地即抓到并修复三处腐化:`test_registry.cpp` 用已删除的 `View::sizeHint`、`test_sparse_set.cpp` 的局部常量撞 emscripten `PAGE_SIZE` 宏、以及一个**真回归**——单组件 `View::each` 活迭代(中途 emplace 会重访、swap-pop 移除会跳漏),多组件版早有快照契约,现已对齐。
-### 地基收口(Foundation Consolidation)— 🟡 进行中,RC6 前置(设计文档)
-见 [`REARCH_FOUNDATION_CONSOLIDATION.md`](./REARCH_FOUNDATION_CONSOLIDATION.md):
+### 地基收口(Foundation Consolidation)— ✅ 已收口(F1–F4 全部落地)
+设计文档 `REARCH_FOUNDATION_CONSOLIDATION.md`(本地 gitignore,同 RC6 约定);要点:
- **F2 单一 `WasmBridge` 基类 + abort 守卫下沉(keystone)— ✅ 已落地**(`ac390f7d` + RM 闭环 `41bea17a`,五套桥接全部收敛,abort 守卫全子系统覆盖)。
- **F3 全 per-App 资源 — ✅ 已落地**(分支 `rearch/f3-per-app`):Camera(`CameraView`)、Timeline(`Timeline`)、PostProcess(拆 god-object + 管线注入 + 删 sync.ts)、SpriteAnimator(`SpriteAnimation`)全部 per-App;模块绑定单例在单模块运行时下无需改(B4 关闭)。
- **F4 重写 `ARCHITECTURE.md` — ✅ 已落地**:`docs/ARCHITECTURE.md` 重写为当前现实(`RenderFrame`+`GfxDevice`/`GLDevice` 单一 GPU 边界、单一 `SparseSet`+`version()`、按域 TypeId、per-App 资源 + `WasmBridge` 基类、`ResourcePool` LRU/预算),删除对已删除的 `Renderer`/`BatchRenderer2D` 的描述。
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index 5c47e14ba..f60f58ca7 100644
--- a/docs/astro/src/content/docs/guides/assets.mdx
+++ b/docs/astro/src/content/docs/guides/assets.mdx
@@ -120,6 +120,9 @@ manifest. Along the way it can:
(ASTC → ETC2 → S3TC, falling back to RGBA8).
- **Content-address** — name each shipped file by a hash of its bytes, so URLs
are immutable and identical files dedupe to a single copy.
+- **Auto-atlas** — put loose PNGs in a `<name>.atlas/` folder and the cook packs
+ them into atlas pages (with the frame UVs written into the manifest), so many
+ small sprites ship as one texture and batch in one draw call. Opt-in per export.
## Lifetime & reference counting
diff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/guides/postprocess.mdx
index 641c4ea05..0b151882f 100644
--- a/docs/astro/src/content/docs/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/guides/postprocess.mdx
@@ -17,6 +17,7 @@ several can stack in one frame at no extra target cost beyond the passes.
| `bloom` | Glow on bright areas | `threshold`, `intensity` |
| `tonemap` | ACES filmic tonemapping | `exposure` |
| `colorGrade` | Exposure / contrast / saturation / white balance | `exposure`, `contrast`, `saturation`, `temperature`, `tint` |
+| `lutGrade` | Color grading through a lookup-table texture | `u_lut` (texture), `intensity` |
| `vignette` | Darkened screen edges | `intensity`, `radius` |
| `chromaticAberration` | RGB fringing | `intensity` |
| `blur` | Gaussian blur | `radius` |
@@ -70,6 +71,20 @@ const setup = defineSystem([Query(Camera), Res(PostProcess)], (q, pp) => {
| `PostProcess.unbind(camera)` | Remove the camera's stack. |
| `stack.setEnabled(name, on)` | Enable/disable an effect (chainable). |
| `stack.setUniform(pass, uniform, value)` | Set an effect parameter (chainable). |
+| `stack.setTexture(pass, uniform, handle)` | Bind a texture parameter, e.g. a LUT (chainable). |
+
+### Texture parameters (LUTs & masks)
+
+Some effects take a texture, not just scalars. `lutGrade` samples a **color
+lookup table** — a 2D-packed `1024×32` PNG (32 slices of a 32³ cube) — so you can
+author a whole grade in an image editor and drop it in. Bind it with `setTexture`
+(or, on a `PostProcessVolume`, list it under the effect's `textures: { u_lut: <ref> }`):
+
+```typescript
+stack.setEnabled('lutGrade', true)
+ .setTexture('lutGrade', 'u_lut', lutHandle)
+ .setUniform('lutGrade', 'u_intensity', 1);
+```
## Best practices
diff --git a/docs/astro/src/content/docs/guides/sprites.mdx b/docs/astro/src/content/docs/guides/sprites.mdx
index b6353a56f..c1ed84625 100644
--- a/docs/astro/src/content/docs/guides/sprites.mdx
+++ b/docs/astro/src/content/docs/guides/sprites.mdx
@@ -42,6 +42,7 @@ Content Browser onto an entity, or set the Sprite's texture field in Details.
| `layer` | `0` | Sorting layer — controls draw order (see below). |
| `flipX` / `flipY` | `false` | Mirror horizontally / vertically. |
| `material` | `0` | A custom [material](/docs/guides/material/) handle (`0` = the default sprite shader). |
+| `lit` | `false` | Receive 2D lights with a flat normal — the one-flag path to lit sprites (a custom `material` overrides it). |
| `uvOffset` / `uvScale` | `{0,0}` / `{1,1}` | Sub-rectangle of the texture to show (for atlases / scrolling). |
| `tileSize` / `tileSpacing` | `{0,0}` | Repeat the texture across the sprite (`0` = no tiling). |
| `parallax` | `{1,1}` | Parallax scroll factor (see below). |
@@ -119,9 +120,12 @@ background.
## Custom materials & lighting
Assign `sprite.material` to draw the sprite with your own shader — a tint, a
-dissolve, a distortion — see [Materials & Shaders](/docs/guides/material/). To make a
-sprite respond to `Light2D` lights, give it a **Lit-2D material**; see
-[2D Lighting & Shadows](/docs/guides/lighting/).
+dissolve, a distortion — see [Materials & Shaders](/docs/guides/material/).
+
+To make a sprite respond to `Light2D` lights, the simplest path is to set
+`sprite.lit = true` — no custom material needed (it's lit with a flat normal). For
+normal maps or a fully custom look, use a **Lit-2D material** instead. Either way,
+see [2D Lighting & Shadows](/docs/guides/lighting/).
## Shapes without a texture
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index b66b2a976..8bb7c1f49 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -17,7 +17,8 @@ There are two entry points. The **`Tilemap`** component points an entity at a Ti
JSON file and, at load, spawns one **`TilemapLayer`** entity per layer. The
**`Tilemaps`** resource is the imperative API for creating and editing layers from
code. Either way the data ends up in the same runtime layer model. Tile ids are
-**1-based** (`0` = empty).
+**1-based** (`0` = empty). **Orthogonal, isometric, staggered, and hexagonal** maps
+all render — the orientation is read from the Tiled file, no extra setup.
## Load a Tiled map
@@ -124,6 +125,33 @@ texture and carries per-tile collision, animation, and terrain/auto-tile data.
world or serialized.
</Aside>
+## 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`:
+
+```typescript
+import { getTilemapSource } from 'esengine';
+
+const src = getTilemapSource('assets/maps/level.tmj');
+for (const group of src?.objectGroups ?? []) {
+ for (const obj of group.objects) {
+ if (obj.type === 'spawn') spawnPlayer(obj.x, obj.y);
+ }
+}
+```
+
+An object group whose name is `collision` (case-insensitive) or that carries a
+`collision=true` property also **spawns static colliders in play mode** — rectangles,
+ellipses, polygons, and polylines become the matching Box2D shape, on the same
+origin / pixels-per-unit / play-mode lifecycle as tile collision.
+
+<Aside type="note">
+ Object collision, like tile collision, is **play-mode only** and never serialized
+ into the edit world.
+</Aside>
+
## `Tilemaps` API reference
| Method | Description |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
index 105f16137..3bd842670 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
@@ -106,6 +106,8 @@ const { failed } = await assets.preload(
- **压缩纹理** —— PNG 被编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。
- **内容寻址** —— 每个发布文件按字节哈希命名,于是 URL 不可变,相同文件去重成一份。
+- **自动图集** —— 把零散的 PNG 放进 `<name>.atlas/` 文件夹,烘焙时会把它们打包成图集页
+ (帧 UV 写进清单),于是许多小精灵作为一张纹理发布、在一次绘制里合批。按导出可选开启。
## 生命周期与引用计数
diff --git a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
index efd4cb840..6f01c2776 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
@@ -16,6 +16,7 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
| `bloom` | 亮部辉光 | `threshold`、`intensity` |
| `tonemap` | ACES filmic 色调映射 | `exposure` |
| `colorGrade` | 曝光 / 对比度 / 饱和度 / 白平衡 | `exposure`、`contrast`、`saturation`、`temperature`、`tint` |
+| `lutGrade` | 通过查找表纹理(LUT)调色 | `u_lut`(纹理)、`intensity` |
| `vignette` | 屏幕边缘变暗 | `intensity`、`radius` |
| `chromaticAberration` | RGB 色散 | `intensity` |
| `blur` | 高斯模糊 | `radius` |
@@ -66,6 +67,20 @@ const setup = defineSystem([Query(Camera), Res(PostProcess)], (q, pp) => {
| `PostProcess.unbind(camera)` | 移除相机的栈。 |
| `stack.setEnabled(name, on)` | 启用/禁用一个效果(可链式)。 |
| `stack.setUniform(pass, uniform, value)` | 设置一个效果参数(可链式)。 |
+| `stack.setTexture(pass, uniform, handle)` | 绑定一个纹理参数,比如 LUT(可链式)。 |
+
+### 纹理参数(LUT 与遮罩)
+
+有些效果吃的是纹理而不只是标量。`lutGrade` 采样一张**颜色查找表**——一张 2D 打包的
+`1024×32` PNG(32³ 色立方切成 32 片)——于是你可以在图像编辑器里做好整套调色再丢进来。
+用 `setTexture` 绑定它(或在 `PostProcessVolume` 上,把它列在该效果的
+`textures: { u_lut: <ref> }` 下):
+
+```typescript
+stack.setEnabled('lutGrade', true)
+ .setTexture('lutGrade', 'u_lut', lutHandle)
+ .setUniform('lutGrade', 'u_intensity', 1);
+```
## 最佳实践
diff --git a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
index 0146ca05d..0d349acb8 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
@@ -39,6 +39,7 @@ const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets)
| `layer` | `0` | 排序层——控制绘制顺序(见下)。 |
| `flipX` / `flipY` | `false` | 水平 / 垂直镜像。 |
| `material` | `0` | 自定义[材质](/docs/zh-cn/guides/material/)句柄(`0` = 默认精灵着色器)。 |
+| `lit` | `false` | 用平面法线接收 2D 光照——让精灵变"受光"的一键路径(自定义 `material` 会覆盖它)。 |
| `uvOffset` / `uvScale` | `{0,0}` / `{1,1}` | 要显示的纹理子矩形(用于图集 / 滚动)。 |
| `tileSize` / `tileSpacing` | `{0,0}` | 把纹理在精灵上平铺重复(`0` = 不平铺)。 |
| `parallax` | `{1,1}` | 视差滚动系数(见下)。 |
@@ -103,8 +104,11 @@ sprite.layer = 2; // 例如 "Foreground" —— 画在上面
## 自定义材质与光照
给 `sprite.material` 赋值,用你自己的着色器绘制精灵——染色、溶解、扭曲——见
-[材质与着色器](/docs/zh-cn/guides/material/)。要让精灵响应 `Light2D` 光源,给它一个 **Lit-2D 材质**;
-见 [2D 光照与阴影](/docs/zh-cn/guides/lighting/)。
+[材质与着色器](/docs/zh-cn/guides/material/)。
+
+要让精灵响应 `Light2D` 光源,最简单的路径是设 `sprite.lit = true`——无需自定义材质
+(用平面法线受光)。需要法线贴图或完全自定义的观感时,改用 **Lit-2D 材质**。两种方式都见
+[2D 光照与阴影](/docs/zh-cn/guides/lighting/)。
## 不带纹理的图元
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 1115b6a42..8ef649b30 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -13,7 +13,8 @@ Estella 在 C++/WebAssembly 内核里渲染瓦片图层,按图集纹理合批并
有两个入口。**`Tilemap`** 组件把实体指向一个 Tiled JSON 文件,加载时为每个图层生成一个
**`TilemapLayer`** 实体。**`Tilemaps`** 资源是用代码创建与编辑图层的命令式 API。两种方式最终
-都落到同一个运行时图层模型。瓦片 id 是**从 1 开始**的(`0` = 空)。
+都落到同一个运行时图层模型。瓦片 id 是**从 1 开始**的(`0` = 空)。**正交、等距、交错
+(staggered)、六边形**地图都能渲染——朝向从 Tiled 文件里读取,无需额外设置。
## 加载 Tiled 地图
@@ -119,6 +120,31 @@ tilemap.setChunkTiles(layer, chunkX, chunkY, tiles, 32, 32);
生成——它们从不在编辑世界里,也不被序列化。
</Aside>
+## 对象层
+
+Tiled 的**对象层**(出生点、触发器、区域形状)随地图一起加载。用地图的源路径经
+`getTilemapSource` 查询——每个组携带它的对象,含位置、尺寸、`type`(Tiled 的 class)、
+`shape` 和自定义 `properties`:
+
+```typescript
+import { getTilemapSource } from 'esengine';
+
+const src = getTilemapSource('assets/maps/level.tmj');
+for (const group of src?.objectGroups ?? []) {
+ for (const obj of group.objects) {
+ if (obj.type === 'spawn') spawnPlayer(obj.x, obj.y);
+ }
+}
+```
+
+名字为 `collision`(大小写不敏感)或携带 `collision=true` 属性的对象组还会**在播放模式
+生成静态碰撞体**——矩形、椭圆、多边形、折线各自变成对应的 Box2D 形状,与瓦片碰撞走相同的
+origin / 每单位像素 / 播放模式生命周期。
+
+<Aside type="note">
+ 对象碰撞和瓦片碰撞一样,**仅在播放模式**存在,从不被序列化进编辑世界。
+</Aside>
+
## `Tilemaps` API 参考
| 方法 | 说明 |