Simulator Build Instructions

This document provides instructions on building the simulator and assets from source using the Unity Editor in developer mode.

Note: When a terminal is mentioned, it refers to cmd.exe on Windows and Terminal on Ubuntu.

Table of Contents

Installing the Unity Editor top#

  1. Download and Install Unity Hub

    • Ubuntu: You may need to allow the downloaded AppImage to be run as an executable
      • Right-click the AppImage
      • Select Properties
      • Go to the Permissions tab
      • Check Allow executing file as program
      • Alternatively, in the terminal run sudo chmod +x UnityHub.AppImage

  2. Download and Install Unity 2020.3.3f1 from the Unity Download Archive:

    • Click the Unity Hub button to have Unity Hub start the installation process
      • If the installation process fails to start on Ubuntu:
        • Right click the Unity Hub button and select Copy Link Address
        • In a terminal, type <PATH_TO_UNITY_HUB> <COPIED_LINK>
          • The copied link will be in the form unityhub://Unity-VERSION/XXXXXX (e.g. unityhub://2020.3.3f1/76626098c1c4)
          • Thus, if the Unity Hub application is in the current directory, type ./UnityHub.AppImage unityhub://2020.3.3f1/76626098c1c4
        • Unity Hub will open and guide you through the installation of Unity Editor
    • IMPORTANT include the Windows Build Support (Mono) for both Windows and Linux when installing Unity
    • (Optional) include support for Visual Studio for easier debugging
    • Verify installation
      • Under the Installs tab of Unity Hub there should be the expected version shown. In the bottom-left corner of the version, there should be an icon of the other OS (e.g. on a Linux computer, the Windows logo will be shown)

Installing Git LFS top#

Make sure you have git-lfs installed before cloning the Simulator repository.

  • Instructions for installation are here
  • Verify installation
    • In a terminal enter git lfs install
    • > Git LFS initialized. should print out

Building a standalone executable top#

  1. Clone simulator project from GitHub (open-source) release branch.

    • Open a terminal and navigate to where you want the Simulator to be downloaded to
      • If you want the Simulator in your Documents folder, use cd in the terminal so that the input for the terminal is similar to /Documents$
    • Open-source user: git clone https://github.com/lgsvl/simulator.git
    • Verify download
      • Above clone will create a Simulator folder
      • Open a File Explorer and navigate to where the Simulator folder is
      • Navigate to Simulator/Assets/Materials/EnvironmentMaterials/
      • There should be a EnvironmentDamageAlbedo.png in this folder
      • Open the image, it should look like the image below
      • If the image cannot be opened, Git LFS was not installed before cloning the repository
        • Install Git LFS following step 4
        • In a terminal, navigate to the Simulator folder so that the terminal is similar to /Simulator$
        • git lfs pull
        • Check the image again

    Note: Please checkout the "release-*" branches or release tags for stable (ready features) and "master" branch for unstable (preview of work in progress).

  2. Run Unity Hub

    1. In the Projects tab, click Add and select the Simulator folder that was created by git clone in Step 5

    2. In the Projects tab, verify that the Simulator is using Unity Version 2020.3.3f1 from the dropdown

    3. Double-click the name of the project to launch Unity Editor

    Note: On Ubuntu 18.04, create an empty sample project before adding an existing project as mentioned in step 1.

  3. Open the Simulator menu from the top toolbar and select Build... to open the build window (shown below with a red outline)

  4. Select the target OS for the build using the Executable Platform dropdown menu

  5. Verify Build Simulator is checked for the Simulator to be built

  6. Select a folder that the simulator will be built in

  7. (Optional) Check Development Build to create a Development Build that includes debug symbols and enables the Profiler

  8. Click Build

Once the build process is complete a simulator executable will be available at the specified location.

Testing the simulator build top#

Follow these steps for a quick test of the simulator build. For a more complete guide please see the tutorial on running the simulator.

  1. (Ubuntu) Install the Vulkan userspace library

    sudo apt-get install libvulkan1

  2. Double-click the Simulator.exe that was built

  3. Click Open Browser, and login to the Web UI (you may need to sign up)

  4. You may be prompted to create a cluster for local simulations

  5. In the Store choose any maps and click Add to My Library

    • ex. the BorregasAve map

  6. Back in the Store choose one of the default vehicles such as the Lincoln2017Mkz and click Add to My Library

  7. In the Simulations tab, Add New simulation with the added map and the newly cloned vehicle:

    • Enter Simulation Name and Select Cluster then click Next.
    • Select the Random Traffic runtime template, choose the map from your library and select the Lincoln2017MKZ vehicle with the Keyboard Control sensor configuration then click Next.
    • Click Next on the Autopilot page and click Publish to create the simulation.

  8. Press the Run simulation button

  9. The Unity window should now show a vehicle in the built environment

Building assets top#

The simulator build tools allow developers to build assets as well as standalone simulator binaries. Assets refer to maps, vehicles, sensors, controllables, npcs, pedestrians and bridges. Asset bundles are built without needing to rebuild the entire simulator.

NOTE: AssetBundles built with one version of the simulator are NOT guaranteed to work with other versions of the simulator. Asset bundles will need to be re-created.

NOTE: NPCs and Pedestrians must be built locally for custom binaries. They must be added to AssetBundles folder to be loaded by the custom simulator binary.

Follow these steps to build assets:

  1. Place the source code for the asset the correct directory under Simulator/Assets/External for it to be discovered by the build tool. Based on the category the asset falls under it should be placed inside on of these subdirectories:

    • Environments
    • Vehicles
    • NPCs
    • Pedestrians
    • Sensors
    • Controllables
    • Bridges

    For example, to build the CubeTown map we would clone the repository into the Environments subdirectory.

  2. Press Ctrl + R to refresh assets (only needed if auto-refresh is disabled in the editor). The asset should now be detected and displayed in the build tool. In the case of this example, CubeTown will show up under Environments.

  3. Check the box next to any asset you wish to build and click the Build button at the bottom of the tool.

  4. Once the asset is built it will be available under the Simulator/AssetBundles in a subdirectory named after the category of the asset that was built. For this example, CubeTown will be at Simulator/AssetBundles/Environments/environment_CubeTown.

Using custom assets with the simulator binary top#

To use built assets with the simulator binary they must first be uploaded to the cloud. For more information on this see the Library guide.

Testing custom assets with the Unity editor top#

Custom assets can be tested with the Unity Editor by using the Developer Settings panel accessible from the Simulator menu located in the top toolbar. Only local assets are supported and JSON must be manually added so Developer Settings can look up sensor data.

Users can toggle Developer Debug Mode in Simulator drop down menu to load local asset classes at runtime to be able to access break point functionality. Be sure to toggle off when finished debugging.