# Unity Monorepo

How to organize a monorepo structure to have a Unity project alongside other .NET projects.

As prerequisites, I would recommend:
1. Get familiar with Assembly Definitions in Unity — `.asmdef` files: https://docs.unity3d.com/6000.2/Documentation/Manual/assembly-definition-files.html
2. It's worth digging into the basics of MSBuild syntax — XML format of `.csproj` files, in particular so called “SDK-style project”: https://learn.microsoft.com/en-us/dotnet/core/project-sdk/overview#project-files

By default, Unity creates a project `Assembly-CSharp.csproj` for all the gameplay C# scripts.
(Set aside plugins and Editor scripts for now.)
Asmdefs allow you to split your code into multiple assemblies, each with its own `.csproj` file.
This is useful for modularization, faster compilation times, and better dependency management.
It's easier to reference this code from outside of Unity.
I'd suggest having at least two assemblies — let's name them `MyGame.UnityAgnostic` and `MyGame.UnityAware`.

The first one will be used for code that does not depend on UnityEngine or UnityEditor assemblies (`"noEngineReferences": true`).
This code can be referenced from outside of Unity, for example from a .NET backend app, or from unit tests running in a separate test runner.
The second one will contain the Unity-specific code, and will reference UnityEngine and UnityEditor assemblies.
This code can also be referenced from outside of Unity, but with some caveats and more restrictions.
Scripts outside of these two assemblies will become part of the default assembly `Assembly-CSharp.dll`, which can reference both `MyGame.UnityAgnostic.dll` and `MyGame.UnityAware.dll`.

It's better to put as much code as possible into the Unity-agnostic assembly.
Use abstractions, inversion of control, and dependency injection.

Unity will generate `.csproj` files for these assemblies, for example `MyGame.UnityAgnostic.csproj` and `MyGame.UnityAware.csproj`.
You should not commit these files to source control, as they are regenerated by Unity.
Instead, you can create your own `.csproj` files like `MyGame.UnityAgnostic.team-shared.csproj`.
Being an "SDK-style project" means you don't need to list all source files explicitly, as all `*.cs` files in the same folder and subfolders are included automatically.

Both projects should target `netstandard2.1`.
Although you can add some other target frameworks as well, for example `net10.0`, if you need to use some APIs that are not available in `netstandard2.1` on your backend logic.
In this case you will need to use conditional compilation symbols.

The structure of the monorepo can look like this:

```
MyGame-Monorepo/
    MyGame-Unity/
        Assets/
            Scripts/
                MyGame.UnityAgnostic/
                    MyGame.UnityAgnostic.asmdef
                    MyGame.UnityAgnostic.team-shared.csproj
                    ...
                MyGame.UnityAware/
                    MyGame.UnityAware.asmdef
                    MyGame.UnityAware.team-shared.csproj
                    ...
        ProjectSettings/
        ...
    MyGame-Dotnet/
        src/
            MyGame.Backend/
                MyGame.Backend.csproj
        tests/
        MyGame-Dotnet.sln
        ...
```

You can add `MyGame.UnityAgnostic.team-shared.csproj` and `MyGame.UnityAware.team-shared.csproj` projects to your `MyGame-Dotnet.sln` solution file.
And add references to these projects from your .NET projects in `MyGame-Dotnet/`, for example from `MyGame.Backend.csproj`.