舞台和全局设置

了解“舞台”

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

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

逻辑尺寸和物理尺寸

在游戏开发中，我们通常会使用逻辑尺寸来表示游戏中的各种尺寸，而不是直接使用像素尺寸。这是因为不同的设备有不同的屏幕尺寸和像素密度（缩放比例/DPI/PPI），直接使用像素尺寸会导致游戏在不同设备上显示效果不一致。

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

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

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

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

舞台与全局设置

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

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

index.json

{
  "$schema": "https://gist.githubusercontent.com/Icemic/55a8cd86b02c0c310f51833e88f7d083/raw/moyu-config.schema.json",
  "surface_size": "1280x720",
  "stage_size": "1920x1080",
  "window_title": "My First Game",
  "entry_filename": "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	窗口是否可调整大小。
surfaceSize	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。通常用于调试，请勿在发布版中设置。