DEV Community: Daniel Rinaldi (TenaciousDan)

Unity Foundational Architecture: Smart Bootstrapping

Daniel Rinaldi (TenaciousDan) — Tue, 07 Jul 2026 17:34:15 +0000

Introduction

Let’s face it: out-of-the-box Unity is a fantastic engine, and it is built to cater to everyone. However, because of this it has a very basic out of the box workflow (press play to load the current scene). Any kind of logic that is related to bootstrapping (game setup, system initialization, etc.) or any specific control flow for your game is left in the hands of the developer and setting this up for every project you start can be a momentum killer.

A game's foundation shouldn't rely on you starting from a specific scene in the Editor and clicking through menus or selecting a scene, nor should it rely on you manually dragging a massive GameManager prefab into every single scene in your project and then dealing with timing issues so that your bootstrapping systems initialize first. Today, I am laying down a workflow and talking about the necessary scripts needed so that you can hit play from any scene and have your bootstrapping and game initialization logic execute flawlessly every single time.

Understanding the Unity Initialization Lifecycle

To build our own bootstrapping logic, we first have to understand exactly what happens when you press Play in the editor. Normally, Unity follows a strict execution order that is tied directly to the currently loaded scene(s) in the editor. This is how it goes after you hit the play button:

The scene(s) are loaded into memory. This means that every GameObject and MonoBehaviour in the currently loaded scenes are created on the heap as well as any assets that are referenced from the scene objects. Awake() is called on every active MonoBehaviour in the scene(s). Then OnEnable() is called. Then Start() is called.

If any of your gameplay logic relies on a GameManager, AudioManager, etc to be present, and those managers are initializing inside their own Awake() loops, you run into a classic race condition. Which script runs its Awake() first? If a gameplay script wins the race, it will try to access a manager that hasn't finished setting up yet, resulting in possible null reference exceptions or other bugs.

The RuntimeInitializeOnLoadMethod Attribute (And Its Limitations)

So, how do we make it so that our bootstrapping logic always execute first before any of our gameplay logic runs? Well, you may have heard of Unity's [RuntimeInitializeOnLoadMethod] attribute that allows us to "cut in line". Before any scene asset is loaded, before any GameObject initializes, and before any Awake() method is fired anywhere in your project, our bootstrapping code runs. This guarantees our core infrastructure is awake and waiting before the rest of the game even knows it exists.

However, there are some restrictions to this approach. The target method for this attribute must be static, parameter-less, and inside a non-generic class. This means that if we want to inject some values into these bootstrap classes we are going to have issues. What we really want is the ability to serialize fields and use those values like we do with MonoBehaviours in our scenes but we also want our logic to always run first before any other gameplay logic.

The Solution: The Bootstrap Scene

What we really want is the best of both worlds: the ability to use the Unity Inspector to configure our core systems, combined with a guarantee that this logic always runs first.

