Colocation Discovery sample overview

Updated: May 7, 2026

Overview

This sample demonstrates proximity-based multiplayer using two complementary OculusXR APIs: the Colocation Discovery API for session discovery and the Group Anchor Sharing API for sharing spatial anchors with group identifiers. Developers learn how to discover nearby headsets, establish a local network session, and share spatial anchors using group UUIDs rather than individual user IDs.

View the sample source code on GitHub⁠.

Learning objectives

Complete this guide to learn how to:

advertise and discover colocation sessions using the OculusXR Colocation Discovery API

embed custom network data (host IP address) as session metadata for local multiplayer

share spatial anchors with groups using UUID-based group sharing

persist session state across level transitions using a custom Game Instance

build a lobby-to-session flow for proximity-based multiplayer

Requirements

Meta Quest 2, Quest 3, or Quest 3S headset

Unreal Engine 5.4 or later with the OculusXR/MetaXR plugin

This sample requires no platform prerequisites such as Data Use Checkup, app registration, or test users.

For build setup and configuration, see the sample README⁠.

Get started

Clone or download the sample from the GitHub repository. Open the project in Unreal Engine 5.4, then build and deploy to your Meta Quest device. The sample opens to the SA_Lobby level where you can create or join a colocation session. Use two Quest devices on the same WiFi network to test the full session discovery and anchor sharing flow.

Explore the sample

File / Scene	What it demonstrates	Key concepts
SA_Lobby (map)	Session creation and discovery UI	Lobby pattern, passthrough environment
SA_Showcase (map)	Colocated shared experience	Anchor creation, group sharing, networked cubes
BP_SessionManager	Colocation session advertising and discovery	Session metadata as network address
BP_SpatialAnchorManagerComponent	Group anchor sharing and retrieval	UUID-based group sharing API
BP_ColocationSessionGameInstance	Cross-map state persistence	Custom Game Instance pattern
UColocationDiscoverySampleBPLibrary	C++ utility functions	IP retrieval, metadata encoding, session joining

Runtime behavior

The sample opens to a passthrough lobby (SA_Lobby) with two options: Create Session and Join Session.

When the host creates a session, the app advertises a colocation session with the device’s local IP encoded in the session metadata, then transitions to the SA_Showcase map as a listen server. When a client joins, the app discovers nearby sessions, decodes the host IP from the discovered session’s metadata, and connects via Unreal’s client travel over local WiFi.

In SA_Showcase, both users share the same passthrough environment. They can create, save, and share spatial anchors using group UUIDs. Shared anchors appear for all colocated users.

Key concepts

Session metadata as network address

The sample embeds the host’s local IP address as the colocation session’s metadata. BP_SessionManager retrieves the local IP and passes it to the OculusXRAsyncStartColocationSessionAdvertisement async action. When a client discovers the session, the app extracts the IP from the session metadata and initiates client travel.

The sample uses the Group Anchor Sharing API to share anchors with a group identified by the colocation session UUID. This replaces the older user-based anchor sharing approach that required Oculus user IDs. BP_SpatialAnchorManagerComponent calls OculusXRShareAnchorsWithGroupsAsync with the session UUID as the group identifier, and other clients retrieve anchors using OculusXRGetSharedAnchorsFromGroupAsync.

Game Instance for cross-map state

BP_ColocationSessionGameInstance persists the colocation session UUID across level transitions from SA_Lobby to SA_Showcase. Unreal’s Game Instance survives map changes, making it ideal for storing session-scoped data.