Sharing Virtual Object Information

Most Shared AR experiences will involve sharing virtual object information between users. For example, if a user manipulates a virtual object, you`ll need to make sure that all other users in the shared AR environment are able to see the effects of this manipulation immediately.

ARDK provides two networking APIs for communicating between users in a shared AR experience. The High-level API (HLAPI) provides a “networked object” system that makes it easy to share virtual game object information between users. The Low-level API (LLAPI) provides a flexible, general-purpose messaging system for sharing information between users.

Both HLAPI and LLAPI utilize the ARDK client-server architecture used for networked AR sessions, with designated host and peer clients, as described in Setting Up a Networked AR Session and Understanding Networking and LLAPI.

When to Use HLAPI

If your Shared AR experience requires coordinating object spawning, object manipulation, and sending/receiving objects over network streams rather than raw byte streams, use the HLAPI to manage all of this in an intuitive way. HLAPI features include:

  • Network spawning/despawning of objects. You can spawn or despawn a game object with a single API call, and have the object spawn/despawn in all users in the Shared AR session.

  • Shared data authority management. Define ownership over networked data, so all clients agree on who is permitted to despawn objects, write to certain fields, listen for updates on those fields and more.

  • Sharing object transforms. A client with data authority can manipulate the transform of a virtual object and automatically communicate this transform to all clients in the session.

  • Support for generic network data fields. Automatically propagate updates for a generic data field to other clients in the session.

  • Sending object data in message streams: Send and receive objects in a stream instead of raw byte messages.

When to Use LLAPI

LLAPI provides a networking API for efficient peer-to-peer messaging. Through LLAPI, the ARDK also handles session management, peer discovery, message routing, and a session-based data store. Use LLAPI if your application has very few message types (i.e. just spawning a single object and moving it around), or if you have a preferred networking library that can utilize the raw byte message API and handle its own addressing/parsing.

Also consider using LLAPI if you have very specific network performance requirements. HLAPI does come with some per-message networking overhead. Every message is tagged with IDs to identify and route networked object messages correctly. HLAPI also has some run-time overhead involved with managing peers and querying groups and handlers for messages every frame.

When to Use Both HLAPI and LLAPI

Generally, it’s not recommended to use both HLAPI and LLAPI for sharing virtual object information, as this increases the complexity of communicating between users. However, you might have scenarios where you need to manage object messaging via HLAPI, but require additional network messaging that HLAPI isn’t a good fit for.

For additional guidance and potential issues to be aware of when using both HLAPI and LLAPI, see Using Both HLAPI and LLAPI