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): design resolution + device preview are project-level, not UI-only

yhhf17bbf4ed7d6
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/guides/editor.mdx
index 84df43c3b..185b05702 100644
--- a/docs/astro/src/content/docs/guides/editor.mdx
+++ b/docs/astro/src/content/docs/guides/editor.mdx
@@ -106,20 +106,22 @@ editor suggests **UI** mode, a `TilemapLayer` suggests **Tilemap**. Each mode re
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 …): the UI
- **relayouts to that device's aspect** (per the Canvas scale mode) inside letterbox bars and
- safe-area insets, so you preview how it actually adapts. A preview only — it does **not**
- change your design resolution.
+**The design frame + device preview.** A scene is authored against a **design resolution** —
+a fixed reference size (e.g. `1920 × 1080` landscape or `750 × 1334` portrait). This is a
+**project-level** value (Project Settings → Display), not a UI-layer one: the viewport's
+**Design** and **Device** controls work in **every** editor mode (Scene / UI / Tilemap), so
+you can preview a gameplay-only scene on a real device **without** a UI Canvas. When the
+scene has a Canvas, UI additionally lays out inside the frame per its scale mode.
+
+- **Design** dropdown (viewport toolbar) — sets the design resolution and reframes to it
+ (undoable). With a Canvas it edits that Canvas; otherwise it edits the project value.
+- **Device** dropdown — *simulates* a target screen (iPhone / iPad / 1080p …) in any mode:
+ draws the device's aspect as letterbox bars + safe-area insets over your scene, so you
+ preview how it fits. A preview only — it does **not** change your design resolution.
+- **Camera Fit** (Project Settings → Display) — how the **main camera** scales the design
+ resolution, independent of any UI Canvas. `None` (default) keeps the camera's own
+ orthoSize; any other mode letterboxes the game the same way on every device, and the
+ device preview then shows the **real** framing (WYSIWYG for gameplay, not just UI).
## Building a scene
@@ -225,9 +227,10 @@ Open settings with **Ctrl / ⌘ + ,** or the Activity Bar's gear. Settings are g
snapping, gizmos), **Keyboard Shortcuts** (every shortcut below is rebindable
here), and Console.
- **Project** (saved into `project.esproject`):
- - **Display** — the design resolution new Canvases seed from, and the project-wide
- **screen orientation** (every export target honors it; unset ⇒ derived from the
- design resolution's aspect).
+ - **Display** — the project design resolution (seeds new Canvases + drives the device
+ 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).
- **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/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
index 72ac4a6ab..0cdc08c58 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/editor.mdx
@@ -94,16 +94,18 @@ gizmo(图标、视野矩形、光照范围/锥、碰撞体轮廓、关节锚点
地图**模式。每个模式会露出其配套面板(UI 控件面板、瓦片地图绘制器)和对应的视口辅助;点击某个模式会
固定它,直到你的选择指向另一个模式。
-**UI 模式——设计框。** UI 是对着 Canvas 的**设计分辨率**创作的——一个固定的参考尺寸(比如横屏
-`1920 × 1080` 或竖屏 `750 × 1334`)。UI 模式下视口会画出这个设计框,并在进入时**自动成帧**、把框外
-压暗,让它读起来就是目标屏幕。编辑器与它**所见即所得**:你在框内摆放的,就是在该分辨率下发布时的样子
-——边缘锚定的 UI 落在框的角上,竖屏分辨率就布局成竖屏。
-
-- **Design** 下拉(视口工具栏)——选择 Canvas 设计分辨率并成帧到它(可撤销;权威值同时在 Details
- 面板的 Canvas 上)。这就是你的 UI 布局所对的尺寸。
-- **Device** 下拉——*模拟*一个目标屏幕(iPhone / iPad / 1080p …):UI 会**按该设备的宽高比重新
- 布局**(依 Canvas 缩放模式),配 letterbox 黑边和安全区内缩,预览它真实的适配效果。只是预览,
- **不会**改动你的设计分辨率。
+**设计框与设备预览。** 场景是对着**设计分辨率**创作的——一个固定的参考尺寸(比如横屏
+`1920 × 1080` 或竖屏 `750 × 1334`)。它是**项目级**的值(项目设置 → 显示),不属于 UI 层:视口的
+**Design** 和 **Device** 控件在**每种**编辑模式(场景 / UI / 瓦片地图)都可用,所以纯玩法场景**无需**
+UI Canvas 也能在真机上预览。场景里有 Canvas 时,UI 会额外按其缩放模式在框内布局。
+
+- **Design** 下拉(视口工具栏)——设置设计分辨率并成帧到它(可撤销)。有 Canvas 时改的是该 Canvas,
+ 否则改的是项目值。
+- **Device** 下拉——在任意模式*模拟*一个目标屏幕(iPhone / iPad / 1080p …):在场景上画出该设备宽高比的
+ letterbox 黑边和安全区,预览它如何适配。只是预览,**不会**改动你的设计分辨率。
+- **相机适配**(项目设置 → 显示)——**主相机**如何按设计分辨率缩放,独立于任何 UI Canvas。`无`(默认)
+ 保持相机自身的 orthoSize;其他模式让游戏在每台设备上一致 letterbox,设备预览也随之显示**真实**取景
+ (玩法也所见即所得,不止 UI)。
## 搭建场景
@@ -186,8 +188,9 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段
- **编辑器** — 外观(**语言**、强调色、UI 缩放)、视口(网格、吸附、gizmo)、**键盘快捷键**(下面每个快捷键
都能在这里重绑)、控制台。
- **项目**(存进 `project.esproject`):
- - **显示** — 新建 Canvas 播种用的设计分辨率,以及项目级的**屏幕方向**(所有导出目标都遵循它;
- 留空则从设计分辨率的宽高比推导)。
+ - **显示** — 项目设计分辨率(播种新 Canvas + 驱动任意场景的设备预览)、项目级的**屏幕方向**
+ (所有导出目标都遵循它;留空则从设计分辨率的宽高比推导),以及**相机适配**(主相机如何在无 UI
+ Canvas 的情况下按设计分辨率缩放;`无`=关闭)。
- **物理** — 启用、重力、十六个碰撞层名字和一个 16×16 碰撞矩阵,以及解算器调参(固定时间步、
子步、接触 Hz/阻尼/推出速度、允许睡眠、连续碰撞)。见 [物理](/docs/zh-cn/guides/physics/)。
- **渲染** — 命名排序层,填充检视器里的层下拉。