1. Home
  2. Docs
  3. Unity SDK
  4. Unity Templates
  5. A Closer Look: Explore AR

A Closer Look: Explore AR

This document dives into the structure of the Explore AR Unity project. This is by no means the only way to set up a Motive project, however we’ve settled on a number of best practices that make using Motive easier.

We’ll go node-by-node.

  • App

    The app node contains setup code and other logic that maps Motive resources and events into the app.

    • Setup

      1. AR Quest App Setup
        This component handles app startup and initialization. It uses the specified AppConfig to connect to the Motive service.
      2. Build Settings
        A number of features in Motive can behave differently in Debug vs. Release mode. For example, when in Release mode only Script Launchers in the “Published” state will be displayed in the Quests/Tours menu.
      3. Dynamic Config
        If set to “No”, the AppConfig in the Setup script is used to configure the connection to the Motive service. If “Yes”, the user must log in and choose their space/config to connect to the service.
      4. World Valuables Initializer
        Initializes “WorldValuablesManager”, which handles all Location Valuables and their associated Collection Mechanics.
      5. Mapbox Initializer
        Initializes the Mapbox Location Cache which feeds Mapbox/OSM locations to the Motive Location Service.
      6. Locative Audio Initializer
        Initializes the Locative Audio engine.
      7. Dark Sky Initializer
        Connects to your Dark Sky account to use weather data for weather conditions, etc.
    • Language Settings
      Sets the default language for your app.
    • Playables

      Handles all audio/screen content.

      1. Audio Content Player
        Handles all “Localized Audio Content” Playables. Implements support for ambient, soundtrack, and narrator audio.
      2. Default Playable Content Handler Delegate
        The Playable Content processor passes Playables to PlayableContentHandler, which in turn hands them off to a delegate. This is the default delegate implementation. If you want to customize how playables work, the best place to start would be to create a subclass of this delegate.  (This pattern will appear in a number of places. The Script Processor calls Resource Processors, which in turn hand the resource off to a “Manager” or a “Handler.” The Managers and Handlers are in charge of managing the state of the Resource, and often use Delgates to connect the Resource to the App UI. This leaves any UI decisions out of the hands of the Handlers and Managers and lets them just focus on game logic.)
    • World Objects
      Has an Object Inspector Manager that chooses UI elements to push to the screen in reaction to Object Inspectors.
    • Unity Webcam Manager
      Abstracts access to the webcam. You can replace the default Unity Webcam with your own implementation by implementing a Webcam Provider. This Webcam is used by the Default AR World Adapter and the QR Code scanner.
    • Location Valuables Drivers
      These drivers handle the game play for the different collection mechanics for Location Valuables.

      1. Map Location Collection Driver
        Handles “Collect on Map” mechanics, usually by clicking a “Collect” button when the item is selected and the player is in range.
      2. AR Location Collection Driver
        Handles “Collect with AR” mechanic. Implemented as an AR item that the user taps to collect.
    • 2D Map Handlers
      These handlers manage map annotations for different sources.

      1. Task Annotation Handler

        These two components handle map annotations for Location and AR Tasks that have locations that need to show on the map. The range colours define the color shown by the annotation range circle when the user is in/out of range.
      2. Marker Annotation Handler
        Handles annotations for the “Map Marker” class.
      3. Locative Audio Annotation Handler
        Handles Locative Audio annotations when “Show on Map” is selected.
    • Attractions [coming soon]
    • Preview Panel Handler
      1. Manages the “Preview” panels that show at the top of the Map. Preview panels ensure that the user always has a clear idea of what they need to do next, which is very important for location-based games.
    • Task Minigames
      1. Delegates that handle the AR Catcher and Quiz Minigames. Use these as a guideline when adding your own Task Minigames.
    • QR Token Scanner
    • Rewards Delegate
      1. Delegate for the Reward Manager that handles displaying the Reward Pop-Up window.
    • Google Poly
      1. Manager for handling Google Poly objects.
  • 2D Mapbox
    Implementation of the Mapbox maps using 2D visualizers.

    1. MapController
      This is the main entry point for access to Map functionality.

      1. Mapbox Location Cache Driver
        Connects Mapbox/OSM points of interest to the Motive location services.
    2. Swivel
      Has a “Rotate With Compass” component that’s disabled by default. Enabling this component will cause the map to rotate with the compass.

      1. Mapbox Tile Layer

        Has a Map Tile Driver component that manages the Map Tiles. The Tile Driver provides a slippy map implementation and applies render throttling to smoothly handle rapid changes in zoom or position.

        1. Map View Wrapper
          Connects the Map Tile Driver to the Mapbox map tile renderers.
      2. Canvas
        Parent of the Map View, allows the Map View to display UGUI annotations.

        1. Map View
          Map Views handle rendering Map Annotations. Map Views communicate with your app through IMapViewDelegate (in this case implemented by MapController). Map Views manage the lifecycle of annotation objects to ensure the app is not using more memory for annotations than required.

          1. Map Surface and Input
            This is the rendering surface for map annotations and handles map inputs through the MapInput script.

  • Motive
    This prefab handles the initialization of the Motive SDK and communication with the Motive server.

    1. WebServices

      1. Motive Url – the URL of the Motive service.
      2. App Id/Api Key – can be set here directly if not using an AppConfig.
      3. User Domain – the domain for users of the app to log into (coming soon)
      4. Use Debug Reachability – if true, uses the “Debug Reachability” defined in the next field to test the startup behaviour of the app under different network reachability scenarios.
      5. Config Name – can be set here if not using an AppConfig.
      6. Use Dev Catalogs – if true, use dev catalogs instead of published catalogs.
      7. Require Network Connection – if true, the app requires a network connection on boot to check for the latest catalogs and scripts. If false, the app will use the most recent catalogs that it has stored.
      8. Cell Download Threshold (in MB) – the maximum download size allowed over the cell network without prompting the user.
    2. Diagnostics

      Uses Unity Logging Control to handle app logs.

      1. Debug Level – log level in debug mode
      2. Release Level – log level in release mode
      3. Include Timestamps – if true, logs include a timestamp
      4. Include Thread Id – if true, logs include a thread ID
      5. Enable All Loggers – if false, only the loggers defined in the “Enabled Loggers” array are enabled
      6. Log To File – if true, logs are also stored in a file marked with a timestamp
      7. Log File Path – the local path to the log files
    3. Threading
      The ThreadHelper manages marshaling calls from background threads to the main Unity thread.
    4. LocationServices
      Debug Player Location manages the debug Location Manager in the Unity editor.

      1. Player Location – set to a “Unity Location” as the starting point for testing.
      2. Keyboard Moves Player – if true, you can manipulate the user’s location in the Unity Editor using the arrow keys and the A & S keys to turn left and right
      3. Move Relative To Heading – if true, the “up” key always moves the user in the direction the user is facing
      4. Player Speed – speed of the user in m/s
      5. Start Heading – the initial heading of the user on the map
      6. User Anchor Position – uses the UserLocationService.Instance.AnchorPosition property to set the user’s position (generally used to test the “Warp” feature which uses the same property)
      7. Map Controller – by default, uses the MapController singleton
    5. ScriptManager

      Handles launching/shutting down scripts.

      1. Auto Launch Mains – if true, automatically launches any “Main” Scripts (as defined by “Main Script Names”)
      2. Main Script Names – an array of Script names to treat as “Main” Scripts
    6. Platform
      This is the main integration point for platform-specific features.

      1. On Enter Background – called when the app is entering the background
      2. On Exit Background – called when the app is returning to the foreground
      3. On Pause Audio – called when Audio Player content is paused, usually because higher-priority audio is playing (user got a Screen Message with attached audio, user got a Playable Video, user played an audio file from their inventory, etc.)
      4. On Resume Audio – called when Audio Player content resumes
    7. Storage Configuration

      1. Use Encryption – if true, the app will use encryption to store local game state
      2. Encryption Key, Encryption IV – inputs to the encryption storage
    8. Native Hooks (only available with Unity native plugins)
      1. Use Native Downloader (iOS only) – uses a native file downloader implementation that speeds up file downloads by up to 50%
      2. Enable Background Location – enables location updates while the app is running in the background
      3. Enable Background Audio – enables audio to play in the background
      4. Enable Notifications – enable system notifications
      5. Enable Background Notifications – enable notifications to be scheduled to be delivered even when the app is shut down
      6. Enable Beacons – enables support for BLE beacons
    1. Screen Sleep Behaviour
      1. Screen Sleep Behaviour – can disable screen sleep under certain circumstances
    2. Compass Type
      1. Compass Type – sets the type of compass used by the app
    3. Background Notifier
      Handles background notifications if used by the app.
  1. UI
    Root node for the app’s UI.

    Contains the following components:

    1. Panel Manager

      A singleton Panel Container that handles pushing/popping Panels.
    2. AR Quest App UI Manager
      Handles the UI state of an AR Quest-based app, including toggling between AR mode and Map mode, etc.

      1. Main Camera – will use the default main camera if not set
      2. AR Canvas – a canvas to display when in AR mode
      3. Map Canvas – a canvas to display when in Map mode
      4. AR Mode Objects – Game Objects that are active only in AR mode
      5. Map Mode Objects – Game Objects that are active only in Map mode
      6. Tour Name Text – a Text field to set to the title of the currently running Tour or Quest
      7. Activate When Running – Game Objects that are active only when a Tour or Quest is running
      8. Stop Tour Confirm – a confirmation panel to show when the user decides to quit a Tour or Quest
      9. Initial Mode – defines whether the app starts in Map or AR mode
    3. Interface Command Handlers
      Interface Commands allow you to control your app’s UI behavior with a Script.

      1. Map Zoom Command Handler – handles the Map Zoom interface command (pan and zoom to a particular location on the map)
      2. UI Mode Switch Command Handler – handles the UI Mode Switch interface command (allows user to switch between AR and Map mode)
    4. Warp Manager – handles the Warp feature
    5. Main Canvas
      Canvas that is viewable in Map mode.

      1. Screen Container – can be used to change the viewable area for the main canvas screens
        1. Safe Area Top – unused screen space at the top of the screen (for iPhone X, e.g.)
        2. Safe Area – viewable safe area
          1. Map – Panels related to the map
            1. Task Previews
              Preview Panels are important for location-AR apps to give users clear guidance for what they should do next. These Panels have some redundancy that will be addressed in a future release. This node also includes Panels that display information for the currently selected map marker (if there is one).
            2. Center Map – a button that centers the map
            3. Unwarp – a button that “unwarps” the user.
          2. Inset Toggle

            Contains Panels that sit inside the “Inset” area, with room for the header above and buttons below.
            Note: The Panel Container on this node has a Stack Behavior of “One At A Time.” This means that only one Panel at a time will be shown–if a new Panel is pushed, any existing Panel will be automatically popped.

            1. Inventory – the player’s inventory
            2. Tasks – player’s Tasks and Assignments
            3. Select Tour – the Quest or Tour select screen
          3. Hud – static elements of the Map UI, including the title bar at the top and buttons at the bottom.
          4. Full – debug screens (Scripts, Settings)
          5. Detail Views – these screens are shown when a user taps an Inventory item or Attraction (coming soon).
        3. Menu – the slide out menu
        4. Popover – dialogs that need to be displayed on top of any other screens
      2. Splash – splash and startup screens
        1. Account – handles signing in
        2. Loading – the main Motive loading screen
        3. Public Projects (QR) – the QR scanning screen
    6. AR Canvas

      Components

      1. Panel Container – top level Panel Container for AR Mode. Note that the Root Panel is set to Default.
      2. AR View Manager
        1. Guide Panel – handles the AR “Guide” – arrows and instructions that help the user find items in AR
        2. Task Complete Panel – a Panel that is shown when a Task is complete
        3. Assignment Complete Panel – a Panel that is shown when an Assignment is complete
      3. AR Interactive Collectibles Manager – handles “interactive” AR items, used for AR “put” taskNodes
      1. Screen Container
        1. Default – the default AR mode Panel, defined as the Root Panel for a Panel Container on AR Canvas
          1. Editor Instructions – arrows with instructions for how to move the camera in AR mode when running in the editor
          2. Guide Container
            1. Guide Panel – instructions for user in AR mode
            2. Task Complete Panel – shown when a Task is complete
            3. Annotation Panel – shows annotations on AR objects (“Tap to Collect”, etc.)
          3. Loading – optional blackout screen that hides the camera while AR mode is loading (not used in Explore AR)
          4. Safe Area
            1. Interactive Items – collectibles that you can “put” in AR tasks
            2. Close – exits AR mode
        2. InspectorsAR world object inspectors
    1. Shared Canvas – a canvas that shared between AR and Map modes
      1. Pop Ups
        1. Reward Pop Up – shown when the player collects a reward
        2. Quiz Success – quiz success screen
        3. Safe Area
          1. PlayablesPlayable Content screens
          2. Quiz Screens – Quiz minigame screens

 

Was this article helpful to you? Yes No 1

How can we help?