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 6000.0.60f1.
   
   

Select the following modules:

1. Wait for Unity Editor to install. This can take up to 20 minutes.
2. 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 2-3 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 or Zoom channel if you need help completing it!

Downloading RR Github repo

Prereqs

• Git: here
• Github Desktop: here
• Added as collaborator to the GitHub repo: ask Israel in GroupMe or Zoom
• Unity 6000.0.60f1 (done above)

Setting up repo locally

1. Open GitHub Desktop
2. Click the FIle button on top left. Then go to File>Clone Repository>URL and paste https://github.com/Izzy129/reality-roost.git. Also select where you want to store the repository locally.
   • Quick rundown of the UI. Fetch origin before pushing your change to ensure it doesn't cause merge conflicts after you push.
3. Change your current branch to your team's branch (Haptics/Rumbling Floor team = rumble-floor, Multiplayer Tracking/System Arch team = multiplayer-tracking). See branches for more details on branches.
4. Open Unity Hub > Projects > Add > Add from Disk > Select wherever you cloned the repo
   
5. Wait for Unity to setup the project, then open it.
6. Ensure that you're using the Windows build profile, not the Android build profile.
   • 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
7. Congratulations! You've successfully setup the Reality Roost project in Unity :D
8. Check that all packages imported successfully
   • Once Unity editor is open, go to Window>Package Manager>In Project and ensure that no packages have errors. If so contact Israel to fix this!!!

Setting up UnityYAMLMerge (optional, but helpful)

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.
I recommend setting it up now (makes potential merge conflicts easier later), but if you're having trouble setting it up, it is not required.

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'

Paste these lines in the bottom of ur git config:

[merge]
    tool = unityyamlmerge

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

7. Example (on my machine):

...	stuff already in config...

[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"

Meta Horizon Link + MQDH

Reality Roost will run using Meta Quest 3s headsets.
To use a headset on your computer (e.g., to test Reality Roost on a headset), you will need to install Meta Horizon Link. Note that this requires a somewhat powerful computer/laptop.

• If you don't have a compatible laptop/computer, you can use the lab computers in Duncan Hall room 2119. See instructions here (TODO) for lab computer usage

Follow the instructions on Meta site to connect headset to your computer and launch Link.
Once link is launched, change default OpenXR runtime to Oculus (TODO).
Then when you press Play in Unity editor, it will output to headset!

Development Workflow

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

Workflow

1. Choose your branch based on what team you're on
   • If on rumbling floor team, ensure you're on the rumble-floor branch
   • If on multiplayer tracking team, ensure you're on the multiplayer-tracking branch
   • See active branches here
2. Pull the latest changes with git pull (CLI) or Fetch origin (GUI)
   • This should be done BEFORE YOU OPEN THE PROJECT IN UNITY
   • but Unity will reload if you do it while it's open
3. Do some work in Unity
4. 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
5. Confirm your changes are added with git status in CLI (or use GUI)
6. Commit your changes with git commit -m "Commit Description" or with GUI
7. 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 the overall system, debugging, etc.).

We currently use git branches to separate work from Rumbling Floor team (rumble-floor branch), and Multiplayer Tracking team (multiplayer-tracking branch).
Then every 2 weeks we merge each other's work on the main branch (starting 2nd semester)
This ensures Reality Roost progress is synced up between the 2 teams.
Outside of team separation, I recommend using git branches for larger features.

Here's how to make a new branch from your current branch (either from rumble-floor or multiplayer-tracking branch)

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

Git is a very useful tool for software development. Here are some resources if wanna learn the fundamentals of git (not required here tho)

• https://missing.csail.mit.edu/2020/version-control/
• https://rogerdudler.github.io/git-guide/
• https://eagain.net/articles/git-for-computer-scientists/
• https://maciejb2k.github.io/no-bs-git/
• Plenty more online!

Handling Merge Conflicts

A merge conflict occurs when 2 developers change the same file, and Git gets confused on which version to accept (especially 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
   • If not a scene file → merge manually in GitHub GUI or a text editor (plenty of resources online for this)
   • if it's a conflict in a scene file, and unityYAMLMerge couldn't merge it, you must merge it manually in Unity
     • Let's say you have a scene Scene.unity that won't get pulled from remote branch because of a merge conflict. Let's fix that.
     • Make a copy of your current local scene file (name it like Scene_local.unity)
     • Try pulling remote version now (will download as Scene.unity)
     • Open both scenes in Unity (kinda something like below)
       • → see docs
     • Manually go through each GameObject to see what was added or removed or changed. Choose whether to add or remove said change in the Scene.unity file.
     • After manually merging like so, delete Scene_local.unity, and commit changes on Scene.unity and push to remote

More Git Stuff

• 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 package assets manually