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(editor): document editing modes + the UI-mode design frame

esenginef9a84bb5512d
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdx
index d54e1a7a1..0859cb12e 100644
--- a/docs/astro/src/content/docs/guides/editor.mdx
+++ b/docs/astro/src/content/docs/guides/editor.mdx
@@ -38,7 +38,7 @@ renaming a file doesn't break references.
The default layout, from the outside in:
-- **Activity Bar** — the far-left icon rail (open side panels, project settings).
+- **Activity Bar** — the far-left icon rail: the **editing mode** (Scene / UI / Tilemap), side panels, and project settings.
- **Menu Bar** — File · Edit · Entity · View · Build · Window · Help.
- **Toolbar** — Save, Undo/Redo, the transform tools, snapping, Show Grid, the **Play**
controls, Show Gizmos, and Build.
@@ -96,6 +96,28 @@ overlay, plus World/Local axis orientation and Pivot-vs-Center. Entities that do
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.
+## Editing modes
+
+The Activity Bar's top three icons switch the **editing mode** — **Scene**, **UI**, or
+**Tilemap**. The mode also *follows your selection*: pick a `Canvas` or `UINode` and the
+editor suggests **UI** mode, a `TilemapLayer` suggests **Tilemap**. Each mode reveals its
+companion panels (UI Widgets, the Tilemap painter) and its viewport aids; clicking a mode
+pins it until your selection implies another.
+
+**UI mode — the design frame.** UI is authored against the Canvas' **design resolution** —
+a fixed reference size (e.g. `1920 × 1080` landscape or `750 × 1334` portrait). In UI mode
+the viewport draws that design frame and, on entry, **frames it** and dims everything
+outside, so it reads as the target screen. The editor is **WYSIWYG** with it: what you lay
+out inside the frame is exactly what ships at that resolution — edge-anchored UI sits at the
+frame's corners, and a portrait resolution lays out as a portrait screen.
+
+- **Design** dropdown (viewport toolbar) — picks the Canvas design resolution and reframes
+ to it (undoable; the authoritative value also lives on the Canvas in the Details panel).
+ This is the size your UI lays out against.
+- **Device** dropdown — *simulates* a target screen (iPhone / iPad / 1080p …) with letterbox
+ bars and safe-area insets, to preview how the UI adapts. It's a preview only — it does
+ **not** change your design resolution.
+
## Building a scene
### Creating entities
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 17fdfddb9..0866a2d70 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
@@ -35,7 +35,7 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
从外到内的默认布局:
-- **活动栏(Activity Bar)** — 最左侧的图标竖条(打开侧面板、项目设置)。
+- **活动栏(Activity Bar)** — 最左侧的图标竖条:**编辑模式**(场景 / UI / 瓦片地图)、侧面板、项目设置。
- **菜单栏** — 文件 · 编辑 · 实体 · 视图 · 构建 · 窗口 · 帮助。
- **工具栏** — 保存、撤销/重做、各变换工具、吸附、显示网格、**运行**控制、显示 gizmo、构建。
- **视口**(中央) — 实时 WebGL 场景视图。
@@ -86,6 +86,23 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可
和轴心/中心。不渲染的实体——相机、`Light2D`、碰撞体——在编辑模式下画成 gizmo(图标、视野矩形、
光照范围/锥、碰撞体轮廓),让你能看见并摆放它们。
+## 编辑模式
+
+活动栏顶部三个图标切换**编辑模式**——**场景(Scene)**、**UI**、**瓦片地图(Tilemap)**。模式也会
+*跟随你的选择*:选中 `Canvas` 或 `UINode`,编辑器建议 **UI** 模式,选中 `TilemapLayer` 建议**瓦片
+地图**模式。每个模式会露出其配套面板(UI 控件面板、瓦片地图绘制器)和对应的视口辅助;点击某个模式会
+固定它,直到你的选择指向另一个模式。
+
+**UI 模式——设计框。** UI 是对着 Canvas 的**设计分辨率**创作的——一个固定的参考尺寸(比如横屏
+`1920 × 1080` 或竖屏 `750 × 1334`)。UI 模式下视口会画出这个设计框,并在进入时**自动成帧**、把框外
+压暗,让它读起来就是目标屏幕。编辑器与它**所见即所得**:你在框内摆放的,就是在该分辨率下发布时的样子
+——边缘锚定的 UI 落在框的角上,竖屏分辨率就布局成竖屏。
+
+- **Design** 下拉(视口工具栏)——选择 Canvas 设计分辨率并成帧到它(可撤销;权威值同时在 Details
+ 面板的 Canvas 上)。这就是你的 UI 布局所对的尺寸。
+- **Device** 下拉——*模拟*一个目标屏幕(iPhone / iPad / 1080p …),带 letterbox 黑边和安全区内缩,
+ 预览 UI 如何适配。它只是预览,**不会**改动你的设计分辨率。
+
## 搭建场景
### 创建实体