OpenXR Spatial Entities

OpenXR Spatial Entities is a family of OpenXR extensions for representing and querying elements of an XR user's surroundings. It provides a common framework for scene understanding, including tracked surfaces, visual markers and spatial anchors. The base extension, XR_EXT_spatial_entity, organizes information into entities and components; additional extensions define particular tracking and persistence capabilities.

Reviewed 21 October 2026. Current registry clauses, release history, snapshots, tracking and local persistence boundaries About review dates.

Purpose and history

Spatial Entities gives applications a shared API for obtaining environmental information and associating virtual content with real locations. Khronos announced the initial extension family on 10 June 2025 under the heading "released for developer feedback". The announcement also stated that the extensions had already been ratified and published. Developer feedback did not mean that the published specifications were unratified drafts.

The initial family appeared in specification release 1.1.49, dated 10 June 2025. Later releases expanded it: 1.1.63, dated 1 September 2026, added spatial image tracking; 1.1.65, dated 16 October 2026, added spatial object tracking, environmental mesh tracking, entity archetypes and an additional plane semantic-label set. These are extension publications, rather than a statement that every OpenXR runtime implements them.

Entities, components and spaces

The framework separates an entity from the information available about it. An entity can represent a physical feature, virtual content or something defined by the application. Components describe its properties or behavior. An entity has at most one component of a particular type. A capability supplies a particular kind of functionality, such as plane tracking, and specifies the components that its entities can provide.

Concept	Role
Spatial entity	An item represented in the spatial framework, such as a detected plane or an application-created anchor.
Component	A typed part of an entity's data, such as bounds, an anchor pose or a persistence identifier.
Capability	A configured source of functionality and associated component types, rather than a guarantee that every device offers the same environmental data.

An XrSpace is a frame of reference used to express coordinates. For example, a reference space establishes where an origin and axes are located, while a pose-action space can follow a controller. An entity is a representation carrying data, so it is not interchangeable with the coordinate frame used to express that data.

An XrSpatialEntityIdEXT identifies an entity within its spatial context. The same physical item discovered through another context does not therefore provide a reusable cross-context ID. Applications can also obtain XrSpatialEntityEXT handles to indicate an ongoing interest in particular entities and request updates for them.

Capability discovery and context setup

Applications enumerate the capabilities, component types and capability features supported by the selected OpenXR system. They configure the capabilities and components they intend to use when creating an XrSpatialContextEXT. The context manages the resources needed to discover and update entities. A context must enable at least one capability, with a nonempty component configuration; requesting an unsupported capability or component produces an error.

Context creation is asynchronous. The framework uses XR_EXT_future: an operation returns a future, the application polls it, and a corresponding completion function retrieves its result when ready. Acceptance of the initial request is not confirmation that the underlying operation succeeded.

A runtime may require permission to access environmental capabilities. Its tracking pipeline may also need time to start, so an early discovery request can return no entities. The specification provides a discovery-recommended event to help applications schedule requests without repeatedly gathering unchanged information.

Initial extension family

Extension	Function and boundaries
XR_EXT_spatial_entity	Establishes the context, entity, component, capability and snapshot framework. Concrete tracking capabilities are supplied by other extensions.
XR_EXT_spatial_plane_tracking	Supplies plane entities with 2D bounds and alignment information. Polygon boundaries, 2D meshes and semantic labels are optional components, so applications must check for them.
XR_EXT_spatial_marker_tracking	Defines capabilities for QR codes, Micro QR codes, ArUco markers and AprilTags. Each supported marker category is advertised separately. Tracked markers provide marker data and 2D bounds.
XR_EXT_spatial_anchor	Lets an application create an anchor at a chosen physical location. Its anchor component supplies a pose that the runtime can adjust as its environmental tracking changes.
XR_EXT_spatial_persistence	Provides persistence contexts, discovery of stored entities and UUIDs for correlating entities across sessions. Persistence scopes determine which storage an application can access.
XR_EXT_spatial_persistence_operations	Adds asynchronous operations to persist and unpersist entities. Its local-anchor scope is limited to anchors on the same device, for the same user and application.

Discovery, snapshots and tracking

Applications read environmental data through snapshots. An XrSpatialSnapshotEXT holds a coherent, immutable collection of entities and selected component data. It does not continually change as tracking improves. Applications obtain a new snapshot for newer information and release snapshots when finished with them.

A discovery snapshot gathers entities asynchronously. A supplied component filter selects entities having at least one requested component and includes data for the requested component types. An update snapshot instead takes handles for specific known entities and retrieves their latest component information; it does not discover additional entities.

The subsequent component-data query has a different rule: when several component types are requested, returned entities must have all of them. Query results include entity IDs and tracking states alongside requested data. A tracking state of PAUSED can resume; STOPPED means that the runtime will not resume tracking that entity. Applications must check the state before treating pose data as valid. The persistence component has a separate rule allowing its data to be returned regardless of tracking state.

Anchoring and persistence

An anchor gives the runtime a location to track while it refines its understanding of the physical environment. Anchors are unaffected by system recentering, but independently tracked anchors can move relative to one another as their poses are corrected. The specification therefore recommends reusing one anchor for virtual objects that must retain a fixed relationship. Creating an anchor does not itself make it persistent: its normal lifetime ends with its spatial context or the destruction of its entity handle.

Persistence uses UUIDs rather than context-local entity IDs. The system-managed scope gives applications read-only access to system-persisted entities. The local-anchor scope supports storage and retrieval for the same device, user and application. It does not establish a cross-device or cross-application anchor-sharing service.

A persisted anchor also does not contain an application's complete scene. The application must retain its own association between the anchor UUID and content to reconstruct. Godot's developer documentation illustrates this by pairing an anchor UUID with an application-managed scene path.

Application integration and limitations

Godot exposes built-in tracking logic for anchors, planes and markers, along with lower-level context and snapshot APIs. Its documentation distinguishes enabling a capability from the additional application logic needed to use its data, and notes that device-specific export permissions can be required. Bastiaan Olij's demonstration project illustrates anchored objects, plane visualization and marker tracking. Its README identifies it as a reference implementation that is not fully tested, and marks the manual discovery examples as untested.

The shared API does not impose identical sensing hardware, component availability or tracking behavior. Godot's documentation notes that plane data can come from a previous room capture or live optical detection. Applications still need to handle unavailable features, permissions and tracking changes on the selected runtime.

OpenXR Spatial Containers addresses a different task: presenting application content in spaces managed by a spatial windowing system. Spatial Entities describes and tracks environmental information; the similarly named container extensions manage application presentation. Neither name makes the two extension families interchangeable.