UNITE

Get started

Install UNITE and run your first study. By the end you will have a working delayed-teleoperation study running in Unity, and you will have made it your own by changing a single module.

Installation

To run UNITE locally you need:

  • Unity Hub and Unity 6000.3.15f1 (Unity 6) — the exact version recorded in ProjectSettings/ProjectVersion.txt.
  • Git and Git LFS — the project stores its 3D models, textures, and other binary assets with LFS.

Install Git LFS first. The 3D models, textures, and other binary assets are stored with Git LFS, so git lfs install must run before you clone, or the asset files arrive as small text pointers instead of real meshes.

Install Git and Git LFS

With Homebrew installed, run:

bash 
brew install git git-lfs

Alternatively, install Git with Apple's Command Line Tools using xcode-select --install, then install Git LFS from git-lfs.com.

Clone the repository

Run these commands after installing Git LFS:

bash 
git lfs install
git clone https://github.com/UHasselt-DigitalFutureLab/unite-teleoperation.git
cd unite-teleoperation
git lfs pull

git lfs pull is safe after a fresh clone and makes the asset-download step explicit. If you already cloned the repository before installing Git LFS, run the same commands from inside the cloned folder, starting with git lfs install and git lfs pull.

Open the resulting folder in Unity Hub: choose Add → Add project from disk, select the cloned folder, and open it with Unity 6000.3.15f1. Library/, Logs/, and the IDE project files are regenerated by Unity on first open and are intentionally not tracked.

Quick start

This walkthrough takes you from the freshly opened project to a running study, and then to your own variation of it by changing a single module.

  1. Open a study scene. In the Project window, open Assets/UNITE/Demo/every-move-you-make/Scenes/condition-baseline.unity. It is the bundled Every Move You Make demo: a TurtleBot3 Waffle Pi rover on a lunar-analog course under a fixed 2.56 s uplink delay, with an operator display, a task, and logging already wired up.
  2. Press Play and drive. Hit Play and drive the rover from the keyboard: the Up / Down arrow keys to drive forward or backward, and the Left / Right arrow keys to turn. Notice the lag between your keypress and what you see, which is the 2.56 s delay the study applies.
  3. See how the study is assembled. Select the TeleroboticsAgent GameObject in the Hierarchy. Its Inspector shows the study's ID and Update Rate, plus the connected input, mapping, communication, vehicle, observation, presentation, task, and logging modules: input read by the keyboard provider, mapped to wheel velocities, delayed by Uplink Communication, applied by the TurtleBot3 Vehicle / Robot Model, and sent back through the downlink modules to Operator Presentation.
  4. Make it your own: change the delay. The delay lives in a communication-condition asset, Configurations/Fixed-Uplink-2560ms, that the Uplink Communication module references. Before editing, save a copy of the scene under a new name, duplicate its shared configuration assets, and assign the copies so the bundled conditions stay unchanged. Edit the copied delay asset and press Play again: the same study now runs under your condition, with nothing else changed.
  5. Save it as a shareable study. Save the new scene and its configuration assets, then commit them together. That scene is your study: a collaborator opens it and runs exactly what you ran.

The core idea. You never rebuild the apparatus; you reconfigure it. Every study is the same loop of modules with different choices plugged in, which is what makes studies reproducible and comparable.

Other conditions and validation

The same Scenes folder contains Network, Path, and Envelope. Exit Play Mode before opening another condition. Baseline shows video only; Network adds command timing; Path and Envelope add predicted motion.

Before sharing a modified study, run the EditMode tests in Unity's Test Runner and smoke-test all four scenes, including trial termination and CSV output. For a standalone build, make the desired condition the first enabled scene in Build Profiles. There is no runtime condition selector.

Next steps

Core concepts Understand uplink, downlink, and where each module sits. Module reference What every module does and how to configure or replace it.

Optional: collaborating with Git

Smart Merge is not required to clone, open, run, or commit UNITE. It can reduce conflicts when branches change the same Unity scene or prefab by merging their Unity structure, rather than only lines of text. Conflicts can still require manual resolution; always review the result and open the affected scenes or prefabs in Unity before committing.

The repository's .gitattributes selects unityyamlmerge for .unity and .prefab files only. Other text assets use normal Git text merging; binary assets continue to use Git LFS.

To enable it, run the appropriate block below from the cloned repository. These examples use Unity Hub's default installation location for Unity 6000.3.15f1. If yours differs, edit unity_merge first. The block checks that the tool exists before configuring this clone, and replaces an earlier driver setting for this repository.

On Windows, use Git Bash (installed with Git for Windows), not PowerShell or Command Prompt. On macOS, use Terminal.

Windows (Git Bash)

bash 
unity_merge='C:/Program Files/Unity/Hub/Editor/6000.3.15f1/Editor/Data/Tools/UnityYAMLMerge.exe'
if [ -f "$unity_merge" ]; then
  git config --local merge.unityyamlmerge.name "Unity Smart Merge"
  git config --local merge.unityyamlmerge.driver "\"$unity_merge\" merge -p \"%O\" \"%B\" \"%A\" \"%A\""
else
  printf '%s\n' 'UnityYAMLMerge not found. Correct unity_merge and run this block again.'
fi

macOS (Terminal)

bash 
unity_merge='/Applications/Unity/Hub/Editor/6000.3.15f1/Unity.app/Contents/Helpers/UnityYAMLMerge'
if [ -f "$unity_merge" ]; then
  git config --local merge.unityyamlmerge.name "Unity Smart Merge"
  git config --local merge.unityyamlmerge.driver "\"$unity_merge\" merge -p \"%O\" \"%B\" \"%A\" \"%A\""
else
  printf '%s\n' 'UnityYAMLMerge not found. Correct unity_merge and run this block again.'
fi

On Linux, use the same shell block with the path to Editor/Data/Tools/UnityYAMLMerge inside your Unity installation. Repeat setup for each clone and update the path if you move or replace the Unity installation. See Unity's Smart Merge documentation for background and conflict-resolution options.