Standalone Application Customization

Overview

The RIDE standalone application features a collection of example scenes that display key capabilities of the API. This application can be built locally with custom scenes added to the existing LevelSelect scene Demo menu list for your own demonstration purposes. 

This tutorial is geared toward developers and researchers working with the RIDE project source and new to the Unity development platform. Topics covered include basic scene creation, script modifications, adjusting scene parameters and building a standalone executable for desktop systems.

Page Contents

LevelSelect_Main

Requirements

Users new to RIDE and Unity will want to ensure their development environment is fully setup before continuing further. If already setup, users may skip to the LevelSelect modification section. 

Prerequisites

  • Unity Hub
  • Unity version 2020.2.3f1
  • RIDE project source (requires minimum 30 GB of free disk space)

Recommendations

  • Version control software (Subversion client TortiseSVN or similar)
  • Text or source code editor (Notepad++ or similar)

Unity Hub Installation

The Unity Hub utility controls which versions of the platform are installed on the local machine.

  1. Navigate to https://unity3d.com/get-unity/download
  2. Click “Download Unity Hub” button.
  3. Download and install Unity Hub.
  4. Run the application, and proceed to create an account or login.
  5. Inside Preferences, License Management, choose Activate New License option.
  6. Complete License Agreement.   

Refrain from acquiring any version of Unity from the Hub for the moment. See next section for Unity installation steps.

Unity v2020.2.3f1 Installation Using runUnity.bat 

With Unity Hub now installed, locate the runUnity.bat file at the top level of the RIDE repository; certain users will find it under \trunk. When first initialized, this process calls Unity Hub for a “headless” (background) automatic installation of the proper version of the Unity editor and modules for the project, v2020.2.3f1. (Remain connected to the Internet during the next set of steps.) 

  1. Recommend for first-time launch with runUnity.bat that it’s initialized through the command line; using this method displays the status of the process and any errors.
  2. On Windows, open File Explorer to the directory with runUnity.bat.
  3. Click in the address bar and clear the path text.
  4. Type “cmd” in the field and press Enter; a command prompt will appear with the current directory path.
  5. Type “runUnity” and press Enter.
  6. Wait for the “headless” process to download and install Unity v2020.2.3f1 via Unity Hub; this can take a while.
  7. When complete, Unity will initialize and begin to ingest the project files and build a local library; this too can take a while.
  8. After the local library creation finishes, the Unity application will open to the RIDE project.
  9. If successful, subsequent launches of the project can be done with runUnity.bat directly, no need to use the command line.

Important

Always use runUnity.bat to open the RIDE Unity development environment. This will ensure you are using the correct version of Unity every time. Do not launch the RIDE project through Unity Hub.

 

Tip

If the “headless” installation process fails, v2020.2.3f1 can be acquired through the Unity Archive page, https://unity3d.com/get-unity/download/archive

  1. Select the option from the page to download and install v2020.2.3f1 through Unity Hub; installation can take a while.
  2. Note, Unity Hub will prompt for a license if not already present; create an account or login, and then complete the License Agreement process.
  3. After installation completes, relaunch runUnity.bat in order to initialize Unity and create the local project library; this too can take a while.
  4. Once the local library creation finishes, the Unity application will open to the RIDE project.

If the “headless” installation process fails, v2020.2.3f1 can be acquired through the Unity Archive page, https://unity3d.com/get-unity/download/archive

RIDE Source Code

External organizations may request access to the RIDE source code via the website, https://ride.ict.usc.edu

  1. Once approved, download the source code package to a data drive on the local machine with at minimum 30 GB of free space.
  2. Unzip the package contents; recommend placing them inside of a local “Projects” directory.

VCS Subversion Client – TortiseSVN

Version control software (VCS) allows the tracking of individual file changes inside of a code base. In the event a “breaking” code change is committed, these changes can be easily compared against prior versions of the file(s) using the VCS client, and the file(s) reverted to another “known good” version.

  1. Navigate to https://tortoisesvn.net/
  2. Download, install and configure latest TortiseSVN Subversion client
  3. Note, TortiseSVN is Windows only; alternative Subversion clients exist for macOS and Linux 

Text or Source Code Editor – Notepad++

Advanced text editors tailored to script and source code will help avoid mistakes that can occur when editing these types of files in a standard text editor or word processor.

  1. Navigate to https://notepad-plus-plus.org/
  2. Download and install latest Notepad++
  3. Note, Notepad++ is Windows only; suitable alternatives exist for macOS and Linux 

Achievement Unlocked!

Now that all of the development environment requirements have been met, the RIDE project and LevelSelect scene can be modified as desired. See next section for instruction.

 

New Scene Creation for LevelSelect Scene Demos Listing 

How to create a basic test scene compatible with LevelSelect scene Demos listing

