Skip to content

Getting Started

Jump to bottom
Michael Starrett edited this page Jul 15, 2019 · 45 revisions

Getting Started

Get the Landmarks master project folder and open it in Unity

  1. Fork, clone, or download the repository here

  2. Open the project in Unity. I do my best to stay up-to-date in using the most recent LTS release of Unity from the previous calendar year (e.g., in May of 2019 Landmarks used Unity2018.4.1f1 (LTS)). I recommend downloading UnityHub to manage versions (getting started with UnityHub)

  3. That's it! Play around in the prebuilt demo scene (Assets/Landmarks/Scenes/demo/demo_SimpleSample_50x50.unity) to get familiar with Landmarks and see a configured and functioning simple navigation experiment, or follow one of the tutorials below to learn how to add new tasks to an existing Landmarks-compatible environment (Assets/Landmarks/Scenes/SimpleSample_50x50.unity) or create your own new Landmarks-compatible scene from scratch using the _Landmarks_ unity prefab (Assets/Landmarks/Prefabs).

Open a functional Navigation Experiment (demo_SimpleSample_50x50.unity)

  1. From the Unity Editor, open Assets/Landmarks/Scenes/demo/demo_SimpleSample_50x50.unity

  2. Optional The experiment is set to operate on desktop interfaces by default. To use another interface (such as VR with the HTC Vive), use the hierarchy to navigate to the LM_Experiment GameObject (child of _Landmarks_) and select it. Click the dropdown next to "User Interface" in the inspector window and select the desired interface.

  3. Click the "Play" button in the Unity editor window and play the game. The experiment will include a welcome message, a target-learning phase (LearnTargets), navigation to each target in a random order, and an ending message. You have just completed a simple navigation experiment. The data from sessions run in the Editor will be saved in the project folder under /data/tmp/test.log (note this file will be overwritten each time the scene is played from the editor window).

