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: deepen the Tilemaps guide (multi-tileset / animation / infinite / transforms)

yhhbae7c976e512
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index 010741fcb..835ddc1ab 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -1,20 +1,20 @@
---
title: Tilemaps
-description: Load Tiled maps, or build tile layers with Res(Tilemaps).
+description: Load Tiled maps or build, edit, and animate tile layers in code.
---
import { Aside } from '@astrojs/starlight/components';
-Estella renders tile layers in the C++/WebAssembly core. There are two ways in:
-a high-level component that loads a whole map from a file, and a low-level API
-for building and editing layers yourself.
+Estella renders tile layers in the C++/WebAssembly core. Load a whole map from a
+Tiled file, or build and edit layers yourself with the `Tilemaps` resource —
+including multi-tileset layers, per-tile animation, and infinite chunked maps.
## High-level: load a Tiled map
The `Tilemap` component points an entity at a Tiled JSON (`.tmj`) file via its
-one field, `source`. You usually add it in the editor and pick the file; the
-runtime then loads the map and spawns a `TilemapLayer` per layer. To do it
-procedurally, spawn from a system that takes `Commands()`:
+one field, `source`. You usually add it in the editor; the runtime loads the map
+and spawns a `TilemapLayer` per layer (with `cellSize`, tileset texture,
+`renderLayer`, `tintColor`, `opacity`, `parallaxFactor`). In code:
```typescript
import { defineSystem, Commands, Tilemap } from 'esengine';
@@ -24,45 +24,72 @@ const loadLevel = defineSystem([Commands()], (cmds) => {
});
```
-## Low-level: build layers with `Res(Tilemaps)`
+## Build a layer in code
-The `Tilemaps` resource is the tilemap runtime API — read it with `Res(Tilemaps)`
-and call it with a layer entity. Spawn an entity, initialise a layer on it, then
-write tiles:
+`Tilemaps` is the runtime API. Spawn an entity, initialise a layer, then fill it —
+tile ids are `1`-based (`0` = empty):
```typescript
import { defineSystem, Commands, Res, Transform, Tilemaps } from 'esengine';
-const buildLayer = defineSystem([Commands(), Res(Tilemaps)], (cmds, tilemap) => {
- const layer = cmds
- .spawn()
- .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
- .id(); // the layer entity
+const build = defineSystem([Commands(), Res(Tilemaps)], (cmds, tilemap) => {
+ const layer = cmds.spawn().insert(Transform, { position: { x: 0, y: 0, z: 0 } }).id();
- tilemap.initLayer(layer, 32, 32, 16, 16); // 32x32 tiles, 16px cells
+ tilemap.initLayer(layer, 32, 32, 16, 16); // 32×32 tiles, 16px cells
+ tilemap.setTiles(layer, new Uint16Array(32 * 32)); // bulk load
+ tilemap.setTile(layer, 5, 3, 7); // one tile
+ tilemap.fillRect(layer, 0, 0, 32, 1, 2); // a row of tile 2
+});
+```
- const tiles = new Uint16Array(32 * 32); // tile ids (0 = empty)
- tiles[0] = 1;
- tilemap.setTiles(layer, tiles);
+## Edit and transform tiles
- tilemap.setTile(layer, 5, 3, 7); // one tile
- tilemap.flipTile(layer, 5, 3, true, false, false); // flip horizontally
+```typescript
+tilemap.getTile(layer, 5, 3); // read a tile id
+tilemap.flipTile(layer, 5, 3, true, false, false); // flipH, flipV, flipDiagonal
+tilemap.rotateTile(layer, 5, 3, 90); // degrees
+tilemap.tileToWorld(layer, 5, 3, 0, 0); // → { x, y }
+tilemap.worldToTile(layer, wx, wy, 0, 0); // → { x, y }
+```
- tilemap.setTileAnimation(layer, 10, [ // animate tile id 10
- { tileId: 10, duration: 100 },
- { tileId: 11, duration: 100 },
- ]);
-});
+## Multiple tilesets
+
+One layer can draw from several tilesets. Give it a slot table — each slot maps a
+`firstId` range to a texture and its column count:
+
+```typescript
+tilemap.setTilesets(layer, [
+ { firstId: 1, textureHandle: grassTex, columns: 8 },
+ { firstId: 256, textureHandle: propsTex, columns: 8 },
+]);
+```
+
+## Tile animation
+
+Set an animation on a tile id once — the plugin advances it every frame:
+
+```typescript
+tilemap.setTileAnimation(layer, 10, [
+ { tileId: 10, duration: 100 },
+ { tileId: 11, duration: 100 },
+]);
+```
+
+## Infinite (chunked) maps
+
+For large or streaming worlds, use an infinite layer and write chunk by chunk:
+
+```typescript
+tilemap.initInfiniteLayer(layer, 16, 16);
+tilemap.setChunkTiles(layer, chunkX, chunkY, tiles, 32, 32);
```
-Other methods: `getTile`, `fillRect`, `rotateTile`, `initInfiniteLayer` (chunked
-infinite maps), `setTilesets`, `setTint`, `setVisible`, and `tileToWorld` /
-`worldToTile`. (The same object is also exported directly as `TilemapAPI` for use
-outside a system.)
+`exportChunks` / `importChunks` serialize the sparse chunk data.
<Aside type="note">
Tile **collision is play-mode only** — static colliders are spawned from
- collidable tiles (marked in the `.estileset` tileset) when the scene runs; they
- are never in the edit world or serialized. Tile animations advance
- automatically once set — you call `setTileAnimation` once.
+ collidable tiles (marked in the `.estileset` tileset, which also carries
+ per-tile animation and terrain/auto-tile data) when the scene runs; they are
+ never in the edit world or serialized. Other methods: `setTint`, `setVisible`,
+ `setRenderProps`, `rotateTile`.
</Aside>
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 ce083beb1..b8e3bff15 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -1,18 +1,18 @@
---
title: 瓦片地图
-description: 加载 Tiled 地图,或用 Res(Tilemaps) 构建瓦片图层。
+description: 加载 Tiled 地图,或用代码构建、编辑并让瓦片图层动起来。
---
import { Aside } from '@astrojs/starlight/components';
-Estella 在 C++/WebAssembly 内核中渲染瓦片图层。有两种用法:一个从文件加载整张地图的
-高层组件,以及一套自己构建、编辑图层的低层 API。
+Estella 在 C++/WebAssembly 内核中渲染瓦片图层。你可以从 Tiled 文件加载整张地图,也可以
+用 `Tilemaps` 资源自己构建、编辑图层——包括多图集图层、逐瓦片动画,以及无限分块地图。
## 高层:加载 Tiled 地图
-`Tilemap` 组件通过它唯一的字段 `source`,把实体指向一个 Tiled JSON(`.tmj`)文件。
-通常你在编辑器里添加该组件并选择文件;运行时随后加载地图,并为每个图层生成一个
-`TilemapLayer`。要以代码方式做,在带 `Commands()` 参数的系统里生成:
+`Tilemap` 组件通过唯一字段 `source` 把实体指向一个 Tiled JSON(`.tmj`)文件。通常你在
+编辑器里添加它;运行时加载地图并为每个图层生成一个 `TilemapLayer`(带 `cellSize`、图集
+贴图、`renderLayer`、`tintColor`、`opacity`、`parallaxFactor`)。用代码:
```typescript
import { defineSystem, Commands, Tilemap } from 'esengine';
@@ -22,42 +22,70 @@ const loadLevel = defineSystem([Commands()], (cmds) => {
});
```
-## 低层:用 `Res(Tilemaps)` 构建图层
+## 用代码构建图层
-`Tilemaps` 资源就是瓦片地图运行时 API——用 `Res(Tilemaps)` 读取它,传入图层实体来
-调用。先生成一个实体,在它上面初始化图层,再写入瓦片:
+`Tilemaps` 是运行时 API。生成一个实体,初始化图层,再填充它——瓦片 id 从 `1` 开始
+(`0` = 空):
```typescript
import { defineSystem, Commands, Res, Transform, Tilemaps } from 'esengine';
-const buildLayer = defineSystem([Commands(), Res(Tilemaps)], (cmds, tilemap) => {
- const layer = cmds
- .spawn()
- .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
- .id(); // 图层实体
+const build = defineSystem([Commands(), Res(Tilemaps)], (cmds, tilemap) => {
+ const layer = cmds.spawn().insert(Transform, { position: { x: 0, y: 0, z: 0 } }).id();
- tilemap.initLayer(layer, 32, 32, 16, 16); // 32x32 格,16px 格子
+ tilemap.initLayer(layer, 32, 32, 16, 16); // 32×32 格,16px 格子
+ tilemap.setTiles(layer, new Uint16Array(32 * 32)); // 批量载入
+ tilemap.setTile(layer, 5, 3, 7); // 单个瓦片
+ tilemap.fillRect(layer, 0, 0, 32, 1, 2); // 一行瓦片 2
+});
+```
- const tiles = new Uint16Array(32 * 32); // 瓦片 id(0 = 空)
- tiles[0] = 1;
- tilemap.setTiles(layer, tiles);
+## 编辑与变换瓦片
- tilemap.setTile(layer, 5, 3, 7); // 单个瓦片
- tilemap.flipTile(layer, 5, 3, true, false, false); // 水平翻转
+```typescript
+tilemap.getTile(layer, 5, 3); // 读取瓦片 id
+tilemap.flipTile(layer, 5, 3, true, false, false); // 水平、垂直、对角翻转
+tilemap.rotateTile(layer, 5, 3, 90); // 度数
+tilemap.tileToWorld(layer, 5, 3, 0, 0); // → { x, y }
+tilemap.worldToTile(layer, wx, wy, 0, 0); // → { x, y }
+```
- tilemap.setTileAnimation(layer, 10, [ // 让瓦片 id 10 动起来
- { tileId: 10, duration: 100 },
- { tileId: 11, duration: 100 },
- ]);
-});
+## 多图集
+
+一个图层可以从多个图集绘制。给它一张 slot 表——每个 slot 把一个 `firstId` 范围映射到
+一张贴图及其列数:
+
+```typescript
+tilemap.setTilesets(layer, [
+ { firstId: 1, textureHandle: grassTex, columns: 8 },
+ { firstId: 256, textureHandle: propsTex, columns: 8 },
+]);
+```
+
+## 瓦片动画
+
+给某个瓦片 id 设置一次动画——插件每帧推进它:
+
+```typescript
+tilemap.setTileAnimation(layer, 10, [
+ { tileId: 10, duration: 100 },
+ { tileId: 11, duration: 100 },
+]);
+```
+
+## 无限(分块)地图
+
+对于大型或流式世界,用无限图层并逐块写入:
+
+```typescript
+tilemap.initInfiniteLayer(layer, 16, 16);
+tilemap.setChunkTiles(layer, chunkX, chunkY, tiles, 32, 32);
```
-其他方法:`getTile`、`fillRect`、`rotateTile`、`initInfiniteLayer`(分块的无限地图)、
-`setTilesets`、`setTint`、`setVisible`,以及 `tileToWorld` / `worldToTile`。(同一个
-对象也以 `TilemapAPI` 直接导出,供在系统之外使用。)
+`exportChunks` / `importChunks` 序列化稀疏的分块数据。
<Aside type="note">
瓦片**碰撞仅在运行模式**存在——静态碰撞体在场景运行时由可碰撞瓦片(在 `.estileset`
- 图集里标记)生成;它们不存在于编辑世界中,也不会被序列化。瓦片动画一旦设置便自动
- 推进——`setTileAnimation` 只需调用一次。
+ 图集里标记,该图集还携带逐瓦片动画和地形/自动图块数据)生成;它们不存在于编辑世界中,
+ 也不会被序列化。其他方法:`setTint`、`setVisible`、`setRenderProps`、`rotateTile`。
</Aside>