If new to Unity and RIDE toolset, recommend first creating the most basic test scene that can launch from, and return to, the LevelSelect scene Demos listing. 

  1. Unity editor, File > New Scene
  2. File > Save As…
  3. Within the project directory, navigate to /Assets/Scenes
  4. Create a new sub-folder, giving it the same name as the new scene that will be saved. (Ex. “ExampleTest”)
  5. Open this new sub-folder.
  6. Name the scene the same as the sub-folder and click Save.
  7. In Project panel, search field, type “ridebase”
  8. Double-click this file (RideBase.cs) to open it in the system default text editor. Recommend Notepad++ or other source code editor.
  9. Copy the first 31 lines of file text.
  10. Create new file in text editor of choice.
  11. Paste 31 lines into new file.
  12. Modify the script to appear exactly as the provided code block example; however, replace the “public class” value of “ExampleTest” with the name of your newly saved scene. This new class is derived from “RideBase” which enables RIDE systems, including load/exit of the individual scene within the LevelSelect scene.  

    ExampleTest.cs
using UnityEngine;
using Ride.Networking;
using Ride.WorldState;
using Ride.UI;
using Ride.IO;
using Ride;
using System;

namespace Ride.Examples
{
    public class ExampleTest : RideBase
    {
	}
} 
  1. Save this file to the same sub-folder inside of /Assets/Scenes named after the new scene, which also contains the scene file itself.
  2. Unity editor, in Hierarchy panel, right-click and choose Create Empty from the context menu.
  3. Rename object to match the scene name.
  4. Ensure object selected.
  5. Inspector panel, click Add Component button.
  6. In the search field, type the name of newly saved script, which matches the object/scene name.
  7. Click the script result to add it to the object as a component.
  8. Save scene.
  9. Verify the scene works by clicking the Play button in the top-center of the Unity toolbar to compile and launch the scene.
  10. Open the Console panel to watch for any errors/warnings. If an error appears, double-check the content of the newly saved script file.
  11. If the scene runs successfully, stop the editor run-time mode by clicking the Play button again.

Achievement Unlocked!

Now that the test scene is compatible with the LevelSelect scene, it can be further developed or added to the LevelSelect scene Demos listing. See next section for instruction.

Customize the LevelSelect Scene Demos Listing 


Adding a new section to the Demos listing

  1. Unity editor, open LevelSelect scene: Assets/Scenes/LevelSelect/LevelSelect.unity
  2. In Hierarchy, select LevelSelect object.
  3. Inspector panel, expand Sections property.
  4. Increment Size value by one and press Enter/Tab key.
  5. A new sub-property representing the new section appears. This section is a duplicate of the previous.
  6. Expand the sub-property of this new section.
  7. Section Name field, replace the current name with the desired name and press Enter/Tab.
  8. The new name appears as the field label.

Editing the number of scenes in the new section

  1. As mentioned in the last set of instructions, any new section is a duplicate of the previous, containing all the same scene entries.
  2. Change the number of scenes in the new section by expanding Scene Descriptions sub-property, and then modify the Size field to the desired value and press Enter/Tab.
  3. The entries below the field will increase or decrease accordingly.

Modifying the scenes in the new section

  1. As mentioned in the last set of instructions, the new section contains duplicate scenes from the previous section of the listing.
  2. Under Scene Descriptions sub-property, expand the first scene entry to reveal its properties:
    • Name: Enter the name of the desired scene exactly as it appears in the /Assets folder. This name will display on a button in the listing at run-time.
    • Capabilities: Select any items from the dropdown which apply to the desired scene. At run-time, these entries display tool-tips with more information.  
    • Related Projects: Select any items from the dropdown which apply to the desired scene. These also have tool-tips and hotlink to that respective project’s documentation. 
    • Description: Used to detail the purpose of the scene and its intended function.
    • Instructions: List any commands and operations the user may need to perform while the scene is active. Note, feature incomplete; text currently does not display at run-time.
  3. Modify the remaining Scene Description entries as desired.
  4. Recommend at this point saving any changes to the now customized LevelSelect scene.

Important

New scenes must be added to the Unity project’s Build Settings list in order to then appear in the LevelSelect scene Demos listing at run-time. See next section for instruction.

 

Adding new scenes to Build Settings

Any new scenes included as Scene Description entries must also be added to the Unity project’s Build Settings list in order to appear in the LevelSelect scene Demos listing at run-time.

  1. Unity editor, open the desired scene intended for inclusion in the LevelSelect scene Demos listing. Most scenes are found in the /Assets/Scenes folder.
  2. Choose File > Build Settings…
  3. Under “Scenes in Build” section, click “Add Open Scenes” button.
  4. The new scene appears at the bottom of the list.
  5. Repeat steps for additional scenes.
  6. Click X to close the Build Settings dialog.
  7. Note, Unity editor automatically saves changes to Build Settings.

