Reference space management

overview reference space management provides a framework for defining and coordinating different coordinate systems within the virtual environment this system is particularly important for xr (virtual/augmented reality) applications, where multiple spatial reference frames must be synchronized the virtual world's coordinate system, the user's physical space, and the viewer's perspective by managing these different "spaces," the engine can correctly translate between physical movements and virtual positioning referencespacestate the core of the reference space management system is the referencespacestate , a global state object that tracks the key reference entities // simplified from src/referencespacestate ts import { undefinedentity } from '@ir engine/ecs'; import { definestate } from '@ir engine/hyperflux'; export const referencespacestate = definestate({ name 'referencespacestate', initial { // entity for the xr session's local floor localfloorentity undefinedentity, // entity for the absolute origin (0,0,0) of the world originentity undefinedentity, // entity representing the viewer/camera viewerentity undefinedentity } }); this state object provides a centralized registry for accessing the three fundamental reference entities origin entity represents the absolute (0,0,0) point of the virtual world local floor entity represents the user's physical floor and play area in xr viewer entity represents the user's head position and orientation (camera viewpoint) initialization process the reference space entities are created during engine initialization initializespatialengine this function sets up the origin and local floor entities // simplified from src/initializeengine ts import { createentity, setcomponent } from '@ir engine/ecs'; import { namecomponent } from ' /common/namecomponent'; import { transformcomponent } from ' /transform/components/transformcomponent'; import { referencespacestate } from ' /referencespacestate'; import { getmutablestate } from '@ir engine/hyperflux'; export const initializespatialengine = () => { // create the origin entity at the world's (0,0,0) const originentity = createentity(); setcomponent(originentity, namecomponent, 'origin'); setcomponent(originentity, transformcomponent); // create the local floor entity (initially at 0,0,0) const localfloorentity = createentity(); setcomponent(localfloorentity, namecomponent, 'local floor'); setcomponent(localfloorentity, transformcomponent); // register these entities in the global state getmutablestate(referencespacestate) merge({ originentity, localfloorentity }); }; initializespatialviewer this function creates the viewer entity, which serves as the camera viewpoint // simplified from src/initializeengine ts import { cameracomponent } from ' /camera/components/cameracomponent'; export const initializespatialviewer = () => { // create the viewer entity const viewerentity = createentity(); setcomponent(viewerentity, namecomponent, 'viewer'); setcomponent(viewerentity, transformcomponent); setcomponent(viewerentity, cameracomponent); // register the viewer entity in the global state getmutablestate(referencespacestate) merge({ viewerentity }); }; spatial relationships the reference entities establish a hierarchical relationship that defines how coordinates are transformed between different spaces originentity (world origin) │ ├── localfloorentity (user's physical space) │ │ │ └── viewerentity (user's head/camera) │ └── \[other world objects] this hierarchy enables several important capabilities world positioning game objects are positioned relative to the origin entity xr anchoring the local floor entity defines where the user's physical space is located within the virtual world camera perspective the viewer entity's transform determines the rendering viewpoint xr integration the reference space system is particularly important for xr applications, where it bridges the physical and virtual worlds xr session initialization when an xr session begins, the system obtains reference spaces from the xr hardware // simplified concept from src/xr/xrsessionfunctions ts async function initializexrreferencespaces(xrsession) { // request the 'local floor' reference space from the xr system const localfloorspace = await xrsession requestreferencespace('local floor'); // store this xr reference space referencespace localfloor = localfloorspace; // update the engine's localfloorentity to match this physical space computeandupdateworldorigin(); } viewer tracking during xr usage, the system continuously updates the viewer entity based on head tracking // simplified from src/xr/xrcamerasystem ts function updatecamerabasedonxr() { // get the reference entities const viewerentity = getstate(referencespacestate) viewerentity; const localfloorentity = getstate(referencespacestate) localfloorentity; // get their transform components const cameratransform = getcomponent(viewerentity, transformcomponent); const floortransform = getcomponent(localfloorentity, transformcomponent); // get the latest xr pose data from the headset const xrpose = getxrposedata(); // update the camera transform with the xr pose data cameratransform position copy(xrpose position); cameratransform rotation copy(xrpose orientation); // calculate the final world position by combining with the local floor transform cameratransform matrixworld compose(cameratransform position, cameratransform rotation, cameratransform scale) premultiply(floortransform matrixworld) decompose(cameratransform position, cameratransform rotation, cameratransform scale); } practical applications the reference space system enables several important capabilities room scale vr for room scale vr experiences, the system allows users to physically move within their play area the local floor entity is positioned at a specific location in the virtual world as the user physically moves, the xr system updates the viewer entity's position relative to the local floor this movement is reflected in the virtual world, allowing natural navigation world repositioning the system allows the virtual world to be repositioned around the user // reposition the player's physical space within the virtual world function teleportplayer(newworldposition) { const localfloorentity = getstate(referencespacestate) localfloorentity; const floortransform = getcomponent(localfloorentity, transformcomponent); // update the local floor's position in the world floortransform position copy(newworldposition); // mark the transform as dirty to trigger updates transformcomponent dirty\[localfloorentity] = 1; } multi user experiences for multi user xr applications, each user has their own local floor and viewer entities // create reference spaces for a new user function setupuserreferencespaces(userid) { // create local floor entity for this user const userlocalfloorentity = createentity(); setcomponent(userlocalfloorentity, transformcomponent); // create viewer entity for this user const userviewerentity = createentity(); setcomponent(userviewerentity, transformcomponent); setcomponent(userviewerentity, cameracomponent); // store these entities in user specific state userreferencespaces set(userid, { localfloorentity userlocalfloorentity, viewerentity userviewerentity }); } reference space workflow the following sequence diagram illustrates how reference spaces are used during an xr session sequencediagram participant user as user (physical movement) participant xrhardware as xr headset participant xrsystem as engine's xr system participant refspacestate as referencespacestate participant viewertf as viewerentity's transformcomponent participant rendersys as rendering system user >>xrhardware moves head xrhardware >>xrsystem provides new head pose data xrsystem >>refspacestate get viewerentity and localfloorentity refspacestate >>xrsystem entity ids xrsystem >>viewertf update position/rotation with new pose note right of xrsystem transform relative to localfloorentity note over rendersys render frame rendersys >>refspacestate get viewerentity refspacestate >>rendersys viewerentity id rendersys >>viewertf get final world matrix rendersys >>rendersys render scene from this viewpoint next steps with an understanding of how different coordinate systems are managed, the next chapter explores the specific implementation of xr features in the engine next xr (extended reality) integration docid\ r8 zl2geuvevqapp8x0x