API reference

SpatialRuntimeDelegate Class

Modifiers: final
The Spatial runtime, as an object a host owns instead of a base class it inherits.
Everything that used to be re-typed into every host class lives here: the SpatialInterface and its Scene, the ComponentManager / SystemManager / FeatureManager trio, the EntityContext bindings, the SpatialHostCallbacks registration, the phase-locked frame loop, the scene-ready gate, audio focus and teardown ordering. A host supplies a SpatialRuntimeDelegate.Host and forwards six lifecycle calls; it does not need to be an Activity, and it does not need any particular base class.
The runtime asks nothing of the host but a Context: it never resolves a method or a field on the host object by name, and instead takes three registrations — a SpatialHostCallbacks, the Scene, and a read-back of the base path. This class is the single place that performs them. VrActivity is a thin entry point over this delegate. Apps that cannot change their base class can own a delegate directly. 
class MyActivity : ComponentActivity(), SpatialRuntimeDelegate.Host {
  private val runtime = SpatialRuntimeDelegate(this, this)
  override fun onCreate(savedInstanceState: Bundle?) {
    runtime.onHostPreCreate(savedInstanceState)  // features + native library, before super
    super.onCreate(savedInstanceState)
    runtime.onHostCreate(savedInstanceState)     // the runtime itself
  }
  override fun onStart() { super.onStart(); runtime.onHostStart() }
  override fun onResume() { super.onResume(); runtime.onHostResume() }
  override fun onPause() { super.onPause(); runtime.onHostPause() }
  override fun onStop() { super.onStop(); runtime.onHostStop() }
  override fun onDestroy() { runtime.onHostDestroy(); super.onDestroy() }
  override fun onSceneTick() { runtime.systemManager.execute() }
}
A Service host forwards the subset it has: onHostPreCreate / onHostCreate from Service.onCreate, onHostResume from onBind / onRebind, and onHostDestroy from onDestroy.
All lifecycle methods must be called on the main thread. SpatialRuntimeDelegate.Host.onSceneTick may run off the main thread when the frame loop is phase-locked; SpatialRuntimeDelegate.Host.onSceneReady never does.

Constructors

SpatialRuntimeDelegate ( context , host , sceneReadyPolicy )
Signature 
constructor(context: Context, host: SpatialRuntimeDelegate.Host, sceneReadyPolicy: SpatialRuntimeDelegate.SceneReadyPolicy = SceneReadyPolicy.WHEN_GRAPHICS_READY)
Parameters
context: Context  The Context handed to native — normally the host itself. Any Context satisfies the runtime, except on the immersive backends (GraphicsHSR, GraphicsHE), which forward it to OpenXR as XrInstanceCreateInfoAndroidKHR.applicationActivity and therefore need a real Activity.
host: SpatialRuntimeDelegate.Host  The object being made into a Spatial host.
sceneReadyPolicy: SpatialRuntimeDelegate.SceneReadyPolicy  When SpatialRuntimeDelegate.Host.onSceneReady fires. Defaults to SpatialRuntimeDelegate.SceneReadyPolicy.WHEN_GRAPHICS_READY, which is what an immersive Activity wants.
Returns
SpatialRuntimeDelegate

Properties

componentManager : ComponentManager
[Get]
The singleton component manager.
Signature 
val componentManager: ComponentManager
context : Context
[Get]
The Context handed to native — normally the host itself. Any Context satisfies the runtime, except on the immersive backends (GraphicsHSR, GraphicsHE), which forward it to OpenXR as XrInstanceCreateInfoAndroidKHR.applicationActivity and therefore need a real Activity.
Signature 
val context: Context
dataModel : DataModel
[Get]
The singleton data model.
Signature 
val dataModel: DataModel
featureManager : FeatureManager
[Get]
The registered features. Empty until SpatialRuntimeDelegate.onHostPreCreate; a temporary empty manager stands in before that so pre-runtime code has something to talk to.
Signature 
var featureManager: FeatureManager
isShutDown : Boolean
[Get]
True once the frame loop has stopped and native resources have been released.
Signature 
var isShutDown: Boolean
lastSessionState : SessionState
[Get]
The most recent OpenXR session state, or SessionState.UNKNOWN before the first change.
Signature 
var lastSessionState: SessionState
scene : Scene
[Get]
The singleton scene.
Signature 
val scene: Scene
spatial : SpatialInterface
[Get]
The native interface.
Signature 
val spatial: SpatialInterface
spatialContext : SpatialContext
[Get]
The context/interface pair panels and features are created against.
Signature 
val spatialContext: SpatialContext
systemManager : SystemManager
[Get]
The singleton system manager.
Signature 
val systemManager: SystemManager

