Skip to main content

Installation and Setup

Versions

We are using the following versions of Unity editor, mono, dotnet, Unity VSCode Extension, and C# VSCode extension:

You are free to use other code editors or IDE such as Neovim, Visual Studio (easy choice but official support will be dropped by Microsoft for macOS users in 2024) or Monodevelop. Please enable intellisense regardless of which IDE/code editor you are using.

Please install all of the above tools before proceeding.

Recommendation​

macOS or Linux distros

macOS users are recommended to use Visual Studio Code with the Unity Extension. See Aug 2023 update.

Windows

Windows users are recommended to use Visual Studio instead of VSC. It will be the default recommended version when you install Unity from Unity Hub.

Basic Setup​

note

Download the starter asset from your course handout, under "Class Calendar" heading, Week 1 Lab Session row. We do not own any of the assets distributed in this lab, they can all be freely obtained from the Internet, credits are all indicated in the individual sheet/resources.

This is a starter asset for this week that you can import to your project and complete the lab. It contains all required images, sound files, etc so we can save time without having to search for all these assets.

Create New Project​

Using UnityHub, create a new 2D project:

Then, import the asset mario-lab.unitypackage you downloaded from the Course Handout :

You should see a list of assets on the Project tab in the Unity editor.

Setting up VSCode​

Check that dotnet and mono are installed properly:


If you're using VSCode, ensure that you install the C# VSCode extension (notice the version, to gain access to this old version, click the arrow beside Uninstall and select Install Another Version):


Then add the following to your VSCode settings.json:

[other path]/Code/Usersettings.json
{
  // ... other settings
  "omnisharp.projectLoadTimeout": 60,

  // only macOS users need mono, Windows users ignore this
  "omnisharp.monoPath": "/Library/Frameworks/Mono.framework/Versions/Current", // change this accordingly to where mono is installed

  // change this accordingly to where dotnet is installed
  "omnisharp.dotnetPath": "/usr/local/share/dotnet/dotnet",

  "omnisharp.useModernNet": false,
  "omnisharp.useGlobalMono": "always",

  // for format on save (automatically)
  "editor.formatOnSave": true,
  "[csharp]": {
    "editor.defaultFormatter": "ms-dotnettools.csharp"
  }
}

You might want to ignore irrelevant files while opening your project with VSCode. Add the following setting in your project workspace:

.vscode/settings.json
    // Configure glob patterns for excluding files and folders.
    "files.exclude": {
        "**/.git": true,
        "**/.DS_Store": true,
        "**/*.meta": true,
        "**/*.*.meta": true,
        "**/*.unity": true,
        "**/*.unityproj": true,
        "**/*.mat": true,
        "**/*.fbx": true,
        "**/*.FBX": true,
        "**/*.tga": true,
        "**/*.cubemap": true,
        "**/*.prefab": true,
        "**/Library": true,
        "**/ProjectSettings": true,
        "**/Temp": true
    }

You also need to install Visual Studio Code Editor under Window >> Package Manager in Unity:

And then link VSCode in External Tools tab under Unity's Preferences:


tip

