This guide will help you get setup for Unity development in Reality Roost

Installing Unity

1. Make a Unity account here if you don't have one already. Either your student or personal email works fine.
2. Sign up for the Unity Student Plan here.
   • Make sure you press the "Free Access: Post-Secondary" button, not the "Free Access: Secondary" one
     
3. Download Unity Hub from here. Unity Hub is Unity's management tool and launcher for Unity development.
4. Open Unity Hub and sign in to your Unity account.
5. Navigate to the Installs tab and click Install Editor. Install Unity 6.0.60f1.
   
   

Select the following modules:

6. Wait for Unity Editor to install. This can take up to 20 minutes.
7. Congratulations! Unity Hub, Unity Editor, and Visual Studio is now installed!

Unity Essentials

Unity Essentials is a course made by Unity designed to learn the basics of Unity. It takes a few hours to complete. If you haven't worked with Unity before, complete the course before working on Reality Roost.

I recommend you complete it in the Unity Editor (it will say this during the course), so you won't have to constantly switch between Unity and your browser. Text in the GroupMe if you need help completing it!

Pico Setup

Although we're developing Reality Roost to be usable for any headset with OpenXR, we're developing with Pico 4E headsets for now. We need to install the Pico Developer Center (PDC) and Pico OpenXR SDK.

1. Create a Pico account here. Either personal or school email works.

2. Download the PDC here. Also download the emulator later down in the same page. Install both of them.

Pico Dev Center

Once installed and signed into Pico Dev Center (PDC), plug in the Pico 4E if you have it. It should pop up in Device Manager like so

Do the following on the headset

• Settings → General → Update software (could take up to an hour)
• Settings → General → About → Software Version → Click 7 times to unlock developer mode
• Make sure USB debugging is enabled in dev tools menu

Downloading RR Github repo

Prereqs