Verifying new scenes in Demos listing at run-time

After including any desired new scenes to the Build Settings and ensuring their respective Scene Descriptions entries are complete, verify the scenes appear as expected in the Demos listing at run-time.

  1. Unity editor, open LevelSelect scene: Assets/Scenes/LevelSelect/LevelSelect.unity
  2. Click the Play button in the top-center of the Game panel to compile and launch the scene.
  3. From the LevelSelect main menu, select Demos.
  4. Scroll to the bottom of the listing to find the new scenes.
  5. Click the button for each new scene and verify the content in the details column to the right.
  6. Click the Play button to launch the scene.
  7. If the scene runs as intended, press the Esc key to return to the listing and launch any other new scenes for verification.
  8. Stop the editor run-time mode by clicking the Game panel Play button again.

Customize Capabilities and Projects Options

How to create new Capabilities entries inside dropdown of Scene Descriptions sub-properties

  1. Unity editor, open LevelSelect scene: Assets/Scenes/LevelSelect/LevelSelect.unity
  2. In Hierarchy, select LevelSelect object.
  3. Inspector panel, find the Capabilities File entry in the various dependency entries of the script component.
  4. Click the Capabilities script object in the corresponding field.
  5. In the Project panel, the Capabilities source file will highlight.
  6. Double-click this file (Capabilities.json) to open it in the system default text editor. Recommend Notepad++ or other source code editor.
  7. Highlight last entry from open to closed ellipsis.
  8. Copy entry text.
  9. Move cursor after closed ellipsis for copied entry, add a comma.
  10. Next, press Enter to create a new line with the cursor indented, matching the previous entry.
  11. Paste entry text.
  12. Increment “$id” value by one.
  13. Modify “name” text within quotes to the desired capability label.
  14. Modify “description” text within quotes to describe the capability in brief.
  15. Ensure open and closed ellipsis align with previous entries and that final closed ellipsis not followed by a comma.

    Capabilities.json
  },
  {
    "$id": "15",
    "name": "Test Capability",
    "description": "Test Capabilities option",
  }
] 
  1. Save changes to file.
  2. Allow Unity editor to reload this source file before modifying any scenes.

How to a create new Related Projects entries inside dropdown of Scene Descriptions sub-properties

  1. Unity editor, open LevelSelect scene: Assets/Scenes/LevelSelect/LevelSelect.unity
  2. In Hierarchy, select LevelSelect object.
  3. Inspector panel, find the Projects File entry in the various dependency entries of the script component.
  4. Click the Projects script object in the corresponding field.
  5. In the Project panel, the Projects source file will highlight.
  6. Double-click this file (Projects.json) open it in the system default text editor. Recommend Notepad++ or other source code editor.
  7. Highlight last entry from open to closed ellipsis. See snippet.
  8. Copy entry text.
  9. Move cursor after closed ellipsis for copied entry, add a comma.
  10. Next, press Enter to create a new line with the cursor indented, matching the previous entry.
  11. Paste entry text.
  12. Increment “$id” value by one.
  13. Modify “name” text within quotes to the desired project label.
  14. Modify “acronym” text within quotes to the desired project acronym.
  15. Modify “description” text within quotes to describe the project in brief.
  16. Modify “url” address within quotes to the corresponding project website.
  17. Ensure open and closed ellipsis align with previous entries and that final closed ellipsis not followed by a comma.

    Projects.json
 },
  {
    "$id": "11",
    "name": "Test Project",
    "acronym": "TEST",
    "description": "Test Project option.",
    "url": "https://ict.usc.edu/"
  }
] 
  1. Save changes to file.
  2. Allow Unity editor to reload this source file before modifying any scenes.

Important

New Capabilities and Related Projects additions in their respective source files must also be referenced within RideDefines.cs in order to then appear as options inside the Capabilities and Integrated Projects dropdowns of the Scene Descriptions sub-properties. See next section for instruction.

 

How to add new Capabilities and Related Projects dropdown entries inside Scene Descriptions sub-properties

  1. Unity editor, open LevelSelect scene: Assets/Scenes/LevelSelect/LevelSelect.unity
  2. In Project panel, search field, type “RideDefines”
  3. Double-click this file (RideDefines.cs) to open it in the system default text editor. Recommend Notepad++ or other source code editor.
  4. Add Capabilities entry:
    • Under “public enum CapabilityFlags” section, highlight last entry from start of label to end comma.
    • Copy entry text.
    • Move cursor after comma for copied entry.
    • Press Enter to create a new line with the cursor indented, matching the previous entry.
    • Paste entry text.
    • Modify label text to match the “name” text for the corresponding entry within the previously edited, Capabilities.json source file. Note, any spaces must be replaced by underscores.
    • Increment the ending numerical value representing the entry by one.
    • Save changes to file.
       
      RideDefines.cs