Methods

doFrame ( frameTimeNanos )
The fallback-mode Choreographer tick. Hosts that implement Choreographer.FrameCallback forward their doFrame here; hosts that do not never see it.
Signature 
open fun doFrame(frameTimeNanos: Long)
Parameters
frameTimeNanos: Long  The frame time supplied by the Choreographer.
findFeature ( clazz )
Returns the registered feature of type clazz, throwing if it is not registered.
Signature 
fun <T : SpatialFeature> findFeature(clazz: KClass<T>): T
Parameters
clazz: KClass  The feature type.
Returns
SpatialRuntimeDelegate
onHostCreate ( savedInstanceState )
Second half of host creation. Call aftersuper.onCreate(). Creates the runtime, binds EntityContext, registers this host with native and runs the features' create hook.
Signature 
fun onHostCreate(savedInstanceState: Bundle?)
Parameters
savedInstanceState: Bundle?  The host's saved state, or null.
Throws
VrActivityDuplicateException  If the host is an Activity and another live Spatial Activity already exists in this process.
onHostDestroy ()
Call from the host's onDestroy, beforesuper.onDestroy().
Signature 
fun onHostDestroy()
onHostPause ()
Call from the host's onPause. Drops audio focus per SpatialRuntimeDelegate.Host.audioPauseMode, and shuts the runtime down if the host is an Activity that is finishing.
Signature 
fun onHostPause()
onHostPreCreate ( savedInstanceState )
First half of host creation. Call beforesuper.onCreate(): it installs the build-time component id map, builds the FeatureManager, loads the native library and runs the features' pre-runtime hook, all of which must happen before the platform's own creation work.
Signature 
fun onHostPreCreate(savedInstanceState: Bundle?)
Parameters
savedInstanceState: Bundle?  The host's saved state, or null.
onHostResume ()
Call from the host's onResume (or, for a Service, from onBind / onRebind). Takes audio focus per SpatialRuntimeDelegate.Host.audioPauseMode and starts the frame loop.
Signature 
fun onHostResume()
onHostStart ()
Call from the host's onStart.
Signature 
fun onHostStart()
onHostStop ()
Call from the host's onStop. Shuts down if the host is an Activity that is finishing.
Signature 
fun onHostStop()
runOnMainThread ( runnable )
Runs runnable on the main thread, immediately if already on it.
Signature 
fun runOnMainThread(runnable: Runnable)
Parameters
runnable: Runnable  The work to run.
shutdown ()
Stops the frame loop, unbinds EntityContext and releases every Kotlin then native resource, once. Called for you from SpatialRuntimeDelegate.onHostPause / SpatialRuntimeDelegate.onHostStop / SpatialRuntimeDelegate.onHostDestroy; call it directly only for a host with no Android lifecycle to hang it on.
Signature 
fun shutdown()
tryFindFeature ( clazz )
Returns the registered feature of type clazz, or null.
Signature 
fun <T : SpatialFeature> tryFindFeature(clazz: KClass<T>): T?
Parameters
clazz: KClass  The feature type.
Returns
SpatialRuntimeDelegate?

Inner Interface

Host Interface

Extends LibraryLoader
The hooks a SpatialRuntimeDelegate calls back into.
Every member has a default, so a host declares exactly the ones it uses. The configuration members are read once, during SpatialRuntimeDelegate.onHostPreCreate / SpatialRuntimeDelegate.onHostCreate.

