Using WayspotAnchorController

WayspotAnchorController provides a low-level interface for working with Wayspot Anchors. When using WayspotAnchorController, you are responsible for maintaining a cache of created or restored anchors if needed, and handling all VPS events for anchors.

For an example of using WayspotAnchorController, see the implementation of WayspotAnchorService in the ARDK source code in Assets/ARDK/AR/WayspotAnchors/WayspotAnchorService.cs.

If you don’t need to customize how anchors are cached or don’t want to handle anchor events, use the WayspotAnchorService interface instead of WayspotAnchorController. See Using WayspotAnchorService for more details on working with WayspotAnchorService.

Creating a Wayspot Anchor

Use the following steps to create a Wayspot Anchor.

Subscribe to the WayspotAnchorController.WayspotAnchorsCreated event. See Subscribing to ARDK Events for more details on ARDK events.
Set an event handler for WayspotAnchorController.WayspotAnchorsCreated wherever you create your WayspotAnchorController instance. The following example sets the HandleWayspotAnchorsCreated handler (described later).
WayspotAnchorController _wayspotAnchorController; _wayspotAnchorController.WayspotAnchorsCreated += HandleWayspotAnchorsCreated;

Create a new anchor at a specific position in your local coordinate space.

Call WayspotAnchorController.CreateWayspotAnchors() with a list of one or more anchor positions and orientations in your local coordinate space. The current localization state must be LocalizationState.Localized before you create any anchors. The call will make a request to the VPS backend and return an array of IDs of the anchors that VPS will create.

using Niantic.ARDK.AR.WayspotAnchors;

private void PlaceWayspotAnchors(params Matrix4x4[] localPoses)
{
    // ...Verified we've localized with a VPS-activated Wayspot, the most recent WayspotController.LocalizationStateUpdated event should indicate LocalizationState.Localized...

    var ids = _wayspotAnchorController.CreateWayspotAnchors(localPoses);

    // ...optionally cache IDs if you need to track successful or failed creations...
}

Handle the created anchor in your WayspotAnchorsCreated event handler

WayspotAnchorController will send a WayspotAnchorsCreated event once anchors are created by VPS. The event data will include an IWayspotAnchor for each anchor that contains information on whether the anchor was successfully created, and additional anchor data.

The following example handler caches the IWayspotAnchor and ID if the anchor was succesfully created. It also calls WayspotAnchorController.ResumeTracking() to have VPS start tracking the created anchors.

using Niantic.ARDK.AR.WayspotAnchors;

private Dictionary<Guid, IWayspotAnchor> _wayspotAnchors;

private void HandleWayspotAnchorsCreated(WayspotAnchorsCreatedArgs wayspotAnchorsCreatedArgs)
{
    var wayspotAnchors = wayspotAnchorsCreatedArgs.WayspotAnchors;
    foreach (var wayspotAnchor in wayspotAnchors)
    {
        // Look up anchor.ID in our cache, add associated IWayspotAnchor
        if (!_wayspotAnchors.ContainsKey(wayspotAnchor.ID))
        {
            // Check if VPS couldn't restore the anchor
            if (wayspotAnchor.Status == WayspotAnchorStatusCode.Failed) {
                // ...handle failed anchor restore condition...
                continue;
            }
            _wayspotAnchors.Add(wayspotAnchor.ID, wayspotAnchor);
        }
        Debug.Log($"Created wayspot anchor {wayspotAnchor.ID}");
    }
    // Start tracking created anchors
    _wayspotAnchorController.ResumeTracking(wayspotAnchors);
}

Create GameObjects associated with your anchor.

Once you have a IWayspotAnchor for a successfully created anchor, you can create GameObjects in your scene for virtual objects associated with your anchor. The following example instantiates a GameObject from a _anchorPrefab and associates the GameObject with an anchor using WayspotAnchorTracker.

using Niantic.ARDK.Extensions;

private GameObject CreateWayspotAnchorGameObject
(
    IWayspotAnchor anchor,
    Vector3 position,
    Quaternion rotation,
    bool startActive
)
{
    var go = Instantiate(_anchorPrefab, position, rotation);

    var tracker = go.GetComponent<WayspotAnchorTracker>();
    if (tracker == null)
    {
        tracker = go.AddComponent<WayspotAnchorTracker>();
    }

    tracker.gameObject.SetActive(startActive);
    tracker.AttachAnchor(anchor);

    return go;
}

