Skip to Content
Quick StartUnity PackageNavigation

Navigation

After the device localizes, the SDK can guide the player to a point of interest (POI) along the section’s navigation graph. Routes can cross sections, for example by taking a lift to another floor. The SDK computes the route and guidance. You decide how to present it: use the optional NavigationRenderer for AR arrows, or draw your own UI from sdk.state.navigation.

Navigation data comes from your map in Graffity Console. There is no built-in destination picker, so your game chooses the destination.

Start a route

Step 1 - Wait for localization

sdk.availableDestinations lists the POIs of the localized section, as PickedDestination objects with poiId, displayName, category, sectionId, placeId and position. The list is filled after the first localization.

Step 2 - Start navigation

Pass a destination from the list, or its poiId:

var sdk = session.sdk;
var destination = sdk.availableDestinations.First(d => d.displayName == "Food Court");
await sdk.startNavigation(destination);       // or: await sdk.startNavigation(destination.poiId);

The returned Task completes when the route is accepted, not when the player arrives. It faults with a GraffityARCloudError when no route is available, for example navigationGraphUnavailable or navigationRouteUnavailable.

Step 3 - Follow the guidance

While a route is active, sdk.state.navigation is a GraffityARNavigationState:

PropertyDescription
destinationId, destinationNameThe final destination, even while the current leg heads to a lift or stairs
actionThe next maneuver: forward, turnLeft, turnRight, goUp, goDown or arriving
distanceToDestinationMetersRemaining route distance
distanceToNextActionMetersDistance to the next maneuver, or null

Observe it with statePublisher or the delegate’s didChangeState, like any other state. If the player leaves the route by more than 3 m, the SDK recomputes it.

Step 4 - Arrive or stop

Within 3 m of the destination, the SDK calls didArriveAt on the delegate once and ends the route. Call sdk.stopNavigation() to cancel; the delegate receives graffityARCloudDidStopNavigation. Starting a new destination replaces the current route.

Multi-section journeys

When the destination is in another section of the same place, the route leads to a transition point, such as a lift, an escalator or stairs. When the player reaches it:

  1. Localization pauses and sdk.pendingTransition becomes non-null. It is an AwaitingSectionTransition with:
    • nextSectionName: the section to go to, for example “Floor 3”.
    • goingUp: true, false or null if unknown.
    • hop: the transition details, including type, fromPoiName and toPoiName.
  2. Show your own prompt, for example “Take the lift to Floor 3, then tap Continue”.
  3. After the player has changed floors, call sdk.continueAfterTransition(). The SDK localizes again in the new section and continues to the final destination.
var transition = session.sdk.pendingTransition;
if (transition != null)
{
    prompt.text = $"Go {(transition.goingUp == true ? "up" : "down")} to {transition.nextSectionName}";
    continueButton.onClick.AddListener(() => session.sdk.continueAfterTransition());
}

If the player ends up in a different section than expected, the SDK plans the rest of the route from the section it actually detects. Before starting a new destination during a transition, call continueAfterTransition() or stopNavigation().

ℹ️

Routes work across sections within one place. Routes between different places aren’t supported and fail with navigationRouteUnavailable.

AR arrows with NavigationRenderer

NavigationRenderer is an optional component that draws route arrows and a destination marker from your own prefabs.

  1. Import the Navigation visuals sample from the Package Manager and choose Graffity > AR Cloud > Samples > Create navigation visuals. This creates URP arrow, marker and renderer prefabs in your Assets folder.
  2. Add the renderer prefab to your scene, outside any map root.
  3. Assign it to the session’s Navigation Renderer field. The session attaches it to the XR Origin’s tracking space when it initializes.
FieldDescription
Navigation Arrow PrefabPath arrow. Local +Z points forward and +Y points up.
Destination Icon PrefabMarker shown at the destination
Destination Go Up / Go Down PrefabOptional markers at transition points
MaterialOptional material override for the instances
Navigation Arrow CountNumber of arrows ahead of the player (1–32, default 3)
Enable Fixed Nav ArrowShow a fixed guide arrow in front of the camera
View CameraCamera used to hide arrows outside the view. Defaults to the XR Origin camera.

The renderer owns the objects it instantiates and destroys them when it is released. Your prefabs and materials aren’t modified. Leave the field empty to draw navigation entirely yourself.

Sample

The Host integration sample includes ScriptedNavigation, which drives navigation from scripts, and NavigationUIController, an example destination list and Continue button in English and Thai. Use Graffity > Samples > Create scripted navigation integration scene to create a scene with both. The UI is optional; delete it and call the same API from your own UI.

Session APIiOS SDK