舞台与全局设置

了解“舞台”

所有的游戏内容都是在舞台上展示的。舞台是一个矩形区域，它是游戏中所有内容的容器。对一个特定的游戏而言，舞台的大小总是固定不变的，我们称之为“舞台尺寸（stage size）”，它是一个逻辑尺寸。

舞台的尺寸并不直接决定最终显示的大小（即操作系统中窗口的大小）。舞台在显示时会被缩放到特定的窗口表面（surface）上，各种游戏中常见的“分辨率设置”或全屏选项即是在设置窗口表面的大小，我们称之为“表面尺寸（surface size）”，它也是一个逻辑尺寸。

正确选择舞台和表面的尺寸

读到这里，或许你仍然不知道如何选择正确的舞台和表面尺寸。那么，你只要记得两点：

舞台尺寸应该是你游戏中所有内容的逻辑尺寸，比如 1920x1080 或 1280x720。如果你的 UI 设计稿使用 1920x1080，那么就用它没错。这样你在开发过程中可以直接使用设计稿中的坐标，而不需要进行额外的缩放计算。
表面尺寸是你窗口的默认大小。一般来说它应该是一个小一些的值，比如 1280x720。这样可以确保游戏第一次运行时在大多数设备上都能正常显示，而不会因为窗口太大而导致内容显示不全。当然，这里只是“默认”大小，在你的游戏脚本中仍旧可以通过代码随时调整窗口大小。

我们推荐使用 1920x1080 或 1280x720 作为舞台尺寸，1280x720 作为表面尺寸。

舞台与全局设置

对于一个游戏，我们首先要配置合适的全局配置，这包括前面提到的舞台相关的设置，以及其他一些全局设置，比如游戏的标题、字体等。在末语游戏引擎中，我们通常使用工程目录下的 index.json 文件来配置他们。

下面是一个简单的 index.json 文件示例：

{
  "$schema": "https://gist.githubusercontent.com/Icemic/55a8cd86b02c0c310f51833e88f7d083/raw/moyu-config.schema.json",
  "initialSurfaceSize": "1280x720",
  "stageSize": "1920x1080",
  "windowTitle": "My First Game",
  "entryFilename": "index.js"
}

在这个配置文件中，我们配置了表面尺寸为 1280x720，舞台尺寸为 1920x1080，窗口标题为 My First Game，入口文件为 index.js。

关于 $schema 字段

$schema 字段是一个特殊字段，指定配置文件的 JSON Schema，用于编辑器的自动补全和检查。通常情况下，你不需要手动修改这个字段，保持其原样即可。

以下是所有可配置的字段列表：

字段名	类型	默认值	描述
entry	string	`./index.json`	重定向游戏入口点，可以是绝对路径或相对路径。这也指定了其他资源（assets）的根路径。通常无需设置。
entryFilename	string	`index.js`	游戏的入口文件名，相对于根路径。除非你知道自己在做什么，否则不要更改此项。
fontFile	string	`fonts/default.otf`	用于渲染文本的字体文件，必须相对于根路径。支持 .otf 和 .ttf 格式。
windowTitle	string	`moyu`	窗口的标题。
windowState	string	`idle`	窗口的初始状态。可能的值：`idle`, `minimized`, `maximized`, `fullscreen`。
windowResizable	boolean	false	窗口可否任意调整大小。
initialSurfaceSize	string	`1280x720`	表面的初始尺寸。
stageSize	string	`1280x720`	舞台的尺寸。
presentMode	string	`recommended`	表面的呈现模式。可能的值：`recommended`, `autovsync`, `autonovsync`。除非你知道自己在做什么，否则不要更改此项。
backend	string	`auto`	用于渲染的后端。可能的值：`auto`, `dx12`, `vulkan`, `gles`, `metal`, `webgpu`。除非你知道自己在做什么，否则不要更改此项。
desiredMaximumFrameLatency	number	2	期望的最大帧延迟。除非你知道自己在做什么，否则不要更改此项。
showFPS	boolean	false	是否显示 FPS。通常用于调试，请勿在发布版中设置。
enableGamepads	boolean	false	是否启用游戏手柄支持。详见手柄与其他 API
enableMSAA	boolean	false	是否启用 4 倍多重采样抗锯齿（4× MSAA），用于改善图形边缘的锯齿。
enableMipmaps	boolean	false	是否为静态图片生成 mipmap，用于改善图片缩小时的清晰度和稳定性。

多重采样抗锯齿（MSAA）

将 enableMSAA 设置为 true 后，引擎会启用 4× MSAA。它主要改善 Sprite 等图形在旋转、缩放或显示斜边时产生的锯齿，也会应用于 Filter 和 Shader 中实际绘制场景内容的部分。

MSAA 会增加 GPU 的显存占用和渲染开销。文字使用 SDF 渲染，Filter 和 Shader 自身产生的着色效果也主要由对应的着色器决定，因此开启 MSAA 通常不会明显改善这些内容。建议根据游戏画面和目标设备的性能测试结果决定是否开启。

静态图片 mipmap

将 enableMipmaps 设置为 true 后，引擎会在静态图片载入时生成一组逐级缩小的纹理。图片被缩小显示时，GPU 会从合适的层级采样，可以减少摩尔纹、闪烁和细节跳动，尤其适合会被大幅缩小、旋转或远距离显示的图片。

目前 mipmap 适用于通过资源管理器载入的静态图片，包括 Sprite 使用的图片和启动图。Animation、Video、文字 SDF 纹理、Filter、Backdrop、Shader 渲染目标和截图不会生成 mipmap。

生成 mipmap 会增加图片载入时的 GPU 工作量，并占用约三分之一的额外纹理显存。图片始终按接近原始尺寸显示时，收益通常不明显；如果游戏中经常缩小图片，建议开启并在目标设备上进行测试。