using System;
using System.Collections.Generic;

namespace Ride
{
    [Flags]
    public enum CapabilityFlags
    {
        Networking = 1 << 0,
        OWT_Loading = 1 << 1,
        OWT_Destruction = 1 << 2,
        OWT_STPLS = 1 << 3, 
        Vehicle_Physics = 1 << 4,
        Agent_Behaviours = 1 << 5,
        Autonomous_Agents =  1 << 6,
        Voice_Communication = 1 << 7,
        Speech_Recognition = 1 << 8,
        Generative_Programming = 1 << 9,
        Performance = 1 << 10,
        Scalability = 1 << 11,
        Natural_Language_Processing = 1 << 12,
        Audio_Visual_Sensing = 1 << 13,
		Test_Capability = 1 << 14,
    } 
 
  1. Add Project entry:
    • Under “public enum ProjectFlags” section, highlight last entry from start of label to end comma.
    • Copy entry text.
    • Move cursor after comma for copied entry.
    • Press Enter to create a new line with the cursor indented, matching the previous entry.
    • Paste entry text.
    • Modify label text to match the “acronym” text for the corresponding entry within the previously edited, Projects.json source file.
    • Increment the ending numerical value representing the entry by one.
    • Save changes to file.
       
      RideDefines.cs
    [Flags]
    public enum ProjectFlags
    {
        TSS = 1 << 0,
        OWT = 1 << 1,
        HA3T = 1 << 2,
        MSELI = 1 << 3,
        POL = 1 << 4,
        SLATS = 1 << 5,
        SCOPE = 1 << 6,
        NLP = 1 << 7,
        VGL = 1 << 8,
        IVR = 1 << 9,
		TEST = 1 << 10,
    } 
  1. Allow Unity editor to reload this source file before modifying any scenes.

Verifying new Capabilities and Related Projects dropdown entries inside Scene Descriptions sub-properties

After including any desired additions to Capabilities.json, Projects.json and entries to RideDefines.cs, verify the entries appear as expected inside their respective dropdowns of the Scene Descriptions sub-properties.

  1. Unity editor, open LevelSelect scene: Assets/Scenes/LevelSelect/LevelSelect.unity
  2. In Hierarchy, select LevelSelect object.
  3. Find the Section properties, and expand the Scene Description sub-group.
  4. Expand properties of any scene entry.
  5. Click Capabilities dropdown.
  6. Select new entry at bottom of list.
  7. Click Related Projects dropdown.
  8. Select new entry at bottom of list.
  9. Save scene.
  10. Verify the scene customization works by clicking the Play button in the top-center of the Unity toolbar to compile and launch the scene.
  11. From the LevelSelect main menu, select Demos.
  12. Scroll to the bottom of the listing to find the new scenes.
  13. Click the button for each new scene and verify the content in the details column to the right.
  14. Open the Console panel to watch for any errors/warnings. If an error appears, double-check the content of the script files.
  15. If Capabilities and Integrated Projects details appear as intended, stop the editor run-time mode by clicking the Game panel Play button again.

Achievement Unlocked!

On account of the LevelSelect scene now successfully customized with new content, a new version of the standalone application can be built locally for demonstration. See next section for instruction.

 

Building and Running a Local Standalone Application

Configuring LevelSelect scene in Build Settings

Unity provides various options to configure a standalone application prior to building locally.

  1. Unity editor, choose File > Build Settings…
  2. Under “Scenes in Build” ensure all scenes desired for the standalone application are checked.
  3. Platform options, use default: PC, Mac & Linux Standalone.
  4. Ensure Architecture property set to x86_64.
  5. Note, additional properties are linked from the “Player Settings…” button.

Building and running local LevelSelect standalone application

  1. When ready to build the local standalone application, return to File > Build Settings…
  2. Click Build button.
  3. In the build location window, navigate to one level outside of the current project folder. Depending on local file structure, this could be outside of /RideUnity or /trunk.
  4. Create a new folder, and name it “bin”.
  5. Open “bin” and create a sub-folder with a unique name.
  6. Ensure this folder is selected, and then click Select Folder.
  7. Unity build process will initialize, and display a “Building Player” dialog.
  8. Once finished, the /bin unique sub-folder will open in a new window.
  9. Run the RIDE executable.
  10. Verify the RIDE main menu appears, and any selected scene from the Demos listing loads as expected.

Important

If distributing the local executable within your organization, compress (zip) the entire contents of the unique sub-folder. The executable is dependent upon the various resources within it.

 

Unity Reference and Training

Resources to build familiarity with the Unity editor and application development.

Unity Manual, Version 2020.2

Unity Scripting API, Version 2020.2

Unity Learn Premium, Getting Started With Unity

Unity Learn Premium, Tutorials

Scroll Up