Marker Sync

Using CV objects (such as QR codes) for fast join and sync in multiplayer.

This is an experimental feature. The API and documentation have not yet been polished/tested to release standards, but are provided for exploration.

Sync against markers, not maps.

Overview

Marker Sync was made to smooth the process of players starting up a multiplayer AR session together. By using defined markers to sync players instead of scanning for maps, this API enables not only joining a networked session (like Pokemon Go’s implementation of QR code scanning to join a multiplayer Buddy session) but also also eliminates the side-to-side swaying usually required.

Flowchart

  • Dotted line boxes indicate steps taken by the developer

  • Solid line boxes indicate steps taken by the game player

  • Steps in filled-grey areas should be happening simultaneously

../../../_images/marker_sync_flowchart.png

Using the API

Full usage of the API is also shown in the flowchart above.

Generating Markers

The IARNetworking.InitializeForMarkerScanning method only requires the marker’s points’ positions, which means that markers can be generated, displayed, parsed, and/or scanned in any way, as long as the following are adhered to:

  • Marker consists of at least 4 identifiable points (ex. The 3 position points and 1 alignment point in a QR code)

  • Marker points are stationary on screen while displayed

  • An implementation of IMarkerScanner can be used to scan the world for a marker

    • Optionally passed in with the call to IARNetworking.ScanForMarker.

    • If none passed in, the default implementation (ARFrameMarkerScanner), which scans for QR codes, will be used.

  • An implementation of IMarkerParser can be used to extract MarkerMetadata (serialized as a byte[]) from an array of pixels provided by an IMarkerScanner.

    • Optionally passed in when constructing an ARFrameMarkerScanner.

    • Required when using custom implementations of IMarkerScanner.

    • If none are passed in, or if the default IMarkerScanner is used, the default implementation (ZXingBarcodeParser) will be used. This only works when the marker is a QR code.

  • The same implementation of IMarkerParser can be used to identify the 4 or more marker points registered by the host’s call to IARNetworking.InitializeForMarkerScanning

  • An implementation of IMetadataSerializer can be used to deserialize the bytes from the IMarkerParser into a MarkerMetadata.

    • Optionally passed in with the call to IARNetworking.ScanForMarker

    • If none passed in, the default implementation (BasicMetadataSerializer) will be used.

Example

An example scene of utilizing a QR code to quickly join+sync multiple players into a Multiplayer AR session can be found in the ARDK Examples project under Assets/ARDKExamples/MarkerSync.

Helpers

  • ZXingMarkerGenerator is an example of how a barcode is generated with a MarkerMetadata, and of how to calculate the positions needed for the call to IARNetworking.InitializeForMarkerScanning

  • BarcodeDisplay is a helper component that can be placed in a scene to display a barcode generated using the ZXingMarkerGenerator.

Best Practices

  • Call IARNetworking.ScanForMarker after the device’s AR tracking state is optimal.

    • Tracking quality is accessible by through your ARSession’s CurrentFrame.Camera.TrackingState. Best quality is TrackingState.Normal.

  • Even after achieving a sync with a marker, keep the players looking in the same area (so it’s more likely a map is found and synced against) until PeerState is Stable for all players.

    • While Marker Sync allows for a near instantaneous sync between players, there’s no drift correction active like there is in ARDK’s traditional syncing methods.

    • The PeerState.Stabilizing state achieved through marker sync should be acceptable for play, but for the most reliable sync, using maps and getting to PeerState.Stable is best.

See Also