The official support for Unity in VSCode has been dropped, so it might be a bit wonky sometimes (VSCode can't find mono, etc). Try completely quitting VSCode (not just closing it) and reopening the files.

Update Aug 2023​

caution

If the above setting with VSCode does not work for you, that's because Visual Studio Code Editor package is no longer actively maintained by Unity, and you might just be unlucky.

Go to Window >> Package Manager and install Visual Studio Editor instead:

Go to Unity >> Settings and set Visual Studio Code as your external tools:

Then, go to Visual Studio Code and install the C# extension (v2.0.X or above is acceptable):

Also install Unity extension (at the time of this writing, it's under preview):

Go to your VSCode UI settings and set dotnet path as the path of your system's dotnet (the one you get when typing which dotnet in the terminal, we assume on UNIX-like OS):

Also update the dotnet sdk path, you can list your sdk as follows:

And update it in VSCode settings:

Completely quit and restart VSCode and reopen your scripts via Unity. Your intellisense should be good to go:

Finally, ensure settings.json in VSCode has the following setting regarding omnisharp:

  "omnisharp.projectLoadTimeout": 60,

  // macOS users: since useModernNet is set to true, theres no need to set monoPath anymore
  "omnisharp.useModernNet": true,
info

Please contact your TA or instructor if you stil cant get your intellisense working, or use another IDE/editor like Visual Studio. Do not program blind for the rest of the semester.

Completely Quit and Restart VSCode​

If you find the following error:

Please restart VSCode completely and reopen the script. This is due to the fact that you close VSCode window and it's still running (in the background), and yet you reopen the scripts from Unity. There will be a conflict in the language server.

You should reopen your VSCode window from VSCode itself:

Housekeeping​

To work better, we need to set up the UI in a more comfortable way. We need at least the following windows:

  1. Inspector (to have an overview of all elements in a GameObject), set on the right hand side,
  2. Game Hierarchy (to have an overview of all GameObjects in the scene), set on the left hand side
  3. Scene Editor (to add GameObjects and place them), set on the middle of the screen
  4. Then usually we also have the following windows (kept as tabs):
    1. Project (to show all the files),
    2. Console (to see printed output)
    3. Game Screen (to test your game)

Then, go to Scenes folder and rename your scene in a way that it makes more sense than “SampleScene”. Create two more folders called “Scripts”, and “Prefabs” under "Assets". We will learn about them soon.

Here's a suggested layout:

Using git​

You can use git as per normal and should not need to touch Git LFS for making this short, 15-minute game. Don't forget to add unity-specific .gitignore file.

Here's one suggestion, taken from this source:

.gitignore
# This .gitignore file should be placed at the root of your Unity project directory
#
# Get latest from https://github.com/github/gitignore/blob/main/Unity.gitignore
#

# for vscode
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
!.vscode/*.code-snippets

# Local History for Visual Studio Code
.history/

# Built Visual Studio Code Extensions
*.vsix

/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/

# MemoryCaptures can get excessive in size.
# They also could contain extremely sensitive data
/[Mm]emoryCaptures/

# Recordings can get excessive in size
/[Rr]ecordings/

# Uncomment this line if you wish to ignore the asset store tools plugin
# /[Aa]ssets/AssetStoreTools*

# Autogenerated Jetbrains Rider plugin
/[Aa]ssets/Plugins/Editor/JetBrains*

# Visual Studio cache directory
.vs/

# Gradle cache directory
.gradle/

# Autogenerated VS/MD/Consulo solution and project files
ExportedObj/
.consulo/
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
*.VC.db

# Unity3D generated meta files
*.pidb.meta
*.pdb.meta
*.mdb.meta

# Unity3D generated file on crash reports
sysinfo.txt

# Builds
*.apk
*.aab
*.unitypackage
*.app

# Crashlytics generated file
crashlytics-build.properties

# Packed Addressables
/[Aa]ssets/[Aa]ddressable[Aa]ssets[Dd]ata/*/*.bin*

# Temporary auto-generated Android Assets
/[Aa]ssets/[Ss]treamingAssets/aa.meta
/[Aa]ssets/[Ss]treamingAssets/aa/*

You can read more about how to use Git from this wonderful article.

Force Text Asset Serialization​

Go to Edit >> Project Settings in Unity, and set Asset Serialization Mode under Editor tab into Force Text:

Git LFS​

Git LFS should be used only if you need to version large files. Normal free-tier GitHub repository can hold as much as 5GB, but 1GB is the recommended size. You can push objects not more than 100MB in size. A typical 50.033 project is far less than 1GB in total, given that you use proper .gitignore file.

If you still want to use Git LFS because you have complex VFX or SFX, then give this article a read. Do note the billing information about Git LFS (there's a limit on bandwidth, not just size).