OpenXR project settings

OpenXR project settings

Project settings describe what the engine requests from OpenXR. They neither install an XR runtime, connect a headset nor establish extension support. The keys and defaults below apply to current Reckfell 1.0.0; enable only the features you need.

Minimal startup

1. Find xr/openxr/enabled in Project Settings and enable it. For the first run, retain Head Mounted, Stereo, Stage and Opaque.
2. Prepare the action map at xr/openxr/default_action_map. The current default is asset://openxr_action_map.rdata; follow the action-map guide.
3. Configure the XR rig and startup handling: an XRCamera3D alone does not enable XR output. Check initialization success and separately enable XR on the intended Viewport.
4. Restart the application after changing startup settings. Inspect logs, the active XR runtime and actual interface capabilities; a saved checkbox is not evidence of success.

--xr-mode on forces an XR startup request; --xr-mode off disables it for a diagnostic run. Normally the editor does not start an OpenXR session merely because enabled=true. Running the game and starting the editor are different processes and stages.

For Vulkan, request OpenXR at startup: graphics-integration extensions are needed before device preparation. Do not expect a late Initialize call to repair missing startup configuration. Editing ProjectSettings during gameplay also does not automatically recreate existing instances, sessions or swapchains.

Core settings

Do not leave the action map to an accidental fallback. If the resource fails to load, the interface creates default actions; a tools-enabled build also tries to save the resource. This does not establish that your custom actions and bindings exist. Save and inspect your own .rdata before export.

Stereo with Foveated Inset already has an implementation in current source. It is a separate view configuration with an additional inset, not a promise of support on every headset. Start an ordinary project with Stereo; do not confuse inset views with shading-density settings.

Choose a tracking space

This is a requested mode, not an unconditional guarantee. Current code can emulate unavailable Local Floor through Local and Stage; for other unsupported requests it chooses Local. Inspect logs and the actual mode before relying on floor or recenter behavior.

OpenXRInterface.PoseRecentered reports a reference-space update after tracking has been updated. The startup guide handler only forwards the event; it does not call CenterOnHmd for you. Choose reset policy together with room-scale handling and locomotion. An unconditional additional CenterOnHmd can offset an already corrected camera again. A Stage boundary neither replaces collisions nor stops a person's physical movement.

Environment blending

Opaque displays the virtual image. Additive adds virtual light to the environment; black does not necessarily obscure the real world. Alpha uses output transparency, so check the intended Viewport.TransparentBg and scene material/background.

If the selected blend mode is unavailable, code can switch to the first supported one. Alpha can also be provided through a specialized passthrough implementation. A black view is not evidence of a broken material: check the actual blend mode, passthrough availability, permissions and target-device integration first. Selecting Alpha does not install a vendor plugin.

Foveation and quality

Eye-tracked foveation and eye-gaze interaction are separate features. A true value establishes neither a sensor, permission nor an active extension. For RD, inspect Viewport VRS; a VRS map alone is also not a measurement of actual savings.

If a log says incompatible rendering features disabled subsampled images, that refers to this image path. Do not automatically extend that conclusion to every form of foveation. Compare the same frame and GPU time on the target device; do not change resolution, MSAA, effects and foveation level simultaneously.

Extensions and input

All switches in the following table default to false, except numeric values explicitly identified elsewhere.

A gaze pose needs a Pose action in the map: profile /interaction_profiles/ext/eye_gaze_interaction, input path /user/eyes_ext/input/gaze_ext/pose. Set XRController3D.Tracker to /user/eyes_ext and Pose to your action name. Enabling the extension alone is insufficient. This naming and route are source-reviewed, not a test of eye accuracy or device permissions.

Spatial environment

These keys request real-environment capabilities, not ordinary gameplay Entities. Enabling them creates no detected surfaces or saved anchors automatically. Check device support, user consent and data lifetime.

This is a startup-request reference, not a ready-made spatial-recognition system. The existence of these keys does not establish anchor, plane-tracking or marker-detection availability.

Startup diagnosis

Verification scope

An isolated installed Reckfell 1.0.0 project with --headless --xr-mode off checked registration and defaults for 39 scalar settings, vector bounds and the presence of a borrowed uninitialized interface. All 81 observations succeeded; no project settings were written and Initialize was not called.

Startup order, enum mapping, space/blend fallbacks, extension gating and the stated limitations were reviewed against current source. This is not real-headset, loader/runtime, permission, recenter, passthrough, foveation, frame-synthesis, tracking, export or editor-UI acceptance. Engine build and SDK were unchanged.