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: the editor's new creation surfaces reach the guides, EN + zh

yhh36d4189e4302
diff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/guides/ai.mdx
index 649d2f6c5..8b7caafe5 100644
--- a/docs/astro/src/content/docs/guides/ai.mdx
+++ b/docs/astro/src/content/docs/guides/ai.mdx
@@ -130,6 +130,11 @@ FSM only flips its flags. Built-in names never shadow yours: if you register an
action or condition under the same name, your registration wins. Avoid the
`timeline.` prefix for game names to keep the namespaces apart.
+In the FSM / behavior-tree editors, the action and condition fields suggest every
+registered name as you type — grouped by namespace, with built-ins carrying a short
+description of what they do. Free text stays legal for names your game registers at
+runtime.
+
The [`cutscene` example](https://github.com/esengine/estella/tree/master/examples/cutscene)
is this pattern end-to-end: an intro timeline plays on scene start, gameplay
unlocks when it completes, and R replays it — with zero registered actions.
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdx
index 8183d6717..a9106b8f4 100644
--- a/docs/astro/src/content/docs/guides/editor.mdx
+++ b/docs/astro/src/content/docs/guides/editor.mdx
@@ -91,10 +91,12 @@ copies. Nudge the selection with the **arrow keys** (one grid step; hold **Shift
**Snapping** — toggle snapping from the viewport's Snap dropdown and set the grid step,
rotation angle, and scale increment.
-**Show Flags** — a viewport dropdown toggles the Grid, Gizmos, Colliders, and the perf
+**Show Flags** — a viewport dropdown toggles the Grid, Gizmos, Physics, and the perf
overlay, plus World/Local axis orientation and Pivot-vs-Center. Entities that don't
-render — Cameras, `Light2D`, and colliders — are drawn as gizmos in edit mode (icon,
-view rect, light reach/cone, collider outline) so you can see and place them.
+render — Cameras, `Light2D`, colliders, joints, particle emitters — are drawn as
+gizmos in edit mode (icon, view rect, light reach/cone, collider outline, joint
+anchor links) so you can see and place them; many carry drag handles that write
+their fields directly (light radius, collider size, emitter shape, joint anchors).
## Editing modes
diff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/guides/physics.mdx
index 24019ef2e..1c32dbded 100644
--- a/docs/astro/src/content/docs/guides/physics.mdx
+++ b/docs/astro/src/content/docs/guides/physics.mdx
@@ -231,6 +231,15 @@ world.spawn(MotorJoint, {
physics.setMotorJointLinearVelocity(crate, { x: -200, y: 0 }); // reverse at runtime
```
+### In the editor
+
+Scene-authored joints draw a gizmo in the viewport: a dashed link between the two
+anchors, with the anchor dots **draggable** — dragging writes `anchorA` / `anchorB`
+in the owning body's local frame. Prismatic and wheel joints also show their slide
+axis; drag its tip to re-aim the axis. Motor joints show an arrow along their target
+linear velocity. The whole family (colliders, one-way arrows, joints) is toggled by
+the **Physics** entry in the viewport's Show Flags.
+
## One-way platforms
Add `OneWayPlatform` to a static (or kinematic) collider to make it **one-sided** — a
@@ -251,6 +260,8 @@ world.spawn(
`normal` is the solid-side direction in world space; `{ x: 0, y: 1 }` (the default)
means "solid top". Set `enabled: false` to turn the platform back into a normal solid.
+In the editor, a one-way platform's collider gizmo grows an arrow along the solid-side
+normal, so which way it carries is visible at a glance.
## Mouse / drag joint
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index 631a71b55..e0ed2e3ee 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -33,6 +33,7 @@ viewport — a stamp ghost previews every stroke:
| Brush | `B` | Paint the current stamp; drag for strokes. |
| Erase | `E` | Clear tiles. |
| Rectangle | `U` | Fill a dragged rectangle with the stamp pattern. |
+| Ellipse | `O` | Drag a bounding box, fill its inscribed ellipse. |
| Line | `L` | Lay the stamp along a straight line. |
| Bucket | `G` | Flood-fill the connected region of matching tiles. |
| Select | `M` | Marquee a region — `mod + C` / `X` copy / cut it, `Delete` clears it, `mod + V` pastes it as the brush. |
@@ -45,6 +46,9 @@ While a paint tool is active, `H` / `V` flip the stamp and `R` rotates it 90°.
- **Multi-tile stamps** — drag across the palette to grab a block of tiles as one
stamp. The palette is keyboard-friendly too: **arrow keys** move the selection,
**Shift + arrows** grow it into a stamp.
+- **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.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
index e2d1c5f0f..676b63bea 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
@@ -116,6 +116,10 @@ registerFsm('intro', {
旗标。内建名字永远不会遮蔽你的注册:同名时你的注册获胜。游戏侧的名字请避开
`timeline.` 前缀,保持命名空间分离。
+在 FSM / 行为树编辑器里,动作与条件输入框会随输入提示所有已注册的名字——按命名
+空间分组,内建项带一行"它做什么"的说明。自由输入仍然合法,留给游戏运行时注册的
+名字。
+
[`cutscene` 示例](https://github.com/esengine/estella/tree/master/examples/cutscene)
就是这个模式的完整落地:场景开始即播开场时间轴,播完解锁操作,按 R 重播——
全程零注册动作。
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 059655819..a116b9765 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
@@ -82,9 +82,10 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
**吸附** — 从视口的吸附下拉里开关吸附,并设置网格步长、旋转角度和缩放增量。
-**显示标志(Show Flags)** — 视口下拉可开关网格、gizmo、碰撞体和性能浮层,以及世界/本地轴朝向
-和轴心/中心。不渲染的实体——相机、`Light2D`、碰撞体——在编辑模式下画成 gizmo(图标、视野矩形、
-光照范围/锥、碰撞体轮廓),让你能看见并摆放它们。
+**显示标志(Show Flags)** — 视口下拉可开关网格、gizmo、物理和性能浮层,以及世界/本地轴朝向
+和轴心/中心。不渲染的实体——相机、`Light2D`、碰撞体、关节、粒子发射器——在编辑模式下画成
+gizmo(图标、视野矩形、光照范围/锥、碰撞体轮廓、关节锚点连线),让你能看见并摆放它们;
+多数还带可拖拽的 handle,直接写回字段(灯光半径、碰撞体尺寸、发射器形状、关节锚点)。
## 编辑模式
diff --git a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx b/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
index 3f7ec8a6c..d65e20382 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
@@ -221,6 +221,13 @@ world.spawn(MotorJoint, {
physics.setMotorJointLinearVelocity(crate, { x: -200, y: 0 }); // 运行时反向
```
+### 在编辑器里
+
+场景创作的关节会在视口画出 gizmo:两个锚点之间的虚线连线,锚点圆点**可以拖拽**——
+拖动即写入 `anchorA` / `anchorB`(各自刚体的局部坐标)。棱柱/轮式关节还会画出滑动轴,
+拖它的端点即可重新指向;马达关节沿目标线速度画出箭头。整个家族(碰撞体、单向箭头、
+关节)由视口显示标记里的**物理**项统一开关。
+
## 单向平台
给静态(或运动学)碰撞体加 `OneWayPlatform`,使其**单面**——刚体从一个方向落上去、从其它
@@ -239,7 +246,8 @@ world.spawn(
```
`normal` 是世界空间里的实心侧方向;`{ x: 0, y: 1 }`(默认)= "实心顶面"。设 `enabled: false`
-让平台恢复为普通实心体。
+让平台恢复为普通实心体。在编辑器里,单向平台的碰撞体 gizmo 会沿实心侧法线多画一支箭头,
+朝向一眼可辨。
## 鼠标 / 拖拽关节
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 c9496fd1b..b154b79db 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -28,6 +28,7 @@ Estella 在 C++/WebAssembly 内核里渲染瓦片图层,按图集纹理合批并
| 画笔 | `B` | 绘制当前印章;拖动连续作画。 |
| 橡皮 | `E` | 清除瓦片。 |
| 矩形 | `U` | 用印章图案填充拖出的矩形。 |
+| 椭圆 | `O` | 拖出包围盒,填充其内切椭圆。 |
| 直线 | `L` | 沿直线铺设印章。 |
| 油漆桶 | `G` | 泛洪填充相连的同类瓦片区域。 |
| 框选 | `M` | 框选一块区域——`mod + C` / `X` 复制 / 剪切,`Delete` 清空,`mod + V` 作为画笔粘贴。 |
@@ -39,6 +40,8 @@ Estella 在 C++/WebAssembly 内核里渲染瓦片图层,按图集纹理合批并
- **多瓦片印章** —— 在调色板上拖动,把一整块瓦片抓成一个印章。调色板也支持键盘:
**方向键**移动选择,**Shift + 方向键**扩成印章。
+- **图章库** —— 工具行下方的书签按钮把当前画笔存进按项目持久化的图章库;点击章片
+ 即可换回该图案,`×` 删除。相同图案自动去重。
- **随机模式** —— 打开骰子按钮,每个落笔格从印章里随机取一个瓦片,而不是重复图案——
给草地、碎石等做变化最快的方式。
- **图层条** —— 场景里有多个瓦片图层时,面板顶部的图层条切换活动图层,并可逐层切换