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(guides): cover v0.26 — map orientations, corner-Wang terrain, project theme colors

esengine84fcf1fefe1c
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdx
index 185b05702..9f2f426c3 100644
--- a/docs/astro/src/content/docs/guides/editor.mdx
+++ b/docs/astro/src/content/docs/guides/editor.mdx
@@ -203,12 +203,15 @@ Double-click an asset in the Content Browser to open its editor in a document ta
[Timeline](/docs/guides/timeline/).
- **Tilemap painter** — tools for **brush, erase, rectangle, line, bucket, select,
eyedropper**, and **terrain (autotile)**, plus stamp **flip-H / flip-V / rotate-90°**
- (`H` / `V` / `R` while a paint tool is active) and a **random-scatter mode**. The
- palette selects with the arrow keys (`Shift` grows a multi-tile stamp). See
+ (`H` / `V` / `R` while a paint tool is active) and a **random-scatter mode** (`D`). The
+ palette selects with the arrow keys (`Shift` grows a multi-tile stamp), and maps can
+ be **orthogonal, isometric, staggered, or hexagonal**. See
[Tilemaps](/docs/guides/tilemap/).
-- **Tileset editor** — mark per-tile **collision** (box or polygon) and **terrain**
- membership for autotiling, and author **animated tiles** (frame sequences with
- per-frame durations and a live preview).
+- **Tileset editor** — author per-tile **collision** (box / circle / polygon, slope
+ presets, one-way / sensor / material modifiers), **terrain** sets for autotiling
+ (edge/corner peering or multi-color **corner Wang**), per-tile **probability**
+ weights and properties, and **animated tiles** (frame sequences with per-frame
+ durations and a live preview).
- **State Machine** (`.esfsm`) and **Behavior Tree** (`.esbt`) editors — visual graphs
for AI. See [Gameplay AI](/docs/guides/ai/).
- **Material Graph** (`.esmatgraph`) — a node editor that compiles to a shader. See
@@ -231,6 +234,9 @@ Open settings with **Ctrl / ⌘ + ,** or the Activity Bar's gear. Settings are g
preview in any scene), the project-wide **screen orientation** (every export target
honors it; unset ⇒ derived from the design resolution's aspect), and the **camera fit**
(how the main camera scales the design resolution without a UI Canvas; `None` = off).
+ - **UI** — the project's widget **theme** (dark / light) and per-role **Theme
+ Colors** overrides, applied identically in the editor, Play, and every export.
+ See [UI widgets — theming](/docs/guides/ui-components/#theming).
- **Physics** — enable, gravity, sixteen collision-layer names and a 16×16 collision
matrix, plus solver tuning (fixed timestep, sub-steps, contact Hz/damping/push
speed, sleeping, continuous collision). See [Physics](/docs/guides/physics/).
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index a6f2e3dd6..31e521944 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -19,8 +19,8 @@ points an entity at a Tiled 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. Every way the data ends up in the same runtime
layer model. Tile ids are **1-based** (`0` = empty). **Orthogonal, isometric,
-staggered, and hexagonal** maps all render — the orientation is read from the
-Tiled file, no extra setup.
+staggered, and hexagonal** maps are all first-class — author any orientation
+natively in the editor, or import it from a Tiled file with no extra setup.
## Paint in the editor
@@ -49,12 +49,36 @@ While a paint tool is active, `H` / `V` flip the stamp and `R` rotates it 90°.
- **Saved stamps** — the bookmark button below the tools saves the current brush
into a per-project stamp library; click a chip to bring a pattern back, `×`
deletes it. Identical patterns deduplicate.
-- **Random mode** — toggle the dice button and each painted cell samples one tile
- at random from the stamp instead of repeating the pattern — quick scatter for
- grass, rubble, and other variation. Sampling honors each tile's **probability**
- weight from the tileset editor's Properties mode (default 1; 0 = never scattered).
+- **Random mode** — toggle the dice button (or press `D` while painting) and each
+ painted cell samples one tile at random from the stamp instead of repeating the
+ pattern — quick scatter for grass, rubble, and other variation. Sampling honors
+ each tile's **probability** weight from the tileset editor's Properties mode
+ (default 1; 0 = never scattered).
- **Layer strip** — when the scene has several tilemap layers, a strip at the top
- of the panel switches the active layer and toggles per-layer visibility and lock.
+ of the panel switches the active layer and toggles per-layer visibility and
+ lock; **drag a layer chip** to reorder layers.
+
+## Map orientations
+
+Orientation is a property of each `TilemapLayer`, not an import artifact. The
+**New Tilemap** dialog picks it up front — orthogonal, **isometric** (diamond),
+**staggered** (staggered-isometric), or **hexagonal** — along with the stagger
+axis/index and hex side length where they apply, and the Inspector edits the
+same fields afterwards. The viewport follows the layer: the grid overlay,
+brush ghost, hover/selection highlights, and every paint tool work on the
+diamond or hex grid exactly as they do on squares.
+
+| `TilemapLayer` field | Values | Description |
+|---|---|---|
+| `orientation` | Orthogonal / Isometric / Staggered / Hexagonal | Grid layout of the layer. |
+| `staggerAxis` | Y / X | Staggered & hex: `Y` shifts alternate rows, `X` shifts alternate columns. |
+| `staggerIndex` | Odd / Even | Which rows/columns carry the half-cell shift. |
+| `hexSideLength` | px | Hexagonal only: flat side length (`0` = regular pointy hex, `tileHeight / 2`). |
+
+Tiled maps of any orientation import into the same fields — including staggered
+maps' `staggeraxis` / `staggerindex`, so an imported staggered map places tiles
+exactly as Tiled shows it. `examples/` ships three painted showcases: an
+isometric island, a staggered patchwork, and a pointy-top hex strategy map.
## Load a Tiled map
@@ -97,6 +121,9 @@ renderer reads these live, so animating `tintColor` / `opacity` is lag-free.
| `parallaxFactor` | Vec2 | `{1, 1}` | Parallax scroll factor relative to the camera. |
| `visible` | boolean | `true` | Show / hide the layer. |
+Plus the [orientation fields](#map-orientations) above — `orientation`,
+`staggerAxis`, `staggerIndex`, `hexSideLength`.
+
## Build a layer in code
Spawn an entity, initialise a layer, then fill it:
@@ -166,6 +193,29 @@ tilemap.initInfiniteLayer(layer, 16, 16);
tilemap.setChunkTiles(layer, chunkX, chunkY, tiles, 32, 32);
```
+## Terrain autotiling
+
+Terrains make the `T` brush paint *meaning* instead of specific tiles — you say
+"grass here" and the resolver picks the tile whose edges match the neighbors.
+Author terrains in the **Tileset editor**'s Terrain mode; a terrain set uses one
+of two models:
+
+- **Peering (edge / corner-blob)** — the classic single-terrain model: each tile
+ declares which of its edges (16-tile sets) or edges + corners (47-tile blob
+ sets) belong to the terrain, and the brush paints the terrain while fixing up
+ neighbor transitions.
+- **Corner Wang (multi-terrain)** — the modern model from Tiled/Godot: the set
+ carries a palette of **colors** (grass, sand, water, …) and each tile assigns
+ a color to its four **corners**. One set blends many terrains, and the brush
+ paints colors on a **half-cell corner grid** — click between four tiles and
+ the resolver re-tiles all of them by exact corner match (nearest-mismatch
+ fallback), producing smooth marching-squares boundaries. The tileset editor
+ authors the color palette (add / rename / recolor / remove) and per-tile
+ corner dots; the painter lists the colors to paint with.
+
+The painter's terrain brush dispatches on the set's model automatically. A
+blended-island corner-Wang demo ships in `examples/`.
+
## Tilesets & collision
The engine's first-class tileset asset is **`.estileset`** — it references an atlas
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdx
index b4fa44498..a269c05e8 100644
--- a/docs/astro/src/content/docs/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/guides/ui-components.mdx
@@ -491,10 +491,32 @@ live-restyles everything already on screen — widgets record which theme *role*
each color came from (a `ThemeStyle` component, carried into prefabs too), so a
swap re-resolves hues while preserving each color's alpha.
+### The project theme
+
+A project declares its widget palette once, in **Project Settings → UI**: pick
+the base theme (**dark** is the default, **light** is built in), then override
+any **color role** in the **Theme Colors** group — a full color picker per
+role, with unset rows showing the inherited base value and a reset that clears
+the override. Overrides are stored in `project.esproject` as
+`features.ui.colors` (role → `#rrggbb[aa]` hex) and validated against the
+theme's role list.
+
+The resolved theme (base + overrides) applies **everywhere, identically**: the
+edit viewport previews it live as you change a setting, Play uses it, and every
+export target — web, desktop, WeChat, playable — resolves it at boot before
+re-theming widgets. Brand the accent by overriding `primary` (+ `primaryHover`
+/ `primaryActive`); `onPrimary` is the content drawn on top of it.
+
## Editor prefabs
The same widgets ship as editor prefabs, so **Create… → UI** drops a ready-made
Button, Toggle, Slider, Dialog, TextInput, and so on into the scene, which you then
edit in Details. Behavior that lives in components — a slider's drag/keys, a
-dialog's Escape/scrim dismissal — works on placed prefabs without code. See
+dialog's Escape/scrim dismissal — works on placed prefabs without code.
+
+Dropping from the palette **nests**: the drop parents into the layout container
+under the pointer (a dashed outline previews the would-be parent while you
+drag), and an empty-canvas drop lands at the root as before. The anchor picker
+edits **per axis** and keeps the widget exactly where it was — changing the
+horizontal anchor never disturbs the vertical layout, and vice versa. See
[The Editor](/docs/guides/editor/).
diff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
index 0cdc08c58..56c3d3e90 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
@@ -169,10 +169,11 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段
- **Sequencer** — 关键帧动画的时间轴/曲线编辑器。见 [时间轴](/docs/zh-cn/guides/timeline/)。
- **瓦片地图画笔** — **画笔、擦除、矩形、直线、油漆桶、选区、吸管**和**地形(autotile)**等工具,
外加图章 **水平翻转 / 垂直翻转 / 旋转 90°**(画笔工具激活时按 `H` / `V` / `R`)和一个
- **随机散布模式**。调色板用方向键选择(`Shift` 扩成多瓦片图章)。见
- [瓦片地图](/docs/zh-cn/guides/tilemap/)。
-- **瓦片集编辑器** — 标记每瓦片的**碰撞**(盒或多边形)和**地形**归属以做 autotile,并创作
- **动画瓦片**(帧序列 + 逐帧时长,带实时预览)。
+ **随机散布模式**(`D`)。调色板用方向键选择(`Shift` 扩成多瓦片图章),地图可以是
+ **正交、等距、交错或六边形**。见 [瓦片地图](/docs/zh-cn/guides/tilemap/)。
+- **瓦片集编辑器** — 创作每瓦片的**碰撞**(盒 / 圆 / 多边形、斜坡预设、单向 / 传感器 / 材质
+ 修饰)、autotile 用的**地形**集(edge/corner 邻接或多色**角 Wang**)、逐瓦片**概率**权重
+ 与属性,以及**动画瓦片**(帧序列 + 逐帧时长,带实时预览)。
- **状态机**(`.esfsm`)和**行为树**(`.esbt`)编辑器 — AI 的可视化图。见
[游戏 AI](/docs/zh-cn/guides/ai/)。
- **材质图**(`.esmatgraph`) — 编译成着色器的节点编辑器。见
@@ -191,6 +192,8 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段
- **显示** — 项目设计分辨率(播种新 Canvas + 驱动任意场景的设备预览)、项目级的**屏幕方向**
(所有导出目标都遵循它;留空则从设计分辨率的宽高比推导),以及**相机适配**(主相机如何在无 UI
Canvas 的情况下按设计分辨率缩放;`无`=关闭)。
+ - **UI** — 项目的控件**主题**(深色 / 浅色)与逐角色的**主题颜色**覆盖,在编辑器、Play
+ 和所有导出里一致生效。见 [UI 控件——主题](/docs/zh-cn/guides/ui-components/#主题)。
- **物理** — 启用、重力、十六个碰撞层名字和一个 16×16 碰撞矩阵,以及解算器调参(固定时间步、
子步、接触 Hz/阻尼/推出速度、允许睡眠、连续碰撞)。见 [物理](/docs/zh-cn/guides/physics/)。
- **渲染** — 命名排序层,填充检视器里的层下拉。
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 bab021cbe..bf430f39a 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -16,7 +16,8 @@ Estella 在 C++/WebAssembly 内核里渲染瓦片图层,按图集纹理合批并
**`Tilemap`** 组件把实体指向一个 Tiled JSON 文件,加载时为每个图层生成一个
**`TilemapLayer`** 实体。**`Tilemaps`** 资源是用代码创建与编辑图层的命令式 API。三种方式
最终都落到同一个运行时图层模型。瓦片 id 是**从 1 开始**的(`0` = 空)。**正交、等距、交错
-(staggered)、六边形**地图都能渲染——朝向从 Tiled 文件里读取,无需额外设置。
+(staggered)、六边形**地图都是一等公民——可以直接在编辑器里以任意朝向创作,也可以从
+Tiled 文件导入,无需额外设置。
## 在编辑器里绘制
@@ -42,11 +43,29 @@ Estella 在 C++/WebAssembly 内核里渲染瓦片图层,按图集纹理合批并
**方向键**移动选择,**Shift + 方向键**扩成印章。
- **图章库** —— 工具行下方的书签按钮把当前画笔存进按项目持久化的图章库;点击章片
即可换回该图案,`×` 删除。相同图案自动去重。
-- **随机模式** —— 打开骰子按钮,每个落笔格从印章里随机取一个瓦片,而不是重复图案——
- 给草地、碎石等做变化最快的方式。采样按图集编辑器属性模式里每个瓦片的 **概率** 权重
- 加权(默认 1;0 = 永不散布)。
+- **随机模式** —— 打开骰子按钮(或在绘制时按 `D`),每个落笔格从印章里随机取一个瓦片,
+ 而不是重复图案——给草地、碎石等做变化最快的方式。采样按图集编辑器属性模式里每个瓦片
+ 的 **概率** 权重加权(默认 1;0 = 永不散布)。
- **图层条** —— 场景里有多个瓦片图层时,面板顶部的图层条切换活动图层,并可逐层切换
- 可见性与锁定。
+ 可见性与锁定;**拖动图层章片**可以重排图层顺序。
+
+## 地图朝向
+
+朝向是每个 `TilemapLayer` 自己的属性,而不是导入痕迹。**新建瓦片地图**对话框在最开始就
+选好它——正交、**等距**(菱形)、**交错**(交错等距)或**六边形**——以及适用时的交错
+轴/起始行与六边形边长;之后 Inspector 编辑同一组字段。视口完全跟随图层:网格覆盖层、
+画笔虚影、悬停/选区高亮和所有绘制工具在菱形或六边形网格上的表现与方格完全一致。
+
+| `TilemapLayer` 字段 | 取值 | 说明 |
+|---|---|---|
+| `orientation` | Orthogonal / Isometric / Staggered / Hexagonal | 图层的网格布局。 |
+| `staggerAxis` | Y / X | 交错与六边形:`Y` 平移隔行,`X` 平移隔列。 |
+| `staggerIndex` | Odd / Even | 哪些行/列带半格平移。 |
+| `hexSideLength` | px | 仅六边形:平边长度(`0` = 规则尖顶六边形,即 `tileHeight / 2`)。 |
+
+任意朝向的 Tiled 地图导入到同一组字段——包括交错地图的 `staggeraxis` /
+`staggerindex`,导入后的落格与 Tiled 里所见完全一致。`examples/` 里有三个绘制好的
+演示:等距海岛、交错拼布和尖顶六边形战棋地图。
## 加载 Tiled 地图
@@ -88,6 +107,9 @@ const loadLevel = defineSystem([Commands()], (cmds) => {
| `parallaxFactor` | Vec2 | `{1, 1}` | 相对相机的视差滚动系数。 |
| `visible` | boolean | `true` | 显示 / 隐藏图层。 |
+外加上文的[朝向字段](#地图朝向)——`orientation`、`staggerAxis`、`staggerIndex`、
+`hexSideLength`。
+
## 用代码构建图层
生成一个实体,初始化一个图层,然后填充它:
@@ -153,6 +175,23 @@ tilemap.initInfiniteLayer(layer, 16, 16);
tilemap.setChunkTiles(layer, chunkX, chunkY, tiles, 32, 32);
```
+## 地形自动拼接
+
+地形让 `T` 画笔绘制的是*含义*而不是具体瓦片——你说"这里是草地",解析器自动挑出
+边缘与邻居吻合的那块瓦片。地形在**图集编辑器**的地形模式里创作;一个地形集使用
+两种模型之一:
+
+- **邻接(edge / corner-blob)** —— 经典单地形模型:每个瓦片声明它的哪些边
+ (16 瓦片集)或边+角(47 瓦片 blob 集)属于该地形,画笔绘制地形时自动修正
+ 邻居过渡。
+- **角 Wang(多地形)** —— Tiled/Godot 的现代模型:地形集携带一个**颜色**调色板
+ (草、沙、水……),每个瓦片给自己的四个**角**各指定一种颜色。一个集就能混合多种
+ 地形,画笔在**半格角网格**上绘制颜色——点在四块瓦片之间,解析器按角色精确匹配
+ 重排这四块(最近失配兜底),得到平滑的 marching-squares 边界。图集编辑器负责
+ 颜色调色板(添加 / 重命名 / 改色 / 删除)与逐瓦片角点;画笔面板列出可绘制的颜色。
+
+画笔的地形工具按地形集的模型自动分派。`examples/` 里有一个角 Wang 混合海岛演示。
+
## 图集与碰撞
引擎的一等图集资源是 **`.estileset`**——它引用一张图集纹理,并携带逐瓦片的碰撞、动画、
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
index 58f0c08f3..079dd9bff 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
@@ -458,9 +458,24 @@ events.on(entity, 'drag_start', () => { /* 还有 'drag_move' 与 'drag_end' */
来自哪个主题*角色*(`ThemeStyle` 组件,也随 prefab 持久化),换主题时按角色重新
解析色相并保留各自的 alpha。
+### 项目主题
+
+项目在**项目设置 → UI** 里一次性声明控件配色:先选基础主题(默认**深色**,内置
+**浅色**),再在**主题颜色**组里覆盖任意**颜色角色**——每个角色一个完整取色器,
+未设置的行显示继承的基础值,重置按钮清除覆盖。覆盖存进 `project.esproject` 的
+`features.ui.colors`(角色 → `#rrggbb[aa]` 十六进制),并按主题角色表校验。
+
+解析后的主题(基础 + 覆盖)**处处一致地生效**:改设置时编辑视口实时预览,Play
+使用它,每个导出目标——web、桌面、微信、playable——都在启动时先解析再给控件换肤。
+品牌色改 `primary`(以及 `primaryHover` / `primaryActive`)即可;`onPrimary`
+是画在它上面的内容色。
+
## 编辑器预制体
这些控件同时作为编辑器预制体提供,所以 **创建… → UI** 会把现成的 Button、Toggle、Slider、
Dialog、TextInput 等放进场景,你再在 Details 里编辑。存在组件里的行为——滑块的拖拽/方向键、
-对话框的 Escape/遮罩关闭——摆出来的 prefab 无需代码即可用。见
-[编辑器](/docs/zh-cn/guides/editor/)。
+对话框的 Escape/遮罩关闭——摆出来的 prefab 无需代码即可用。
+
+从调色板拖放会**嵌套**:放手时会父接到指针下方的布局容器里(拖动过程中虚线描边预览
+将要嵌入的父级),拖到空画布则照旧落在根上。锚点选择器**按轴**编辑且保持控件原位——
+改横向锚点绝不打扰纵向布局,反之亦然。见 [编辑器](/docs/zh-cn/guides/editor/)。