• Git: here
• Git Large File Storage: here
• Github Desktop: here (easier to use than Git CLI, but if you're accustomed to CLI that works too).
• Get added to the Github repo: ask in GroupMe

Setting up repo locally

1. Open Git Bash, and navigate to the folder you want the project to be stored.
2. Clone the repo: git clone https://github.com/Izzy129/reality-roost.git
3. Open cloned repo: cd reality-roost
4. Install Git LFS into the repo: git lfs install
5. Pull Git LFS files: git lfs pull
6. Open Unity Hub > Projects > Add > Add from Disk > Select wherever you cloned the repo
   
7. Wait for Unity to setup the project, then open it.
8. Ensure that you're using the Windows build profile, not the Android build profile. Reality Roost is a PCVR application that uses SteamVR, as required by NVIDIA CloudXR.
   • To check, go to File>Build Profiles, and check if Windows is active like below. If not, click the Windows build profile and click the Switch Platform button
9. Congratulations! You've successfully setup the Reality Roost project in Unity :D

Setting up UnityYAMLMerge

Merge conflicts in Unity are a hassle to deal with. Thankfully, Unity provides a tool called UnityYAMLMerge that helps resolve these conflicts. You must set it up manually, since the location of the tool varies based on your machine.

1. Open Unity Hub, and go to the Installs tab. On the Unity 6000.0.60f1 install, press Manage>Show in Explorer.
   
2. In the folder that pops up, go to the Data>Tools folder.
3. Find the UnityYAMLMerge.exe file. Single press it, and press CTRL+Shift+C to copy the path to the executable.
4. With the path in your clipboard, go to the Reality Roost folder, and open the .git folder.
   .git folder not showing
   

   If you don't see the .git folder, then you have Show Hidden Folders disabled in File Explorer. Enable it like so:
   

5. In the .git folder, edit the config file (use notepad++ or notepad) and add the following lines. Replace <EDITED_PATH> with the path we copied earlier, edited like so:
   • Replace the double quotes in the pasted text with single quotes.
   • Replace the backslashes (\) with forward slashes (/).
   • Edited path Example:

"C:\Program Files\Unity\Hub\Editor\6000.0.60f1-x86_64\Editor\Data\Tools\UnityYAMLMerge.exe"

becomes

'C:/Program Files/Unity/Hub/Editor/6000.0.60f1-x86_64/Editor/Data/Tools/UnityYAMLMerge.exe'

Lines to paste into git config:

[merge]
    tool = unityyamlmerge

[mergetool "unityyamlmerge"]
    trustExitCode = false
    cmd = <EDITED_PATH> merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

7. Your final git config file should look something like this:

[core]
	repositoryformatversion = 0
	filemode = false
	bare = false
	logallrefupdates = true
	symlinks = false
	ignorecase = true
[lfs]
	repositoryformatversion = 0
	
[merge]
    tool = unityyamlmerge

[mergetool "unityyamlmerge"]
    trustExitCode = false
    cmd = 'C:/Program Files/Unity/Hub/Editor/6000.0.60f1-x86_64/Editor/Data/Tools/UnityYAMLMerge.exe' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"
[remote "origin"]
	url = https://github.com/Izzy129/reality-roost.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[lfs "https://github.com/Izzy129/reality-roost.git/info/lfs"]
	access = basic
[branch "main"]
	remote = origin
	merge = refs/heads/main

Github Desktop Setup

This step is optional, but recommended since using Github Desktop is easier for Unity development.

1. Open GitHub Desktop (you should've installed this earlier) and login.
2. Click the Add an existing repository from your local drive button, and find the folder you downloaded Reality Roost to.
   
3. Quick rundown of the UI. Fetch origin before pushing your change to ensure it doesn't cause merge conflicts after you push.
   

Pico Unity OpenXR SDK

To develop for Pico headsets, we need the Pico Unity OpenXR SDK in Unity.

I've installed this package in the Github repo's Unity project, so you may not need to install it yourself.
To check if it's already installed, check in package manager:

If it's not installed, follow the below steps to install it manually.

1. Open PDC and click Download Center → SDK Tab → Download the Pico Unity OpenXR SDK (NOT Pico Unity Integration SDK!!!)
   

2. Open the Reality Roost folder in file explorer
   
3. Press Start on the Pico Unity OpenXR SDK in the installed tab in PDC. This will reveal where the SDK is downloaded in a new file explorer window
   
4. Make a new folder in the opened explorer window called com.unity.xr.openxr.picoxr
5. Extract the contents of the .zip file to the com.unity.xr.openxr.picoxr folder.
6. Move the com.unity.xr.openxr.picoxr folder inside the Packages folder inside the Reality Roost folder
   
7. Check that the package is properly installed in Unity Package Manager

Development Workflow

You have successfully setup Reality Roost for local development!
For quick reference, below is a workflow for development

Workflow

1. Pull the latest changes with git pull (CLI) or Fetch origin (GUI) BEFORE OPENING UNITY
2. Do some work in Unity
3. Add your changes to working tree
   • Use git add file to add file to your commit, or git add . to add all changes. Or use GUI
4. Confirm your changes are correct with git status in CLI (or use GUI)
5. Commit your changes with git commit -m "Commit Description" or with GUI
6. Push your changes to GitHub in GUI or in CLI:git push

Making a new branch

Git Branches allow you to diverge from the main branch to work on something without affecting everyone (e.g. a new feature, testing new things that could break overall system).
I recommend using them for larger features.

1. Make a new branch in GUI or with CLI: git checkout -b my-branch
2. Do work and periodically commit changes with workflow above
3. When ready to merge your changes to the main branch, switch back to main branch in GUI or with CLI: git checkout main
4. Merge your changes to the main branch in GUI or in CLI: git merge my-branch
5. Push merged changes in GUI or in CLI: git push

Handling Merge Conflicts

A merge conflict occurs when 2 developers change the same file, and Git gets confused on which version to accept (esp if you modified the same lines of code). Git does its best to resolve these automatically, but you may need to resolve it manually.

1. Try using Unity's merge tool first: git mergetool
2. If that doesn't work, see which files conflict with git status
3. Manually resolve the conflicts in GitHub GUI

More Git Stuff

• We are using Git LFS (Large File Storage), an extension for Git that handles large binary files (e.g. player models, textures) efficiently.
  TODO MORE LFS STUFF → this is more of a 2nd semester thing for the creative team
• Packages installed from the Unity Package Manager are added to the Packages/manifest.json file. Then, when a developer pulls from Github, only the manifest.json is downloaded. Unity automatically installs packages listed in manifest.json.
• However, if you install a custom package (e.g. in Assets folder; likely by doing Assets → Import Package → Custom Package or downloaded from the Asset Store), you will need to commit them manually. TODO add instructions for committing Large packages w/LFS
• We should split the project into smaller scenes to prevent merge conflicts, as well as announce to other devs when we're working on a specific scene. Also use Git branches. TODO GIT BRANCH GUIDE