Process Documentation

Communication

Our main channel of communication is through Discord. Please ensure Discord is installed from here https://discord.com/download and our server through this URL https://discord.gg/UrwDAfEb

Getting your Dev Environment Ready

The project uses Unity version 2021.3.5f1

1. Download Unity Hub https://unity3d.com/get-unity/download
2. Download Unity version 2021.3.5f1 https://unity3d.com/get-unity/download/archive
3. Download Visual Studio Community https://visualstudio.microsoft.com/downloads/
4. Download GitHub Desktop https://desktop.github.com/
5. Join the Trello board https://trello.com/invite/b/67pgTWlN/932058b60e288e1a70092cebd72c988f/kanban-board
6. Join the Github repository https://github.com/mattcoulter7/SWE40001-Exposure
7. Clone the repository https://github.com/mattcoulter7/SWE40001-Exposure.git

Before we open our code solution, we need to configure Unity preferences to use this Visual Studio, and ensure all .csproj files exist for IntelliSense to work.

1. Click on Edit > Preferences

2. Click External Tools on the left pane menu

3. Select Microsoft Visual Studio as your External Script Editor

4. Tick all of the options under Generate .csproj files for
   

5. Click Regenerate project files

We can now open the code solution in our IDE by Clicking on Assets > Open C# Project. This ensures the entire project is loaded, instead of just a single file!

Using Version Control

I suppose this is a good time to mention some standards around using the GitHub repo, considering that our team has grown to 9 people now. So far it has been pretty loose, and I think in order to maximize efficiency and quality control we shouldn't ever be pushing things directly into the main branch. I myself am guilty of this, pushing one off bug fixes and what not, but essentially main should always be build ready... so if you're doing dev it should be in your own branch for starters which can branch off of main. For example, the bug fixes I've done in the main branch should never have existed in the head branch in the first place! Once you've finished your dev, if it's not build ready, meaning it still needs internal testing to be done to ensure it doesn't break the game, don't push it to head yet. Once it is ready for play testing, then it can be pushed to main.

Some companies opt for multiple branches such as main > QA > DEV > dev branches > etc. however given how far we are into the project I'm not really feeling a whole repo restructure... so let's try stick to the above as best as possible

Creating a Branch

1. Open Github Desktop

2. Click on current Branch > New Branch
   

3. Name the branch the product backlog item name
   

4. Click create branch

5. Do devwork!

Merging Head with Branch

Once you have completed the backlog item fully, you need to merge your code with the head branch.

The first step is to merge head into your branch, so you can resolve merge conflicts, if any!

6. Click on current branch, then at the bottom of that pain, click on Choose a branch to merge into _CURRENT_BRANCH
   _

7. In the popup window, ensure head is selected, then click “Create a merge commit”
   

8. If the button is grayed out, it is already up to date, and you don’t need to merge anything.

9. Otherwise a new window will popup for handling merge conflicts if any.

   1. Handle the merge conflicts using VSCode,
      

   2. In VSCode, click on which the respective button for whichever version you want to keep
      

   3. Save the file

   4. Go back to GitHub Desktop

   5. Repeat for each of the remaining merge conflicts

   6. There should now be no merge conflicts showing
      

   7. Click Continue Merge

   8. Click Push Origin, this will now guarantee your branch is up to date with the head branch. \

\

Merging Branch into Master (HEAD)

10. Now this branch is ready to be merged into the head branch
11. To do so, click on Create Pull Request \

12. This will open a new browser window in GitHub
13. Add any further comments
14. Click on “Create Pull Request” \

15. Since we have handled the Merge conflicts already, there should be no merge conflicts now.
16. At this stage, you should inform me (Matt Coulter) that you have created a Pull Request, and I will go perform the final step, merging the pull request 9. MATT ONLY: Click Merge Pull Request \

10. Click Merge
11. Click Delete Branch \

Managing Tasks

Tony has put together a video on how we should be using Trello for task management. Please have a look here: https://youtu.be/me3qhfKPR5s

Building the game

Proper builds of this game need to be done on an Apple computer running MacOS. This is because of the rewind video overlay being encoded in an Apple format. Once the build has been done however, it should work on both Windows and Mac.

1. Open the Project Solution using Unity Hub \

2. Click on File > Build Settings (Ctrl + Shift + B) \

3. Ensure that all of the following scenes and options are ticked as per below
   

4. Save the build to a new folder in the Google Drive Build Directory here:
   Builds

