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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdxindex 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 mapThe `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:```typescriptimport { 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):```typescriptimport { 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.mdxindex 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`)。用代码:```typescriptimport { 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` = 空):```typescriptimport { 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>