Save the anchor payload.
Each successfully created IWayspotAnchor will have a Payload, a binary blob that you should save to use when you want to restore previously created anchors, or to share the anchor with other users. The payload is created by VPS and is only available once the IWayspotAnchor.Status is Success or Limited. See Persisting and Sharing Wayspot Anchors for how to serialize and deserialize Wayspot Anchors.
Track anchor position updates.
Once a Wayspot Anchor has been successfully created, subscribe to the anchor’s TransformUpdated event to get corrections from VPS for the anchor’s position and orientation as the user moves. See Handle Anchor Tracking Updates for how to do this.

Restoring a Previously Created Wayspot Anchor

Use the following steps to restore a previously created Wayspot Anchor:

Restore the anchor using the anchor payload.

Call WayspotAnchorController.RestoreWayspotAnchors(), providing a list of one or more anchor payloads that identify which anchors need to be restored. RestoreWayspotAnchors() will return an array of IWayspotAnchors.

The following example calls RestoreWayspotAnchors() using a previously deserialized array of payloads, enables position tracking for each restored anchor, and adds the restored anchors to a simple cache.

using Niantic.ARDK.AR.WayspotAnchors;

private Dictionary<Guid, IWayspotAnchor> _wayspotAnchors;

// Deserialize/load saved payloads, using WayspotAnchorPayload.Deserialize() as needed
// var payloads = ...load payloads...
if (payloads.Length > 0)
{
    var wayspotAnchors = _wayspotAnchorController.RestoreWayspotAnchors(payloads);

    // Resume tracking restored anchors
    _wayspotAnchorController.ResumeTracking(wayspotAnchors);

    // Add restored IDs and IWayspotAnchors to cache
    foreach (var wayspotAnchor in wayspotAnchors)
    {
        // Look up anchor.ID in our cache, add associated IWayspotAnchor
        if (!_wayspotAnchors.ContainsKey(wayspotAnchor.ID))
        {
            // Check if VPS couldn't restore the anchor
            if (wayspotAnchor.Status == WayspotAnchorStatusCode.Failed) {
                // ...handle failed anchor restore condition...
                continue;
            }
            _wayspotAnchors.Add(wayspotAnchor.ID, wayspotAnchor);
        }
        Debug.Log($"Restored wayspot anchor {wayspotAnchor.ID}");
    }
}

If you need to load previously persisted Wayspot Anchor payloads see Persisting and Sharing Wayspot Anchors for how to serialize and deserialize Wayspot Anchors.

Track anchor position updates.
Once a Wayspot Anchor has been successfully restored, you’ll need to subscribe to the anchor’s TransformUpdated event to get corrections from VPS for the anchor’s position and orientation as the user moves. See Handle Anchor Tracking Updates for how to do this.

Pausing Wayspot Anchor Tracking

Your AR experience might use many Wayspot Anchors, however you might not need to track and display associated game objects all the time. For example, you might have a game object used to help players visualize placement during a specific mode of your game, that you don’t need to track (or display) in other game modes. You can pause tracking for VPS Wayspot Anchors in these situations to reduce computational and network overhead.

To pause anchor tracking, use WayspotAnchorController.PauseTracking() with the wayspot anchors that don’t need to be tracked. Once you need to resume tracking these anchors, use WayspotAnchorController.ResumeTracking() with the paused wayspot anchors.

using Niantic.ARDK.AR.WayspotAnchors;

IWayspotAnchor[] wayspotAnchors;

// ...populate wayspotAnchors array with IWayspotAnchors you want to pause...

// Pause tracking on anchors in the wayspotAnchors array
_wayspotAnchorController.PauseTracking(wayspotAnchors);

Stopping a VPS Session

If you no longer need to create or track any Wayspot Anchors, you can stop the VPS service without stopping your AR session. You might need to do this if your AR experience needs to provide AR features when your users are not near any VPS-activated Wayspots. For example, if your users are traveling between different VPS-activated Wayspots, but you still want to display some virtual objects using AR depth, or AR meshing.

You might also need to stop and restart a VPS session when your app encounters localization issues. See “Understanding Localization Flow” in Localizing with VPS for examples of when you might need to restart VPS. Also, see “Restarting VPS” in Localizing with VPS for additional details on what happens when you restart a VPS session.

Stop the VPS session using WayspotAnchorController.StopVps(). Any in-progress Wayspot Anchor creation or tracking will be canceled.