API reference

SpatialIdRegistry Object

Global lookup of stable component and attribute IDs assigned at APK build time.
Spatial SDK components and their attributes are identified at runtime by Int IDs. Historically these came from Android resource IDs (R.id.*) populated by AAPT2 at the consuming APK's link time — which made the integers unstable across builds and consumers, breaking compiled-AAR distribution.
The new pipeline assigns deterministic IDs from 1 by post-processing the APK's component XMLs (extracted from each AAR's components directory). The result is packaged into the APK as a name → ID map asset; at process startup the bootstrap reads that asset and calls SpatialIdRegistry.install. Generated component companions then read their IDs eagerly at companion class init via SpatialIdRegistry.component and SpatialIdRegistry.attribute.
After class init the IDs are plain Int fields on the companion — accesses are single field reads, with no per-access lazy delegate, no synchronization, and no allocation.
Bootstrap order: SpatialIdsBootstrap.installIfPresent runs from VrActivity.onCreate and reads the build-time map from assets/spatial_ids.json. If the asset is present, that's the happy path: every lookup returns its build-time-assigned integer.
Transition fallback: if the asset is missing (e.g. an app that hasn't yet adopted the AssignSpatialIdsTask Gradle task), the registry falls back to handing out IDs from a monotonic counter on first lookup and logs a one-time warning naming the missing component. The app keeps working, but IDs are unstable across runs/builds and across other apps that load components in a different order. Adopt the assigner to fix.

Signature

object SpatialIdRegistry

Methods

attribute ( className , propName )
Looks up the ID for an attribute. Called from generated companion <clinit>. See SpatialIdRegistry.component for the lookup-vs-fallback semantics.
Signature 
fun attribute(className: String, propName: String): Int
Parameters
className: String  the owning component's simple class name.
propName: String  the attribute's name as declared in its XML schema.
Returns
Int
attribute ( className , propName , sharedId )
SpatialIdRegistry.attribute, for an attribute whose schema declares a non-integer customId.
Attributes declaring the same key are deliberately one attribute — Mesh.hittable, Panel.hittable and Hittable.hittable all share R.id.mesh_hittable. A complete installed map already encodes that (it assigns every such name the same integer), so the key steers the fallback, which would otherwise hand each name its own counter value and quietly split them apart. A map covering only some of the names cannot be repaired from here and is reported — see warnPartialShareOnce.
Spelled as a separate overload rather than a default argument: see SpatialIdRegistry.component.
Signature 
fun attribute(className: String, propName: String, sharedId: String?): Int
Parameters
className: String
propName: String
sharedId: String?
Returns
Int
component ( name )
Looks up the ID for a component class. Called from generated companion <clinit>.
Returns the build-time-assigned integer if SpatialIdRegistry.install has been called and the name is present. Otherwise, falls back to a monotonic counter (see class KDoc).
Signature 
fun component(name: String): Int
Parameters
name: String  the component's simple class name as declared in its XML schema.
Returns
Int
component ( name , sharedId )
SpatialIdRegistry.component, for a class whose schema declares a non-integer customId. See SpatialIdRegistry.attribute for what the key does.
Spelled as a separate overload rather than a default argument: the arity-1 form is bound by name from JNI, and a @JvmOverloads bridge has no Kotlin callers for R8 to see.
Signature 
fun component(name: String, sharedId: String?): Int
Parameters
name: String
sharedId: String?
Returns
Int
install ( componentMap , attributeMap )
Installs the build-time name → ID maps. Called once during process bootstrap before any component companion is touched. Re-installation replaces the previous maps; this supports tests that need to swap fixtures between cases.
Signature 
fun install(componentMap: Map<String, Int>, attributeMap: Map<String, Int>)
Parameters
componentMap: Map<String, Int>  simple component name (e.g. "Named") → assigned ID.
attributeMap: Map<String, Int> "ComponentName.attributeName" → assigned ID.
reset ()
Test-only: clears the installed maps and the fallback state so a subsequent SpatialIdRegistry.install starts from a clean slate.
Signature 
fun reset()
Meta
English (US)
© 2026 Meta