Skip to content

Setup

Jump to bottom
Falko Galperin edited this page Sep 26, 2024 · 8 revisions

Setup for Development

Required Tools

You need Unity version that is stated in the README.md on our GitHub landing page and either Visual Studio Community Edition 2019 (Edition 2017 may work, too) or JetBrains Rider. We will generally use the latest minor version of Unity LTS. The exact minor version required may depend upon the branch.

To be able to download Unity, you may need to create a Unity account as a student or for personal use.

Cloning the repository

Note that we use Git LFS to store large files and external plugins. These LFS files are stored at the University of Bremen's GitLab instance in a private repository, since we cannot host the (paid) external plugins on this public GitHub repository.

To be able to clone SEE along with its LFS parts, set up your LFS Credentials for the GitLab SEE-LFS repository:

  • request access to the project if you cannot access it yet.
  • if you have 2FA active: find your token under Preferences → Generate Access Token and save it somewhere.

Then, you can clone the project:

git clone https://github.com/uni-bremen-agst/SEE

If you get asked for the GitLab LFS credentials, enter your GitLab username and password or access token.

Once you cloned the project successfully, the first thing you should do is to install our git hooks as follows:

On Linux run (at the root of the cloned repository):

./generateHook.sh

On Windows run:

./generateHook.bat

Unfortunately, this can't be automated (for security reasons) and hence has to be done manually.

If you ask git for a diff relating to files hosted on Git LFS, you will only see the LFS pointer. If you want to see the real difference, configure git as follows:

git config diff.lfs.textconv cat

Also, take a look at the Git-FAQ for additional information about Git (e.g., LFS or rebases).

Developing on Windows

You can install the required tools with the Windows package manager Chocolatey:

choco install unity --yes
choco install unity-hub --yes
choco install visualstudio2019community --yes

If you have a professional license, you may want to replace visualstudio2019community with visualstudio2019professional. The installation of Visual Studio may take quite some time. Be patient.

After installing Visual Studio, run Visual Studio Installer and press Modify. Select the package Game development with Unity and apply the changes with Modify. Run Visual Studio by pressing the Launch button at the main menu of Visual Studio Installer. Log in with your user credentials (your Microsoft account). If necessary, create a new account.

If you are using Visual Studio as an editor, it is highly recommended to install the RemoveTrailingWhitespaces extension, which removes all trailing whitespace upon saving a file.

Run Unity Hub and log in with your user credentials. If necessary, create a new account. Wait a few seconds until your Unity license was recognized or acquire a new one. Install the latest stable version of the Unity SDK. You'll find your installations at Installs. Deselect the module Microsoft Visual Studio Community 2019 if Visual Studio is already installed (e.g. with Chocolatey as described above).

Add SEE to your projects (Unity Hub: Projects => Add). Close Unity Hub and run Unity (which again starts Unity Hub). Open the previously added project and wait until Unity finished its setup.

In order to connect Unity with your Visual Studio installation, go to Edit => Preferences => External Tools and select Visual Studio 2019 (Community) at External Script Editor. Test your configuration by opening a .cs file.

It's also recommended to run the generateHook.bat script in the root folder (simply double-click it). This will create a pre-commit hook which will warn you in case you try to commit any drawn code cities by mistake.

Developing on Linux

Required Tools

This is pretty similar to the Required Tools on Windows. However, you also need the following dependencies:

  • FFMPEG
apt install ubuntu-restricted-extras  # on Ubuntu
pacman -S ffmpeg  # on Arch Linux
  • libvpx (technically optional, but can cause errors if missing)
apt install libvpx  # on Ubuntu
pacman -S libvpx  # on Arch Linux

The following exceptions to the Windows section also apply:

  1. Unity Hub must be installed as described in this guide
  2. The "Linux Build Support" module should be selected when installing Unity from Unity Hub.
  3. Because Visual Studio Community Edition is not available, a different IDE should be used. JetBrains Rider is a good alternative with many practical features (e.g. highlighting of performance critical sections) and compatibility to Visual Studio projects, but it's only free for students and faculty. Another option would be to use Visual Studio Code, an open-source IDE which is probably closest to Visual Studio Community Edition, though it hasn't been tested for this guide.

Additional tools for Rider

When using Rider you might need to install DotNet Code and Mono

apt install dotnet-sdk-6.0 mono-devel  # On Ubuntu
pacman -S dotnet-sdk mono  # On Arch Linux

Steps

  1. Install the correct Unity version as described in Required Tools. Note the path where Unity is installed by clicking on "Show in File Browser".

  2. Now it should already be possible to open and build the SEE project in Unity. If the menu items appear too small, see HiDPI scaling issues.

  3. It's also recommended to run the generateHook.sh script in the root folder. This will create a pre-commit hook which will warn you in case you try to commit any drawn code cities by mistake.

  4. Finally, Rider, VSCode or a similar IDE should be installed. This IDE should then be registered within the Unity editor at "Edit => Preferences => External Tools => External Script Editor".

If the IDE or Unity complains about missing .csproj files, see the section below.

Generating C# project files

Note

This is only required if the normal setup steps above did not already lead to the IDE integration working correctly.

To generate the C# project files, run the generateCSProj.sh script while you'in the SEE root directory (this can take quite a bit of time). If Unity is not in the PATH (by default, it isn't), the script must be run with the environment variable UNITY_PATH set to its location:

UNITY_PATH=<unity> ./generateCSProj.sh

Where <unity> is the path to the Unity executable, which can be found in the Unity Hub.

Hot Reload Plugin

The Hot Reload Plugin allows you to modify code while the game is running (except for fields and for members inside generic classes).

Settings should be set to the following (the settings window opens automatically the first time):

HiDPI scaling issues

In case a 4K screen (or similar) is used, menu elements may be too tiny. In this case the scaling must be adjusted by running Unity from the console as follows (where <unity> is the path to the Unity executable and <SEE> is the path to the SEE project):

GDK_SCALE=2 GDK_DPI_SCALE=0.5 <unity> -projectpath <SEE>

Scaling factors may need to be adjusted depending on your setup.

Clone this wiki locally