5. Perform a play through of the playtest to ensure there are no bugs that have popped up due to being a release build.

Managing Prefabs

Due to the nature of how prefabs work, it can get rather complicated when we have prefabs inside of prefabs, and we need to decide which level we want to save variables to on the prefab itself. However, if done properly, it can allow us to efficiently make changes in every scene without needing to manually go through every scene.

Following the following rules should always ensure that prefabs are managed optimally.

1. If a value should apply to every single instance of the prefab, then save it to the prefab.
2. When saving a value to a prefab, save it to the lowest level possible.
   This is important as prefabs inside of prefabs allow you to save the value at either prefab level. \

3. If you see a blue indicated on a variable, it means the value hasn’t been saved to the prefab
4. Variables that reference something in the scene that aren’t a part of the same prefab cannot be saved to the prefab. A solution to this is to create a parent prefab that has both references as children. Then you will have the option to save the scene reference as an override to the parent prefab.
   Note that this has been done with the ‘Generic’ prefab, which has many children prefab that may reference eachother \

5. We should always try to avoid completely unpacking a prefab, then saving it as a new prefab. This would in turn give the prefab a new id, and any updates won’t apply to other instances of the old one.

Debugging the solution

Since we are using Visual Studio as our IDE for Unity, debugging the solution is very simple.

1. Open the project solution by clicking on Edit > Open C# Project
2. At the top of Visual Studio see the Run button labeled “Attach to Unity”. Click on this \

3. Go back to Unity and notice the message popup \

4. Click Enable Debugging for this session. This needs to be done once for every time UNity has been opened
5. Put a breakpoint in your code and notice that the debugger will hit it \

Generating Developer Documentation

Convention for writing the documentation

We have created a system for easy creation of developer docs which covers what all of the components, scripts and classes do. However it requires the developers to follow a convention when commenting on their code.

The Convention is called Annex D Documentation comments and full docs can be found here https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/documentation-comments

For the purpose of not overcomplicating the docs, we will not be commenting with this convention for anything that isn’t public. This is to reduce clutter and also because when someone is trying to play with your component, they most likely only care about what is public, as the other stuff isn’t modifiable.

Note that Visual Studio integrates this convention into their IDE, so hovering over variables will reveal the comment making it super friendly and consistent to all developers.

Public classes

Multiline summary of what the class is for

Public variables

Single line summary of what the variables is for

Public methods/functions

Comment the Summary and each of the params. If the function returns somethings, use <returns>Description of what is being returned</returns>

Generating the docs

1. Clone the repo https://github.com/mattcoulter7/AnnexDWikiGenerator.git
2. Open the repo folder on your machine \

3. Run the “run.bat”, or if you have issues, open a terminal in the repo folder and type “python main.py”
4. This will pop open a window to select a directory. This is where .cs will be extracted from to convert into documentation. Notes this walks through all of the subdirectories too! \

5. A new window should open up showing the export \

6. Feel free to use a website such as https://markdownlivepreview.com/ to preview what some of the files look like \

Saving the docs to the wiki

1. Clone the wiki repo https://github.com/mattcoulter7/SWE40001-Exposure.wiki.git
2. Note that wiki repos don’t clone from Github Desktop, so you will need to use a command prompt \

3. This will show all the pages as markdown files \

4. Now, we can load this repo into Github Desktop \

\

5. Paste the generated markdown files into the folder called Code-Documentation \

6. Commit and push changes using Github Desktop
7. Note that Github wikis only support subfolders of 1 depth only
8. You should now see the uploaded markdown documentation is on the repo! \

Developer Guidelines for Component Creation

Components

The #1 key thing to consider when building components is reusability. With every component that has been created for this project, it has been quite a generic component that has many use cases.

A good example of this would be with the Cinematic Bar System. There are 9 components that all work together for the system to work. One of which is called RectangleToRaycast. Whilst this script is used for aligning the cinematic bar rectangle with the camera, so that you only see the front face, it is also used for collision checking with the reticle. See below:

Extending on the idea of good code practices, please refer to the SOLID principles which should be followed as closely as possible.

Decoupling

An approach we have taken to minimizing the co-dependencies in our code is to utilize Unity’s UnityEvent class. Whilst all of the necessary functionality should be written in the code, additional things that don’t stop a mechanic from working such as sound, texture changing etc. should be use the UnityEvent class.

A simple example of this is playing a PuzzleSolved sound when the door is entered to complete the level. Note that this didn’t require any scripting, it was simply a configuration.