The solution is simple: We create a dedicated "Bootstrap" scene that always loads first, which then instantly loads the actual scene we want to play. The only remaining hurdle is making this seamless in the Editor. We don't want to manually open the Bootstrap scene every time we want to test a tweak in Level 3. Luckily for us, Unity allows us to override the functionality of the Editor's play button so that we can force this workflow to behave flawlessly. (As for built games, we don't need to do anything extra other than set our Bootstrap scene as index 0 in the Build Settings).

Let's take a look at how to set this up...

First, let's create the Bootstrap scene. We'll create a regular scene asset and call it "Bootstrap". Next we will add this scene to the list of scenes in the build settings and set it to index 0 so that it is the first scene that your game loads when you launch the built executable.

Ok, now that that's done, we need to override the play button to make the editor workflow smooth. We'll start by creating a static class called EditorBootstrapScene.cs and placing the script under an Editor folder (the folder name is important as we don't want to compile this script in a runtime build).

using UnityEditor;
using UnityEditor.SceneManagement;

using UnityEngine;
using UnityEngine.SceneManagement;

namespace TenaciousEditor.SceneManagement
{
    /// <summary>
    /// A Bootstrap scene is a scene that is used for loading/bootstrapping systems on startup. <br />
    /// The purpose of this class is to override the functionality of the play button in the editor
    /// to make sure that the Bootstrap scene is additively loaded before running the game in the Editor. <br />
    /// This is convenient so that you don't need to always search for and additively load the bootstrap scene
    /// into the hierarchy when you open a new scene in the Editor.
    /// </summary>
    [InitializeOnLoad]
    public static class EditorBootstrapScene
    {
        private const string MENU_ITEM_BOOTSTRAP_SCENE_FOLDER = "Tenacious/SceneManagement/Editor Bootstrap Scene/";
        private const string MENU_ITEM_LOAD_BOOTSTRAP_SCENE_ON_PLAY = MENU_ITEM_BOOTSTRAP_SCENE_FOLDER + "Load Bootstrap Scene On Play";
        private const string MENU_ITEM_DONT_LOAD_BOOTSTRAP_SCENE_ON_PLAY = MENU_ITEM_BOOTSTRAP_SCENE_FOLDER + "Don't Load Bootstrap Scene On Play";
        private const string MENU_ITEM_OPEN_BOOTSTRAP_SCENE = MENU_ITEM_BOOTSTRAP_SCENE_FOLDER + "Open Bootstrap Scene";

        static EditorBootstrapScene()
        {
            if (ShouldLoadBootstrapSceneOnPlay)
                RegisterCallbacks();
        }

        private static void RegisterCallbacks()
        {
            EditorApplication.playModeStateChanged -= OnPlayModeChanged;
            EditorApplication.playModeStateChanged += OnPlayModeChanged;

            SceneManager.sceneLoaded -= OnSceneLoaded;
            SceneManager.sceneLoaded += OnSceneLoaded;
        }

        private static void UnregisterCallbacks()
        {
            EditorApplication.playModeStateChanged -= OnPlayModeChanged;
            SceneManager.sceneLoaded -= OnSceneLoaded;
        }

        [MenuItem(MENU_ITEM_LOAD_BOOTSTRAP_SCENE_ON_PLAY)]
        private static void EnableLoadBootstrapSceneOnPlay()
        {
            string bootstrapScenePath = EditorUtility.OpenFilePanel("Select Bootstrap Scene", Application.dataPath, "unity");
            bootstrapScenePath = bootstrapScenePath.Replace(Application.dataPath, "Assets");

            if (!string.IsNullOrEmpty(bootstrapScenePath))
            {
                BootstrapScenePath = bootstrapScenePath;
                ShouldLoadBootstrapSceneOnPlay = true;
            }
        }

        [MenuItem(MENU_ITEM_DONT_LOAD_BOOTSTRAP_SCENE_ON_PLAY, true)]
        private static bool EnableDontLoadBootstrapSceneOnPlayMenuItem() => ShouldLoadBootstrapSceneOnPlay;

        [MenuItem(MENU_ITEM_DONT_LOAD_BOOTSTRAP_SCENE_ON_PLAY)]
        private static void DisableLoadBootstrapSceneOnPlay()
        {
            ShouldLoadBootstrapSceneOnPlay = false;
        }

        [MenuItem(MENU_ITEM_OPEN_BOOTSTRAP_SCENE, true)]
        private static bool EnableOpenBootstrapScene() => ShouldLoadBootstrapSceneOnPlay;

        [MenuItem(MENU_ITEM_OPEN_BOOTSTRAP_SCENE)]
        private static void OpenBootstrapScene()
        {
            EditorSceneManager.OpenScene(BootstrapScenePath, OpenSceneMode.Additive);
        }

        public static bool ShouldLoadBootstrapSceneOnPlay
        {
            get => EditorBootstrapScenePrefs._loadBootstrapSceneOnPlay;
            set
            {
                EditorBootstrapScenePrefs._loadBootstrapSceneOnPlay = value;

                if (value)
                    RegisterCallbacks();
                else
                    UnregisterCallbacks();
            }
        }

        public static string BootstrapScenePath
        {
            get => EditorBootstrapScenePrefs._bootstrapScenePath;
            set => EditorBootstrapScenePrefs._bootstrapScenePath = value;
        }

        private static void OnPlayModeChanged(PlayModeStateChange state)
        {
            // TODO
        }

        private static void OnSceneLoaded(Scene scene, LoadSceneMode mode)
        {
            // TODO
        }

        private class EditorSessionState : SessionState
        {
            private static readonly string KEY_PREFIX = $"{PlayerSettings.productGUID}.{typeof(EditorBootstrapScene).FullName}";
            public static readonly string KEY_PREVIOUS_ACTIVE_SCENE_PATH = $"{KEY_PREFIX}.{nameof(ShouldLoadBootstrapSceneOnPlay)}";

            internal static string _previousActiveScenePath
            {
                get => GetString(KEY_PREVIOUS_ACTIVE_SCENE_PATH, BootstrapScenePath);
                set => SetString(KEY_PREVIOUS_ACTIVE_SCENE_PATH, value);
            }
        }

        private class EditorBootstrapScenePrefs
        {
            private static readonly string KEY_PREFIX = $"{PlayerSettings.productGUID}.{typeof(EditorBootstrapScene).FullName}";
            public static readonly string LOAD_BOOTSTRAP_SCENE_ON_PLAY = $"{KEY_PREFIX}.{nameof(_loadBootstrapSceneOnPlay)}";
            public static readonly string BOOTSTRAP_SCENE_PATH = $"{KEY_PREFIX}.{nameof(_bootstrapScenePath)}";

            internal static bool _loadBootstrapSceneOnPlay
            {
                get => EditorPrefs.GetBool(LOAD_BOOTSTRAP_SCENE_ON_PLAY, false);
                set => EditorPrefs.SetBool(LOAD_BOOTSTRAP_SCENE_ON_PLAY, value);
            }

            internal static string _bootstrapScenePath
            {
                get => EditorPrefs.GetString(BOOTSTRAP_SCENE_PATH, null);
                set => EditorPrefs.SetString(BOOTSTRAP_SCENE_PATH, value);
            }
        }
    }
}

The above code should add a menu item in the top toolbar that allows us to select and set a Bootstrap scene via a file menu dialog popup. Once set, we will save the file path to the bootstrap scene to the local EditorPrefs that (by the way) should not get pushed to git. Now let's finish writing the empty callback functions OnPlayModeChanged and OnSceneLoaded.

private static void OnPlayModeChanged(PlayModeStateChange state)
{
    if (!ShouldLoadBootstrapSceneOnPlay)
        return;

    if (EditorApplication.isPlaying)
        return;

    if (EditorApplication.isPlayingOrWillChangePlaymode)
    {
        // user pressed the play button...
        EditorSessionState._previousActiveScenePath = SceneManager.GetActiveScene().path;

        if (EditorSceneManager.SaveCurrentModifiedScenesIfUserWantsTo())
        {
            string bootstrapScenePath = BootstrapScenePath;
            try
            {
                Scene bootstrapScene = EditorSceneManager.OpenScene(bootstrapScenePath, OpenSceneMode.Additive);

                // active scene is loaded first, so we set the active scene to be the bootstrap scene
                SceneManager.SetActiveScene(bootstrapScene);
            }
            catch
            {
                Debug.LogError($"Bootstrap Scene not found: `{bootstrapScenePath}`");
                EditorApplication.isPlaying = false;
            }
        }
        else
        {
            // user canceled the save operation...
            EditorApplication.isPlaying = false;
        }
    }
    else
    {
        // user pressed stop button or canceled play...
        Scene previousActiveScene = SceneManager.GetSceneByPath(EditorSessionState._previousActiveScenePath);

        if (previousActiveScene.IsValid())
            SceneManager.SetActiveScene(previousActiveScene);
    }
}

private static void OnSceneLoaded(Scene scene, LoadSceneMode mode)
{
    if (EditorSessionState._previousActiveScenePath != null && scene.path == EditorSessionState._previousActiveScenePath)
    {
        // at this point the bootstrap scene was already loaded and Awake() methods were invoked, revert to previous active scene
        SceneManager.SetActiveScene(SceneManager.GetSceneByPath(EditorSessionState._previousActiveScenePath));
    }
}

With this code, we now have a way to set a bootstrap scene and then additively load it when the user presses play. We make sure to set the bootstrap scene as the active scene so that awake methods are prioritized in that scene in the first frame. Afterwards, we set the previously active scene back to being the active scene and then let the scene loading process continue as normal.

So what now? Well, now we can add Singletons or Services we want to run on game start in order to initialize key systems in this new scene we created. It's important that we tell all the devs on the team to make sure that they set the Bootstrap scene in the editor if they want to test gameplay logic that requires that key game systems have already been setup and initialized. This is as simple as adding a note in the project's README about this.

There is one last thing that we need to do. In a built game, if we set the bootstrap scene as scene index 0, nothing will happen. This is because we still need a script to load the actual first scene in a built game. To do that let's create a MonoBehaviour script called Bootstrap.cs and let's make sure this is NOT placed inside an Editor folder.

using UnityEngine;
using UnityEngine.SceneManagement;

using System.Collections;

namespace Tenacious.SceneManagement
{
    /// <summary>
    /// This script should be placed on a game object inside a Bootstrap Scene. 
    /// In a build, this script will load the next scene (build index + 1) at the end of the first frame.
    /// </summary>
    public class Bootstrap : MonoBehaviour
    {
        protected virtual void Start()
        {
            StartCoroutine(CR_LoadNextScene());
        }

        private IEnumerator CR_LoadNextScene()
        {
            yield return new WaitForEndOfFrame();

            LoadNextScene();
        }

        private void LoadNextScene()
        {
            if (Application.isEditor)
            {
                if (SceneManager.sceneCount > 1)
                    SceneManager.UnloadSceneAsync(gameObject.scene);
            }
            else
            {
                SceneManager.LoadScene(gameObject.scene.buildIndex + 1);
            }
        }
    }
}

With this script created and attached to a GameObject in our Bootstrap scene, we now have it so that in a build, assuming the Bootstrap scene is loaded first, during the first frame we will call awake and start on all MonoBehaviours in the Bootstrap scene and after the first frame has finished we will load the next scene (bootstrap scene index + 1).

Now we can add whatever game objects we want to the bootstrap scene and initialize whatever we need in one place. We also have dependency injection via Unity's [SerializeField] if needed. In my next blog post we will discuss Single Instance Systems (Singletons/Services) which have single instances that are tied to the game instance itself.

Unity Foundational Architecture: Project Scaffolding

Daniel Rinaldi (TenaciousDan) — Tue, 07 Jul 2026 17:34:01 +0000

Introduction

Great architecture in Unity is entirely about drawing the right boundaries. Whether you are building a view-first UI framework or completely decoupling your core logic from your visual representation, the success of those systems is dictated by your initial project setup and that poor scaffolding will fight you evry step of the way. In this article we are going to look at how to properly setup and structure a brand new Unity project.

Scaffolding

In this article, we are going to setup some basic scaffolding that most Unity projects will need (one way or another). Scaffolding is about setting up the foundational environment of a project. The goal is to handle all the repetitive, baseline setup so you can immediately start writing actual feature code.

After creating a new Unity project, there's a few things that Unity devs do but we are going to focus on the shared setup process (we're skipping things that are only local like editor layouts, IDE setup, etc).

Git

Next we'll create our .gitignore and a .gitattributes files.

For the .gitignore we can use the following file which should be placed at the root of your project folder:

##################################################
# Unity
##################################################

# Unity-generated folders
.utmp/
/[Ll]ibrary/
/[Ll]ogs/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Uu]ser[Ss]ettings/

