Using the Remote Authoring Assistant

The Remote Authoring Assistant allows you to load a VPS location into your Unity project. You can find a location using the Geospatial Browser and you will need to download a zip file of that location in order to load a location.

Loading a location

  1. Import the zip file into your Unity project. You can do that by drag and drop or by using the Remote Authoring Assistant.

    1. Drag and Drop: Drag and drop the zip file into your project folder in Unity.

    2. Remote Authoring Assistant:

      1. Launch the scene using ARDK > Lightship > Remote Authoring Assistant > Open.

      2. Select the RemoteAuthoringAssistant Game Object.

      3. Follow the prompt to Import New Location in the Inspector window.

        Import Location
  2. Once the location is imported, you can now explore the remote authoring scene in the editor by choosing that location in the Selected Location dropdown menu on your RemoteAuthoringAssistant.

    Note

    Important: Your location is imported into an editor only scene used by the Remote Authoring Assistant. Use the RemoteAuthoringAssistant UI to work with this scene as described in the next steps, and don’t edit the editor scene content directly. The “Making a Build” section explains how to export your anchor content into a playable scene.

  3. Move your default anchor.

    1. You will find child objects within your RemoteAuthoringAssistant Game Object. By default there is one moveable child object named Default. This is your initial origin anchor. You are free to rename this anchor and move it around. In the scene view you can see that a red placeholder gizmo identifies this Anchor and its position in relation to your location.

      Default anchor
      1. Due to the way meshes are generated, some default anchors may appear farther from the mesh than expected and you may need to move the GameObject to into scene view.

    2. It may be convenient to see how your content would look placed at one of these anchored points. To associate a GameObject prefab to an anchor, add a GameObject to the AssociatedPrefab list on your Anchor object. The authoring assistant will now visualize your game content in relation to your anchor as you move your anchor around.

      1. Don’t forget to save your anchors as you move them around.

        Anchor modified

        Notice how you can see if a property on your anchor is not yet saved. Such properties remain bolded until a Save occurs.

      2. Tip: Saving an anchor is how your wayspot anchor payload gets generated (which would be visible in the Payload section of your anchor component. If the payload section is Invalid you must Save your payload to see your serialized payload string.

  4. Create new anchors.

    1. You may want more than one anchor to be defined in your location. You can use the RemoteAuthoringAssistant component and click on Create New Anchor. You can have any number of anchors in your location.

    2. Remember that you should not try to create these game objects manually. DO NOT USE Unity’s built-in “Duplicate” function on anchor game objects. You must use the RemoteAuthoringAssistant UI to Create, Delete, and Save anchor content. Using the RemoteAuthoringAssistant UI to Create, Delete, and Save content ensures that changes are saved in the LocationManifest.

  5. You have now authored anchors at your first location. You have anchor content stored in a Location Manifest, which is a scriptable object that was generated when you first imported your zip file! You can use that manifest to generate a JSON manifest if you choose, that you can bring into your AR build. Location manifests

Note

Advanced Concept Note: The VPSLocationManifest is an Editor-ONLY scriptable object. This makes the file impossible to use outside of the context of the Editor. Storing this manifest in your build or in an asset bundle is not possible so we’ve provided a means of exporting to a JSON TinyVPSLocationManifest (see “Best Practices” below) for storing anchors in a lightweight data structure. Runtime applications require generating a TinyVPSLocationManifest which is seen in the LocationManifestManager script in the RemoteAuthoring example scene described in “Making a Build” below.

Making a Build

We will show you how to put your content in a build using the RemoteAuthoring example scene. If you want to build something that’s part of a larger infrastructure, we have some tips and tricks as well.

While developing an application you may want to see your code run in your application without having to build it to your phone first. You can do this using the location manifest to create a mock asset for testing in the editor.

You can find the example scene in the ARDKExamples folder under RemoteAuthoring. This scene makes it easy to use the Location Manifests you’ve generated and consume them at runtime.

  1. Open the RemoteAuthoring example scene and find the ManifestLoader game object. This contains the LocationManifestManager component.

    1. To add your own content, drag your manifests into the drag and drop box at the top of the component. Populate anchors

    2. This location accepts both LocationManifest scriptable objects as well as Location Manifests JSON exports.

    3. Click the Populate Anchors button at the bottom of the component. From here you can attach content to your anchors if you have not done so already.

  2. Choose your manifests and populate anchors

    1. After pressing Populate Anchors, the Anchored Content list will be populated with any Unity GameObject-based content associated with your anchors.

    2. If you’ve used the Associate Prefab option while making your anchors then you should see your game objects in the list that is populated when you click the Populate Content toggle. When running the RemoteAuthoring example, the content will be loaded when the user presses the Load button and will become visible after the user has localized to the corresponding location.

  3. Run in Play Mode using a mock.

    1. To create a mock asset using the location manifest, find your manifest and click the Create button. You now have a mock asset you can use for testing in Editor.

      Create mock

      Use the Create button to create a mock to test with in Editor

    2. To use the mock asset, navigate to ARDK’s Virtual Studio (ARDK > Lightship > Virtual Studio), select your newly created Mock scene in the drop down, and click the Play button in the Unity editor.

At this point you should have all you need to make a build of your AR experience on an Android or iOS device. Please note: for ARDKv2.4, apps must target Android 12 (API level 31) or higher. Follow the steps to make a build on your device of choice!

Unity Editor Best Practices

Using JSON to store your manifest data somewhere else

You may not want to bundle a manifest in your project. While we don’t want to prescribe the best way to do that (create a JSON, use a database, etc), we’ve attempted to make it easy for you to save living data like anchors outside of the build so that you can update said content without having to always make a new build.

Manifest scriptable objects have an Export to JSON option that allows you to save a lightweight version of your remote content anchors. With the following two lines of code, you can transform that JSON content back into the TinyManifests data structure that is used in the example code.

var jsonString = (obj as TextAsset).text;
var manifest = JsonUtility.FromJson<TinyVPSLocationManifest>(jsonString);

When paired with Unity examples about how to read a file from the web, creating a remote manifest for your project is fairly straightforward.

Known Issues & Workarounds

The Default anchor cannot be used in Mock mode with Virtual Studio.

  • Every location that is imported will contain an anchor named “Default (Authored Anchor)”.

  • Attempting to load this anchor in virtual studio mock mode will result in the following exception “FormatException: Unrecognized Guid format.”

  • The work around is to either:

    • Delete the anchor named “Default” and create a new anchor.

    • Change the position or rotation of the Default anchor.

  • This is only a problem when running in mock mode in the Unity editor. When running on device, the default anchor does not show this behavior.

When using a mock location in the Unity editor (with Virtual Studio), loading content for a different location will cause an error.

  • The error will show up as an exception “ArgumentException: An item with the same key has already been added. Key: 00000000-0000-0000-0000-000000000000”.

  • The work around is to only load content for the currently selected mock location.

  • It is not currently possible to switch mock locations while running with Virtual Studio without restarting the editor play session. Therefore, only one location can be tested in each play session when using mock locations.

Anchors for each location must have unique names.

  • If a single location manifest contains anchors with the same name, you will encounter errors when loading the content for that location.

  • In Mock mode in the Unity editor, an exception similar to the following will be generated: “ArgumentException: An item with the same key has already been added. Key: eeaa8ed7-15bf-49bc-9b9a-7c5466b4ae5f”.

  • On device, some of the content for the selected location will be missing.

  • The work around is to ensure that all anchors within a single location manifest have unique names.

Not clicking the “Populate Content” button on the ManifestManager after making changes with the RemoteAuthoringAssistant can result in stale content and/or errors.

  • The ManifestManager is not updated until “Populate Content” is pressed.

  • If changes or fixes are made to the locations in the RemoteAuthoringAssistant, those will not show up at runtime unless “Populate Content” is pressed.

  • The work around is to always press “Populate Content” before running in editor or building to device.

With AR depth enabled, assets that are located more than ~20 meters from the user may not show up in the app experience – keep anchors within or a short distance from the mesh surface area.

If you use the Remote Authoring Assistant to associate multiple prefabs with a single anchor, only the first prefab will be picked up by the ManifestLoader – you will receive a Unity warning in the console when trying to associate more than one prefab.