Custom platform ports
Similar to Custom modules in 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.
Some reasons to create custom platform ports might be:
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.
Note
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.
Official platform ports
The official platform ports can be used as a reference when creating a custom platform port:
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.
Creating a custom platform port
Creating a custom platform port is a large undertaking which requires prior knowledge of the platform's SDKs. Depending on what features you need, the amount of work needed varies:
Required features of a platform port
At the very least, a platform port must have methods from the OS
singleton implemented to be buildable and usable for headless operation.
A logo.svg (32×32) vector image must also be present within the platform
folder. This logo is displayed in the Export dialog for each export preset
targeting the platform in question.
See this implementation for the Linux/*BSD platform as an example. See also the OS singleton header for reference.
Note
If your target platform is UNIX-like, consider inheriting from the OS_Unix
class to get much of the work done automatically.
If the platform is not UNIX-like, you might use the Windows port as a reference.
detect.py file
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.
All methods should be implemented within detect.py as follows:
is_active(): Can be used to temporarily disable building for a platform. This should generally always returnTrue.get_name(): Returns the platform's user-visible name as a string.can_build(): ReturnTrueif the host system is able to build for the target platform,Falseotherwise. Do not put slow checks here, as this is queried when the list of platforms is requested by the user. Useconfigure()for extensive dependency checks instead.get_opts(): Returns the list of SCons build options that can be defined by the user for this platform.get_flags(): Returns the list of overridden SCons flags for this platform.configure(): Perform build configuration, such as selecting compiler options depending on SCons options chosen.
Optional features of a platform port
In practice, headless operation doesn't suffice if you want to see anything on screen and handle input devices. You may also want audio output for most games.
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_IDand 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 thedrivers/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 One-click deploy). 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 One-click deploy 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.
Distributing a custom platform port
Danger
Before distributing a custom platform port, make sure you're allowed to distribute all the code that is being linked against. Console SDKs are typically under NDAs which prevent redistribution to the public.
Platform ports are designed to be as self-contained as possible. Most of the
code can be kept within a single folder located in platform/. Like
Custom modules in C++, this allows for streamlining the build process
by making it possible to git clone a platform folder within a Godot repository
clone's platform/ folder, then run scons platform=<name>. No other steps are
necessary for building, unless third-party platform-specific dependencies need
to be installed first.
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.