# Unity 6 : ignore recovery folder created upon restarting after a crash.
/[Aa]Assets/_Recovery/
/[Aa]Assets/_Recovery.meta

# ignore the asset store tools plugin
/[Aa]ssets/AssetStoreTools*

# Explicitly track Unity's package manifest and packages-lock json files
!**/[Pp]ackages/manifest.json
!**/[Pp]ackages/packages-lock.json

# 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

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

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

# Gradle cache directory
.gradle/

# Unity3D generated file on crash reports
sysinfo.txt

# Builds artifacts
*.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/*

##################################################
# IDEs
##################################################

# Rider
##################################################
/[Aa]ssets/Plugins/Editor/JetBrains*
.idea/

# VS Code
##################################################
.vscode/

# Visual Studio
##################################################
.vs/

##################################################
# Custom
##################################################

# ignore any folder named 'gitignore' and its contents
gitignore/
gitignore.meta

# End of Custom ##################################

Note the Custom section at the end. Here is where you can add custom ignore patterns. I added a pattern to ignore any folder called gitignore in the project as a nice to have. This is so that devs can experiment with things locally without worrying about needing to discard/stash those changes so that they don't show up in another PR.

Next we'll create the .gitattributes file which is used to define how Git should track, format, and merge specific file types. But what's more important is its relation to Git LFS. Unity projects inherently contain massive binary assets like textures (.png, .psd), 3D models (.fbx, .obj), and audio clips (.wav, .mp3). Normal Git cannot handle these well and they will bloat your repository quickly. The .gitattributes file acts as the explicit instruction manual for Git LFS. It intercepts designated file extensions and flags those files to be uploaded to an external storage server (take note of all the lines ending in lfs), replacing them in your standard repo with a tiny text pointer instead. Make sure that you enable Git LFS for your project. Anyways, here's the .gitattributes file which should be placed at the root of your project folder:

# Define macros (only works in top-level gitattributes files)
[attr]lfs               filter=lfs diff=lfs merge=lfs -text
[attr]unity-json        eol=lf linguist-language=json
[attr]unity-yaml        merge=unityyamlmerge eol=lf linguist-language=yaml

# Ensure that text files that any contributor introduces to the repository have their line endings normalized
* text=auto

# Unity source files
*.cginc                 text
*.compute               text linguist-language=hlsl
*.cs                    text diff=csharp
*.hlsl                  text linguist-language=hlsl
*.raytrace              text linguist-language=hlsl
*.shader                text

# Unity JSON files
*.asmdef                unity-json
*.asmref                unity-json
*.index                 unity-json
*.inputactions          unity-json
*.shadergraph           unity-json
*.shadersubgraph        unity-json

# Unity UI Toolkit files
*.tss                   text diff=css linguist-language=css
*.uss                   text diff=css linguist-language=css
*.uxml                  text linguist-language=xml linguist-detectable

# Unity YAML files
*.anim                  unity-yaml
*.asset                 unity-yaml
*.brush                 unity-yaml
*.controller            unity-yaml
*.flare                 unity-yaml
*.fontsettings          unity-yaml
*.giparams              unity-yaml
*.guiskin               unity-yaml
*.lighting              unity-yaml
*.mask                  unity-yaml
*.mat                   unity-yaml
*.meta                  unity-yaml
*.mixer                 unity-yaml
*.overrideController    unity-yaml
*.playable              unity-yaml
*.prefab                unity-yaml
*.preset                unity-yaml
*.renderTexture         unity-yaml
*.scenetemplate         unity-yaml
*.shadervariants        unity-yaml
*.signal                unity-yaml
*.spriteatlas           unity-yaml
*.spriteatlasv2         unity-yaml
*.terrainlayer          unity-yaml
*.unity                 unity-yaml
*.physicMaterial        unity-yaml
*.physicsMaterial2D     unity-yaml

# Unity LFS
*.cubemap               lfs
*.unitypackage          lfs

## 3D models
*.3dm                   lfs
*.3ds                   lfs
*.blend                 lfs
*.blend1                lfs
*.c4d                   lfs
*.collada               lfs
*.dae                   lfs
*.dxf                   lfs
*.FBX                   lfs
*.fbx                   lfs
*.jas                   lfs
*.lws                   lfs
*.lxo                   lfs
*.ma                    lfs
*.max                   lfs
*.mb                    lfs
*.obj                   lfs
*.ply                   lfs
*.skp                   lfs
*.stl                   lfs
*.ztl                   lfs

## Audio
*.aif                   lfs
*.aiff                  lfs
*.it                    lfs
*.mod                   lfs
*.mp3                   lfs
*.ogg                   lfs
*.s3m                   lfs
*.wav                   lfs
*.xm                    lfs

## Video
*.asf                   lfs
*.avi                   lfs
*.flv                   lfs
*.mov                   lfs
*.mp4                   lfs
*.mpeg                  lfs
*.mpg                   lfs
*.ogv                   lfs
*.wmv                   lfs

## Images
*.bmp                   lfs
*.exr                   lfs
*.gif                   lfs
*.hdr                   lfs
*.iff                   lfs
*.jpeg                  lfs
*.jpg                   lfs
*.pict                  lfs
*.png                   lfs
*.psd                   lfs
*.tga                   lfs
*.tif                   lfs
*.tiff                  lfs
*.webp                  lfs

## Compressed Archive
*.7z                    lfs
*.bz2                   lfs
*.gz                    lfs
*.rar                   lfs
*.tar                   lfs
*.zip                   lfs

## Compiled Dynamic Library
*.dll                   lfs
*.pdb                   lfs
*.so                    lfs

## Fonts
*.otf                   lfs
*.ttf                   lfs

## Executable/Installer
*.apk                   lfs
*.exe                   lfs

## Documents
*.pdf                   lfs

## .a files (Static Libraries): These are archive files often used for compiled C++ static libraries, frequently used in Unity projects for iOS native plugins or specialized plug-in libraries.
*.a                     lfs

## Spine export file for Unity
*.skel.bytes            lfs

Project Settings

You should configure any initial project settings in the Project Settings window which you can open by selecting Edit > Project Settings... in the top toolbar. While many of the settings here are project specific there are a few that you should adjust right away.

Player settings:
- You should update the Company Name, Product Name, and Version fields so that they are not set to the default.
- You should also configure the Splash Image. I usually just set it to this (see image below) and simply append to the list of logos when a logo for the game is ready:
Editor settings:
- You should set Asset Serialization > Mode to Force Text to force YAML instead of binary for asset files. This makes it easier to work with Git and Unity YAML-Merge.
- You should also set Enter Play Mode Settings > When entering Play Mode to Reload Scene Only to enable fast enter play mode. This will be the default setting in Unity 6.5+ and moving forward as they are deprecating and removing the option to Reload Domain when entering Play Mode. This makes it so that Unity does not destroy the entire C# code domain state and does not reload any assemblies which means that static data, variables, events and memory are not reset when entering play mode in editor. The plus side is that this makes you write cleaner code and also makes entering play mode super-super quick!

Project Folder Structure

Let's start with folder structure. This is the folder hierarchy that I use for my projects:

[PROJECT_ROOT]/
├── Assets/
│   ├── _Project/
│   │   ├── _Modules/
│   │   │   └── Default/
│   │   │       ├── _Runtime/
│   │   │       └── Editor/
│   │   ├── _Scenes/
│   │   ├── Art/
│   │   ├── Audio/
│   │   │   ├── Music/
│   │   │   └── Sounds/
│   │   ├── Resources/
│   │   ├── Sandbox/
│   │   ├── Settings/
│   │   └── StreamingAssets/
│   │       └── Videos/
│   ├── TextMesh Pro/
│   └── ...
├── Packages/
├── .gitignore
├── .gitattributes
├── README.md
└── ...

The key take-aways from this folder structure is the following:

The Special Folders that Unity reserves that we have setup prematurely (Editor, Resources, StreamingAssets). Note that you can have multiple of some folders in your project and Unity will consider/group them all together when processing them.
The _ prefix for some of the folder names is just so that Unity orders it first inside its parent folder in the project explorer which uses alphabetical sorting for folders.
The _Project folder where we have already setup a neat standard moving forward for how we separate and organize our project's code modules (more on that later) from other assets like _Scenes (level design), Art, Settings, etc.
The _Scenes folder, where we keep the scene files as well as any files related to a given scene. Usually I create a folder with the same name as the scene and place stuff like baked navmesh and lighting files there (unity will do this automatically for you as well when you bake navmesh or lighting).
The Art folder. This folder is for artists only (no code). Many artists want to just focus on art and be able to have their own project structure for organization and this folder allows them to do that. Textures, images, 3D models, all go in here.
The Audio folder. Again, this is a folder where audio engineers can have their own file organization. Although I usually impose a Music and Sounds subfolder so that my code can easily scan a single folder when generating assets that connect the audio to in-game systems (so I'll leave this up to you).
The Sandbox folder. This is where devs can roughly test things and place files that might not ever be used in production if a feature they are prototyping is rejected. Essentially, this is where someone can prototype a feature. I usually create subfolders with the names of each dev in this folder so each dev has there own working directory.
The Settings folder. This folder is to group all the settings/configuration files for the project. Things like InputSystem (.inputactions file), Localization (locales, tables, and settings), URP Settings (URP Render Pipeline assets, etc),
The TextMesh Pro and Assets/... folders. These folders sit outside the _Project folder and are mainly for external asset packages like the ones you'd download off the asset store. It may be tempting to group them under a third party folder but I've seen some assets that assume they are placed at the root of the assets folder and if not placed there don't function properly as a result. While this is a very small minority of asset plugins, it's best to side with caution here. Besides, since we prefixed the project folder with _ these external assets will always end up sorted at the end of the project explorer window.

TextMesh Pro

In the editor toolbar menu at the top, select Window > TextMeshPro > Import TMP Essential Resources. This will import the TextMesh Pro essential resources. This will also trigger when you add your first TMP Text component in a UI. You might want to configure a default font at some point but I'll leave that up to you.

Scenes

There are at least 2-3 scenes that I create at the start of every project.

The Bootstrap scene: This scene is the entry point of the application in a build and should be set as index 0 in the build settings scene list. For more information about bootstrapping see my other article. If you prefer to use your own bootstrapping logic than you can skip creating this scene however I strongly advise reading the other article and setting up your bootstrapping logic using a scene.
The Splash scene (optional): This scene is only needed if you want to have something more flashy as a splash screen other than the built in logo fades with a plain background (think animations or 3D scene or particle effects). If you implement this scene don't forget to add it as index 1 (after the bootstrap scene) in the build settings scene list.
The Welcome scene: Every game has this, it's the first scene where the player has input agency and is usually reffered to as "the main menu". Here I usually just setup a UI view with the Game's title at the top and a basic vertical menu with some basic buttons which have some simple functionality. The 2 buttons I implement are Play (brings you to another scene) and Quit which calls Application.Quit(). This scene should be set as index 2 (after the splash scene) in the build settings scene list.

When creating scenes I also like to impose a structure to the scene hierarchy. To make it easier to keep the same initial hierarchy when creating scenes, I create a scene template via RightClick in Project Window > Create > Scene > Scene Template. This will create a scenetemplate asset that you can point to a scene to use as the template. So create a regular scene and place it adjacent to the scenetemplate asset and then simply drag the scene into the Template Scene field of the scenetemplate asset's inspector. Also make sure to check Pin in New Scene Dialog so that our template stands out.

My basic scene template is as follows:

Everything in [] is at position (0,0,0) and has zero rotation and a scale of (1,1,1). The [Context] object and everything under it are mostly for contextual things like navmesh, players spawned at runtime, level specific managers, etc. The [Environment] object is for the level designer and is meant to contain all the 3D models and gameobjects that make up the 3D world as well as any lights, post processing volumes, etc.

To use this Scene Template that we created, we just have to press Ctrl+N in the Editor and we should see our scene template in the New Scene Dialog list.

Code Modules

Every project can, at some point, have code that can be grouped into its own module and even if you don't have any initially it's good to set this structure up now. The _Modules folder is where all your codebase will live. Each code module should be separated within its own folder and have assembly definitions to enforce separation of concerns and to ensure a clean dependency between modules and assemblies. I will not go over assembly definitions in this article but I will explain the one or two that every Unity dev uses whether they know it or not which is the "Default" hidden Assembly-CSharp and Assembly-CSharp-Editor assemblies.

The default Assembly-CSharp assembly (which you may have already seen in your IDE) is the default assembly that any code under the Assets/ lives in. Unity sets this assembly up by default and automatically makes it depend on every single other assembly in the project. This assembly is also a "Runtime" assembly which is a term I use to mean that the code in this assembly is compiled and packaged in our built game. Basically any code we add under _Modules/Default/Runtime/ will be part of this default Assembly-CSharp assembly, which is why the folders are structured this way.

You may have noticed that there is also an Editor folder under the _Modules/Default/ folder. This is because if we write Editor code we do not want this code to be compiled and packaged with our built game, in fact Unity will throw errors when building if this is the case. By adding Editor specific scripts under this folder, Unity will automatically add them into a default Assembly-CSharp-Editor assembly (which you also may have seen in your IDE before). This entire assembly is automatically excluded from all builds except for editor which means that the code here is not packaged with your game builds and Unity will not throw any errors. So you should use this folder for any Editor specific code.

You can make other modules like a "Core" module which contains interfaces and common logic if you want but you'll have to create your own assembly definitions for that and that is a whole other topic. If you do create another module, you should follow the same folder structure where you create the module folder "Core" and under it create the "_Runtime" and "Editor" folders which will house their respective assembly definition files.

README

Finally, you should create a README.md with instructions on how to clone the project and install it on your machine.

Here's a good starting point:

# PROJECT_NAME

- [PROJECT_NAME](#project_name)
  - [Installation](#installation)
    - [Clone Project](#clone-project-using-git)
  - [Configuration](#configuration)
    - [Setup Custom Mergetool (optional)](#setup-custom-mergetool-optional)
  - [Getting Started](#getting-started)

## Installation

### Clone Project Using Git

```
cd [CHOOSE_A_DIRECTORY_TO_STORE_THE_REPO]
git clone [INSERT_URL_TO_GIT_REPO_HERE]
```

Next, Continue to the `Git Configuration` section to configure git or just go straight to `Getting Started` section below.  

## Configuration

### Setup Custom Mergetool (optional)

UnityYAMLMerge.exe is a merge tool that aids with the merging of scene, prefab and asset files (and any other YAML files). It comes packaged with each installation of the Unity Editor, therefore if you upgrade the project version you should also update your custom merge tool to use the newer UnityYAMLMerge.exe for your version of Unity.  

You must tell Git to use UnityYAMLMerge.exe as a custom merge tool and also as a custom diff tool. It is located in the [UnityEditor installation folder](https://docs.unity3d.com/2021.3/Documentation/Manual/SmartMerge.html) under `./Editor/Data/Tools/UnityYAMLMerge.exe`.  
On Windows this is located at `C:/Program Files/Unity/Hub/Editor/{EDITOR_VERSION}/Editor/Data/Tools/UnityYAMLMerge.exe`.  

Once you have setup Git to use UnityYAMLMerge, you must then tell UnityYAMLMerge what diff tool to use as a fallback. To do this, you simply need to edit `mergespecfile.txt` located adjacent (within the same folder) to the UnityYAMLMerge.exe file.  
Follow the instructions in this txt file to setup a fallback merge/diff tool.  

For more info on UnityYAML merge (Smart Merge) and setup with git or git GUIs see : https://docs.unity3d.com/2021.3/Documentation/Manual/SmartMerge.html  

## Getting Started

Notice how I included a paragraph in the README about Unity YAML-Merge? That's because this is not something that you can do for the whole project. Each developer should be setting this up locally for every project that they are collaborating on. If you are working on a project and are arguing 90% of the time about who is currently modifying a scene or prefab file then you are using Unity wrong in my opinion. Unity YAML-Merge allows you to merge scene, prefab, and asset files without breaking or corrupting anything. There are some edge cases but from my experience they are far and in between and are generally not an issue in practical use when work is separated cleanly.

Push the Initial Commit

With all of the above done, you can stage all your changes and push the initial commit to your main branch.

DEV Community: Daniel Rinaldi (TenaciousDan)

Unity Foundational Architecture: Smart Bootstrapping

Table of Contents:

Introduction

Understanding the Unity Initialization Lifecycle

The RuntimeInitializeOnLoadMethod Attribute (And Its Limitations)

The Solution: The Bootstrap Scene

Unity Foundational Architecture: Project Scaffolding

Table of Contents:

Introduction

Scaffolding

Git

Project Settings

Project Folder Structure

TextMesh Pro

Scenes

Code Modules

README

Push the Initial Commit