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(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.mdxindex 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 recompanion panels (UI Widgets, the Tilemap painter) and its viewport aids; clicking a modepins 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 gsnapping, gizmos), **Keyboard Shortcuts** (every shortcut below is rebindablehere), 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 collisionmatrix, plus solver tuning (fixed timestep, sub-steps, contact Hz/damping/pushspeed, 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.mdxindex 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/)。- **渲染** — 命名排序层,填充检视器里的层下拉。