Building visionOS templates

This guide builds native visionOS export templates for Reckfell Engine 1.0.0. It does not build a desktop editor or export a game. To package a project, use Exporting for visionOS.

Requirements

Run commands from the engine's Source directory containing SConstruct. Use Python 3.9 or newer and SCons 4.4 or newer. On macOS, select a full Xcode installation with the visionOS SDK and its Swift toolchain; Command Line Tools alone are insufficient.

Current sources target xros26.0 for devices and xros26.0-simulator for the simulator. The Swift builder uses language mode 6 and C++ interoperability. Use tools supporting these targets, rather than copying the iOS SDK or deployment target. Apple's visionOS 26 release notes describe that SDK; check the requirements of your selected Xcode version separately.

Check the selected tools before starting a build:

xcode-select -p
xcrun --sdk xros --show-sdk-path
xcrun --sdk xrsimulator --show-sdk-path
xcrun swiftc --version

The first command should identify the intended Xcode developer directory; the next two should return existing SDK directories. These checks locate tools, not prove a successful build.

Device templates

Build both configurations for an arm64 device:

scons platform=visionos target=template_debug arch=arm64 simulator=no
scons platform=visionos target=template_release arch=arm64 simulator=no generate_bundle=yes

The native build combines engine objects into static libraries under Source/bin, with names beginning libreckfell.visionos.template_debug or libreckfell.visionos.template_release. This is not an executable editor or a signed application.

The second command also packages existing libraries using misc/dist/apple_embedded_xcode. With default suffixes, the ZIP is bin/reckfell_visionos.zip. Its framework folders distinguish xros-arm64 from xros-arm64-simulator. Packaging copies the available configurations; it does not build missing ones or prove that every required slice exists. Inspect the framework libraries before importing the archive into your export workflow.

The packager recreates and then removes bin/visionos_xcode. Keep personal files outside that temporary directory. Signing, provisioning and application export are separate steps.

Simulator limitations

The source exposes simulator=yes, selects the xrsimulator SDK and adds .simulator to library filenames. This does not establish a working simulator renderer: the current configuration disables Metal for the simulator and disables Vulkan and OpenGL on visionOS. Switching to Compatibility is therefore not an available workaround in this configuration.

Use the arm64 device as the target for graphics validation. Simulator compilation, launch and rendering have not been accepted by this guide. Although the architecture validator also lists x86_64, that list alone is insufficient to establish a supported simulator or device combination; the device recipe above deliberately uses arm64.

Custom toolchain and C#

APPLE_TOOLCHAIN_PATH selects the toolchain root, APPLE_SDK_PATH the SDK directory, and SWIFT_COMPILER an explicit swiftc executable. apple_target_triple is a compiler executable name prefix, not a replacement for the Swift deployment target: tools are looked up as $APPLE_TOOLCHAIN_PATH/usr/bin/${apple_target_triple}clang and corresponding clang++, ar and ranlib names.

The presence of OSXCROSS_VISIONOS enables the cross-build branch even if its value is empty. That branch requires an explicit SWIFT_COMPILER; it has no automatic Swift compiler fallback. Enabling the branch does not install tools or prove a complete Linux/Windows build workflow.

The native recipes above do not enable C#. module_mono_enabled=yes opts into the module; it does not by itself produce or validate managed assemblies, AOT compilation or a working C# export on visionOS.

Diagnose the failing stage

This guide is source-reviewed, including isolated configuration checks with simulated build environments. No visionOS compiler, template build, signing, device/simulator launch or graphics test was run for this review.