Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

自定义平台的移植

Similar to 自定义 C++ 模块, Godot's multi-platform architecture is designed in a way that allows creating platform ports without modifying any existing source code.

An example of a custom platform port distributed independently from the engine is FRT, which targets single-board computers. Note that this platform port currently targets Godot 3.x; therefore, it does not use the DisplayServer abstraction that is new in Godot 4.

创建自定义平台移植可能有以下原因：

• You want to port your game to consoles, but wish to write the platform layer yourself. This is a long and arduous process, as it requires signing NDAs with console manufacturers, but it allows you to have full control over the console porting process.

• You want to port Godot to an exotic platform that isn't currently supported.

If you have questions about creating a custom platform port, feel free to ask in the #platforms channel of the Godot Contributors Chat.

备注

Godot is a modern engine with modern requirements. Even if you only intend to run simple 2D projects on the target platform, it still requires an amount of memory that makes it unviable to run on most retro consoles. For reference, in Godot 4, an empty project with nothing visible requires about 100 MB of RAM to run on Linux (50 MB in headless mode).

If you want to run Godot on heavily memory-constrained platforms, older Godot versions have lower memory requirements. The porting process is similar, with the exception of DisplayServer not being split from the OS singleton.

官方的平台移植

创建自定义平台移植时，可以使用官方的平台移植作为参考：

• Windows

• macOS

• Linux/*BSD

• Android

• iOS

• Web

While platform code is usually self-contained, there are exceptions to this rule. For instance, audio drivers that are shared across several platforms and rendering drivers are located in the drivers/ folder of the Godot source code.

创建自定义平台移植

创建自定义平台移植是一项繁重的工作，同时需要熟悉对应平台的 SDK。工作量因所需的功能而异：

平台移植的必要功能

平台移植至少需要实现 OS 单例中的方法才能够进行构建，用于无头操作。平台文件夹中还需要存在一张名为 logo.svg 的矢量图（32×32）。“导出”对话框中为该平台定义的导出预设就会显示这个图标。

示例实现请参考 Linux/*BSD 平台。另见 OS 单例头文件。

备注

如果你的目标平台是类 UNIX 平台，请考虑继承 OS_Unix 类，这样就能够自动完成大量工作。

If the platform is not UNIX-like, you might use the Windows port as a reference.

detect.py 文件

A detect.py file must be created within the platform's folder with all methods implemented. This file is required for SCons to detect the platform as a valid option for compiling. See the detect.py file for the Linux/*BSD platform as an example.

detect.py 应实现如下所有方法：

• is_active()：可以用来临时禁用某个平台的构建。一般都应该返回 True。

• get_name()：返回平台的用户可见名称字符串。

• can_build()：如果宿主系统能够构建目标平台则返回 True，否则返回 False。请勿在此处进行耗时的检查，用户请求平台列表时会查询该函数。大量的依赖项检查请使用 configure()。

• get_opts()：返回用户能够为该平台定义的 Scons 构建选项列表。

• get_flags()：返回该平台覆盖的 Scons 标识列表。

• configure()：执行构建配置，例如根据所选的 SCons 选项调整编译器选项。

平台移植的可选功能

实践中，如果你想要在屏幕和手持输入设备上看到画面，那么需要的就不仅仅是无头操作。大多数游戏可能还会需要音频输出。

Some links on this list point to the Linux/*BSD platform implementation as a reference.

• One or more DisplayServers, with the windowing methods implemented. DisplayServer also covers features such as mouse support, touchscreen support and tablet driver (for pen input). See the DisplayServer singleton header for reference.

  • For platforms not featuring full windowing support (or if it's not relevant for the port you are making), most windowing functions can be left mostly unimplemented. These functions can be made to only check if the window ID is MAIN_WINDOW_ID and specific operations like resizing may be tied to the platform's screen resolution feature (if relevant). Any attempt to create or manipulate other window IDs can be rejected.

• If the target platform supports the graphics APIs in question: Rendering context for Vulkan, Direct3D 12 OpenGL 3.3 or OpenGL ES 3.0.

• Input handlers for keyboard and controller.

• One or more audio drivers. The audio driver can be located in the platform/ folder (this is done for the Android and Web platforms), or in the drivers/ folder if multiple platforms may be using this audio driver. See the AudioServer singleton header for reference.

• Crash handler, for printing crash backtraces when the game crashes. This allows for easier troubleshooting on platforms where logs aren't readily accessible.

• Text-to-speech driver (for accessibility).

• Export handler (for exporting from the editor, including 一键部署). Not required if you intend to export only a PCK from the editor, then run the export template binary directly by renaming it to match the PCK file. See the EditorExportPlatform header for reference. run_icon.svg (16×16) should be present within the platform folder if 一键部署 is implemented for the target platform. This icon is displayed at the top of the editor when one-click deploy is set up for the target platform.

If the target platform doesn't support running Vulkan, Direct3D 12, OpenGL 3.3, or OpenGL ES 3.0, you have two options:

• Use a library at runtime to translate Vulkan or OpenGL calls to another graphics API. For example, MoltenVK is used on macOS to translate Vulkan to Metal at runtime.

• Create a new renderer from scratch. This is a large undertaking, especially if you want to support both 2D and 3D rendering with advanced features.

分发自定义平台移植

危险

分发自定义平台移植之前，请先确定你有权利分发所有被链接的代码。主机平台的 SDK 通常存在相关的保密协议，禁止向公众进行二次分发。

平台移植的设计尽量做到了自包含。大多数代码都在 platform/ 下的某个文件夹中。这种设计与 自定义 C++ 模块 类似，能够允许将平台文件夹 git clone 至 Godot 仓库副本的 platform/ 文件夹中，后续执行 scons platform=<name> 即可，使得构建过程流水线化。除非有第三方平台特定的依赖项需要安装，否则构建时不需要其他步骤。

However, when a custom rendering driver is needed, another folder must be added in drivers/. In this case, the platform port can be distributed as a fork of the Godot repository, or as a collection of several folders that can be added over a Godot Git repository clone.