Add new tasks to an existing Landmarks-compatible environment (create demo_SimpleSample_50x50.unity from SimpleSample_50x50.unity)

  1. From the Unity Editor, open Assets/Landmarks/Scenes/SimpleSample_50x50.unity

  2. In the hierarchy, expand the parent GameObjects so the "Tasks" GameObject is visible (_Landmarks_/LM_Experiment/LM_Timeline/Tasks).

  3. In the project window, navigate to Assets/Landmarks/Prefabs and drag the TASK_LearnTargets prefab onto the Tasks GameObject so it is placed as a child in the hierarchy window.

    • In the hierarchy, expand TASK_LearnTargets and select the ViewTargets GameObject.
    • In the inspector window, set the "repeat" value to 1 (you can choose any integer and this will determine how many times the task will repeat practicing each target object.

  4. In the project window, navigate to Assets/Landmarks/Prefabs and drag the TASK_NavigationTask prefab onto the Tasks GameObject so it is placed as a child in the hierarchy window.

    • In the hierarchy, select TASK_NavigationTask and note the "repeat" value is set to 1 (we will leave it at 1, but you may change it to any integer you like to add blocks of navigation).
    • In the hierarchy, expand TASK_NavigationTask and select the NavigationTrials GameObject
    • In the inspector window, set the "repeat" value to 3 (we are using 3 because that is the number of targets in the scene; you can set this value to any integer and it will determine how many trials of navigation there are in each block).

  5. Click the "Play" button in the Unity editor window. The scene should now operate exactly as it would if you opened the preconfigured demo scene detailed in the previous section (Assets/Landmarks/Scenes/demo/demo_SimpleSample_50x50.unity).

Create a Landmarks-compatible Environment from scratch (create SimpleSample_50x50.unity from a new scene)

  1. From the Unity editor window, select File > New Scene

  2. Delete everything from the scene's hierarchy (Main Camera and Directional Light)

  3. Drag and drop the _Landmarks_ prefab (Assets/Landmarks/Prefabs/) into the hierarchy

  4. Locate the LM_Environment GameObject, a child of our new _Landmarks_ GameObject, and expand it to view children

At this point, you should be able to click play in the Unity editor window. The prefab comes configured for Desktop use and includes a default welcome and ending instruction.

  • Populate the Environment gameObject (child of the Landmarks prefab, with filler props (non-target buildings, sidewalks, streets, trees, etc.)
    • NOTE: Don't create or place any actual navigation targets. Just aesthetics for now.
    • If you are using an existing environment, move all non-target environment objects onto the Environment object
    • You may wish to organize aspects of the environment via additional empty child gameObjects of LM_Environment (e.g., an empty "NonTargetBuildings" gameObject as a child of LM_Environment that contains any building/house/store prefabs/gameObjects that are not going to be targets for navigation/memory)
    • Important - Be sure to tag all of these objects as "props" in the Inspector
  • Place empty game objects (or, if all your targets are identical, a blank prefab of your target object) as children of the TargetLocations gameObject.
    • NOTE: These are not your actual targets, but merely placeholders that facilitate Landmarks ability to flexibly populate targets in predefined or randomized order (depending on your experimental design/needs) targets in the environment
    • Ensure that the empty or placeholder object has the correct Transform (local position and rotation) that you want the populated target to have when the experiment begins (this is why it is good to use an empty target prefab)
    • Select all of your TargetLocations children and add them to the "Targets" Layer in the inspector
    • Be sure that each of these objects has a unique name or Landmarks will throw errors when populating targets
  • Add gameObjects that will serve as navigation/memory targets as children of the "TargetObjects" gameObject.
    • If using an existing environment, make your target gameObjects children of the TargetObjects gameObject
    • Once finished, select all of these objects use the Inspector to tag them as "Target" and place them in the "Targets" layer
    • Ensure that each of these gameObjects are outside the environment and the view of any cameras
  • In the MapTestPlaceHolders gameObject (8 children by default when using the _Landmarks_ prefab)...
    • Adjust so the number of children matches TargetObjects and TargetLocations
      • If your environment has less than 8 targets, remove children (beginning with the last child) until there are the same number of children as TargetObjects and/or TargetLocations
      • If your environment has more than 8 targets, duplicate the last child and adjust it's transform to be consistent with the other children. Repeat until there are the same number of children as TargetObjects and/or TargetLocations
    • Adjust the position to be just outside the environment. This allows mapTask functionality.
  • In the MapTestHighlights gameObject (8 children by default when using the _Landmarks_ prefab)...
    • Adjust so the number of children matches MapTestPlaceHolders, TargetObjects, and TargetLocations
      • If your environment has less than 8 targets, remove children (beginning with the last child) until there are the same number of children as TargetObjects and/or TargetLocations
      • If your environment has more than 8 targets, duplicate the last child and adjust it's transform to be consistent with the other children. Repeat until there are the same number of children as TargetObjects and/or TargetLocations
    • Ensure that each of these gameObjects are outside the environment and the view of any cameras

Set up your experiment (Experiment child gameObject of the _Landmarks_ Prefab)

  • Select LM_Experiment in the Hierarchy (child of _Landmarks_ gameObject prefab) and use the Inspector to select the desired user interface from the dropdown menu (User Interface enum on the Experiment (Script) component of LM_Experiment
  • Expand the LM_Timeline component, which reveals an ordered list of the experiment procedure. The framework functions in essentially 4 loops (practice, pre, main, and post). Each loop is represented by a gameObject by that same name.
    • Drag and drop experiment prefabs onto any of the task loops and configure them based on the documentation for that task prefab.
  • NOTE: The _Landmarks_ prefab comes with the NavigationTask prefab (Landmarks/Prefabs/NavigationTask.prefab) preconfigured on the MainTaskLoop. If you have followed this guide correctly, so far, you should now be able to run a basic navigation task in your scene and get output as a log file (In your project folder, you will find a file named test.log in the following path: ProjectFolder/data/tmp/test.log)
    • This task can be moved to any of the four task loops without need for any additional changes. It can also be removed and replaced with other tasks, or have additional tasks placed on the same loop.

NOTICE This guide is a living document. If you have any questions or issues, please let us know by emailing Mike Starrett at [email protected].

Clone this wiki locally