Porting to a new platform — documentation

A platform port adds a new operating system or device to a native Reckfell build. It requires C++, the target SDK and SCons. A game using an already supported platform normally needs an export, not a new engine port.

Define the deliverable first

Separate three tasks: running an application on the device, building an export template, and exporting from the developer’s desktop editor. Completing the first does not supply the other two. C# also needs a working target .NET environment; a native port alone does not provide it.

Build in a separate source checkout. Do not replace the installed editor or working templates before checking the new binary. See the build overview for prerequisites and the known local SCons helper limitation.

How the build discovers a platform

Paths below are relative to Source. The directory name supplies the identifier: platform/my_platform corresponds to platform=my_platform.

File or function	Requirement
`platform/my_platform/detect.py`	Without this file, the directory is not considered during discovery.
`can_build()`	Takes no arguments. Reports whether the current host can build the port. Avoid side effects: discovery calls it.
`get_opts()`	Platform SCons options. Called when `can_build()` returns true.
`get_flags()`	Platform option defaults; use a dictionary for a new port.
`configure(env)`	Configures the selected platform: compiler, SDK, architecture, include paths and linking.
`platform/my_platform/SCsub`	Selects sources and creates the target executable or library.

The current discovery loop does not call is_active(). Existing ports define get_name(), but it does not select the platform=… identifier. Compare any older detect.py template with the current SConstruct and a suitable working port before using it.

What to implement

Lifecycle. The entry point creates an OS implementation, calls Main::setup, then Main::start and the application loop, followed by Main::cleanup. Handle startup failures and the exit code. Reference: platform/linuxbsd/reckfell_linuxbsd.cpp.
System services. Review every pure virtual method in core/os/os.h, beyond initialization: time, filesystem environment, processes, entropy and other operations need implementations. For a UNIX-like target, inspect drivers/unix/os_unix.h. A headless launch does not establish display support.
Window and input. Implement DisplayServer and the keyboard, mouse, touch and controller events supported by the device. The contract is in servers/display/display_server.h.
Graphics and audio. Connect a driver supported by the device and create its context or surface. Source drivers include drivers/vulkan, drivers/d3d12, drivers/metal and drivers/gles3; a directory’s presence does not establish compatibility with your SDK. Check the audio driver separately.
Template and packaging. Supply target templates, libraries, resources and required device metadata. An empty project must start from a finished package, independently of the source tree.

Do not bring up everything at once. Establish predictable headless startup and shutdown, then window and input, followed by rendering, audio and packaging. Unsupported operations should report a meaningful result rather than pretend to succeed.

Exporter and platform APIs

The exporter runs in the host editor. SConstruct discovers it through platform/my_platform/export/export.cpp; editor/SCsub adds the C++ files from export/. Compare a working port’s export.h, export.cpp and export_plugin.*. LinuxBSD registration uses register_linuxbsd_exporter_types() and register_linuxbsd_exporter().

The existing exporter icons are platform/linuxbsd/export/logo.svg and run_icon.svg. platform/SCsub generates headers from SVG files in export/; adding platform/my_platform/logo.svg at the platform root does not connect an icon. Your exporter must supply registration, paths and use of the generated symbols.

Optional common platform APIs are discovered through platform/my_platform/api/api.cpp. The generator expects api/api.h, register_my_platform_api() and unregister_my_platform_api(). Add these files when the port actually provides such APIs, rather than creating an unused stub.

Port acceptance

Check on the target device	Required evidence
Startup and shutdown	Loading failures appear in logs, exit codes are correct, repeated launch works.
Data	Resources load, user data can be written, and saved data survives a restart.
Window and input	Size and scaling, focus, closing, input and supported device reconnection work.
Graphics and audio	An actual rendered frame and audio on the device, suspend/resume, correct drivers and materials.
Export	Both debug and release packages launch without the editor or source directory.
C#, if advertised	A managed project builds and runs on the device with its target .NET environment.

Measure memory, startup time and performance on the actual device and project. A new port has no universal memory budget or graphics-quality guarantee.

This article was checked against current source. The discovery algorithm was also exercised on isolated fixture directories. No new port, target SDK, native build or device acceptance listed above was completed here.