Signature

interface Host : LibraryLoader

Methods

audioPauseMode ()
When audio focus is dropped and regained. The delegate applies it — a host cannot, because Scene.setAudioFocused is deliberately not public.
Signature 
open fun audioPauseMode(): AudioPauseMode
Returns
AudioPauseMode
loadLibrary ( name )
Loads the native library. Override only if the host does not use System.loadLibrary. Also the LibraryLoader every registered SpatialFeature is attached to.
Signature 
open override fun loadLibrary(name: String)
Parameters
name: String  Library name without prefix or extension.
onHMDMounted ()
The headset was put on.
Signature 
open fun onHMDMounted()
onHMDUnmounted ()
The headset was taken off.
Signature 
open fun onHMDUnmounted()
onRecenter ( isUserInitiated )
The user recentered.
Signature 
open fun onRecenter(isUserInitiated: Boolean)
Parameters
isUserInitiated: Boolean  True when the user asked for it rather than the system.
onSceneReady ()
The scene may now be built. Fires once, on the main thread, per SpatialRuntimeDelegate.sceneReadyPolicy.
Implementations are expected to call featureManager.onSceneReady() — the delegate routes through the host rather than dispatching to features itself, so that a host's own overridable hook stays the single ordering point.
Signature 
open fun onSceneReady()
onSceneTick ()
Per-frame application work. Typically systemManager.execute(). May run off the main thread when the loop is phase-locked.
Signature 
open fun onSceneTick()
onSessionStateChanged ( state )
The OpenXR session state changed.
Signature 
open fun onSessionStateChanged(state: SessionState)
Parameters
state: SessionState  The new state. The previous one is SpatialRuntimeDelegate.lastSessionState until this call returns.
onSpatialShutdown ()
The runtime is being torn down, before any native resource is released.
Signature 
open fun onSpatialShutdown()
onVRPause ()
The immersive session became inactive.
Signature 
open fun onVRPause()
onVRReady ()
The immersive session became active.
Signature 
open fun onVRReady()
registerFeatures ()
App-level features.
Signature 
open fun registerFeatures(): List<SpatialFeature>
Returns
List
registerRequiredOpenXRExtensions ()
OpenXR extensions this host requires at startup. The extensions declared by registered features are added to these.
Signature 
open fun registerRequiredOpenXRExtensions(): List<String>
Returns
List
registerSystemFeatures ()
SDK-level features, registered before SpatialRuntimeDelegate.Host.registerFeatures. This is where a toolkit host returns its ToolkitFeature.
Signature 
open fun registerSystemFeatures(): List<SpatialFeature>
Returns
List
renderConfiguration ()
Render-resolution scaling.
Signature 
open fun renderConfiguration(): RenderConfiguration
Returns
RenderConfiguration
setBaseHref ( baseHref )
The native base path became known. The delegate already stores it for EntityContext.getBaseHref; this hook exists only for hosts that publish it further.
Signature 
open fun setBaseHref(baseHref: String)
Parameters
baseHref: String  The runtime's base path.
useVolumes ()
Whether the runtime is initialized with apertures (volumes) enabled.
Signature 
open fun useVolumes(): Boolean
Returns
Boolean

Inner Enum

SceneReadyPolicy Enum

When a SpatialRuntimeDelegate fires SpatialRuntimeDelegate.Host.onSceneReady.

Signature

enum SceneReadyPolicy : Enum<SpatialRuntimeDelegate.SceneReadyPolicy>

Enumeration Constants

MemberDescription
WHEN_GRAPHICS_READY
On the first frame after SpatialInterface.isGraphicsReady(), hopped to the main thread if the frame loop is ticking off it. Ticks and commits are withheld until then, so scene setup can safely touch graphics. The right choice for a host that renders.
ON_FIRST_RESUME
Synchronously on the first SpatialRuntimeDelegate.onHostResume, before the frame loop starts. For hosts whose "ready" is a binding rather than a display — VrService and ArActivity both bind to a runtime that another component has already brought up.
Nav Logo
English (US)
© 2026 Meta