Skip to content

Getting Started

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

Get the Landmarks master project folder and open it in Unity

  1. Fork and clone or simply download the repository here

    • It is recommended that users fork the public repository and then clone their forked repository to a local repository. A useful guide for completing this process can be found here. Tracking your forked repository and the upstream repository allows you to stay up-to-date with any new developments and improvements to Landmarks.

  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).

Other tutorials for getting started with Landmarks

• Open a functional Navigation Experiment (demo_SimpleSample_50x50.unity) • Add new tasks to an existing Landmarks-compatible environment (create demo_SimpleSample_50x50.unity from SimpleSample_50x50.unity) • Create a Landmarks-compatible Environment from scratch (create SimpleSample_50x50.unity from a new scene)

Open a functional Navigation Experiment (demo_SimpleSample_50x50.unity)

  1. From the Unity Editor, use the Project window to 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.

  4. 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

  5. Populate the environment with filler props

    • Right click the filler_props GameObject. Select "Create Empty" and rename this new child of filler_props to "NonTargetProps"

      • Right click our new NonTargetProps GameObject and select "3D Object > Cube"

        • Click on our new Cube GameObject and, under the Transform component, set the Position (-12.5, 5, 13.8) and Scale (5, 10, 5)

      • Right click the Cube object we just created and select "Duplicate" (repeat this process until there are 5 copies)

      • In the inspector, under Transform, set the Position of each cube GameObject (functionally, these GameObjects can be located anywhere in the environment)

      • In the project window, navigate to Assets/Landmarks/Materials/ then drag and drop the SimpleSample_Pillar material onto each cube that we just created

    • Right click the filler_props GameObject. Select "Create Empty" and rename this new child of filler_props to "Walls"

      • Right click our new Walls GameObject, select "3D Object > Cube", and change the name of this GameObject to "C"

        • In the inspector window, under Transform, set the Position (0.5, 3.05, 24.5), Rotation (0, 0, 0), and Scale (49, 6, 1)
        • In the project window, navigate to Assets/Landmarks/Materials/ then drag and drop the SimpleSample_CyanWall material onto the GameObject that we just created

      • Right click the Walls GameObject again, select "3D Object > Cube", and change the name of this GameObject to "M"

        • In the inspector window, under Transform, set the Position (25.5, 3.05, 0), Rotation (0, 90, 0), and Scale (50, 6, 1)
        • In the project window, navigate to Assets/Landmarks/Materials/ then drag and drop the SimpleSample_MagentaWall material onto the GameObject that we just created

      • Right click the Walls GameObject again, select "3D Object > Cube", and change the name of this GameObject to "Y"

        • In the inspector window, under Transform, set the Position (-24.5, 3.05, 0), Rotation (0, 90, 0), and Scale (50, 6, 1)
        • In the project window, navigate to Assets/Landmarks/Materials/ then drag and drop the SimpleSample_YellowWall material onto the GameObject that we just created

      • Right click the Walls GameObject again, select "3D Object > Cube", and change the name of this GameObject to "K"

        • In the inspector window, under Transform, set the Position (0.5, 3.05, -24.5), Rotation (0, 0, 0), and Scale (49, 6, 1)
        • In the project window, navigate to Assets/Landmarks/Materials/ then drag and drop the SimpleSample_BlackWall material onto the GameObject that we just created

    • Right click the filler_props GameObject. Select "3D Object > Cube" and rename this new child of filler_props to "terrain"

      • Click on our new terrain GameObject and, under the Transform component, set the Scale (50, 0.01, 50)
      • In the project window, navigate to Assets/Landmarks/Materials/ then drag and drop the SimpleSample_MarbleFloor material onto the terrain GameObject we just created.
  • 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

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