DEV Community: Daniel Rinaldi (TenaciousDan)

Unity Foundational Architecture: Loose Coupling, Interfaces & Events

Daniel Rinaldi (TenaciousDan) — Sat, 08 Aug 2026 00:29:24 +0000

Introduction
The Power of Interfaces
- The Unity Serialization Wall
- Building a Serializable Unity Object Reference
- Serializing Plain C# Object References
Decoupling Communication (Events)
- Building a Simple Generic Global Event Bus
- The Instance Specific Event Problem
- Instance Specific EventBus
- Serializing Events
Conclusion

Introduction

In the last few posts we covered Project Scaffolding, Bootstrapping Logic, and Global State Management. The next problem that we will tackle is how to tie our code and scene objects together without creating a tangled and unmanageable web of dependencies (Spaghetti).

The Power of Interfaces

To decouple our systems, we need to stop relying on concrete classes. If a Turret script needs to deal damage, it shouldn't hold a reference to PlayerHealth, EnemyHealth, or DestructibleCrate. Doing so creates strict dependencies.

Instead, the Turret just needs to know that the thing it's hitting can take damage. As such we can define an generic interface for "things that can take damage". Let's call it IDamageable:

public interface IDamageable 
{
    void TakeDamage(int amount);
}

Now, the Turret only relies on the IDamageable contract. It doesn't care what the object is, as long as it signs that contract. This is textbook loose coupling.

The Unity Serialization Wall

However, if you try to expose this interface in the inspector so that you can inject the dependancy into your monobehaviour scripts connecting the scene objects, you'll hit a wall.

Unity's standard serializer does not serialize interfaces. It can only handle concrete classes that derive from UnityEngine.Object. Now, you can work around this by using GetComponent() in Awake() essentially hooking things up on initialization manually through code, but that forces you to hardcode scene hierarchy paths or rely on slow runtime lookups, and defeating the purpose of a highly configurable architecture that uses dependancy injection.

Building a Serializable Unity Object Reference

To get the best of both world, clean interfaces in our code and drag-&-drop support in the inspector, we can build a generic wrapper.

By utilizing the ISerializationCallbackReceiver interface, we can trick Unity into serializing a standard UnityEngine.Object, while casting it to our interface behind the scenes.

using UnityEngine;

using System;
using System.Collections.Generic;

using UnityObject = UnityEngine.Object;

[Serializable]
public class SerializableUnityRef<T> : ISerializationCallbackReceiver where T : class
{
    // This field will store the serialized reference to the Unity Object that the inspector can serialize (The True Value)
    [SerializeField]
    private UnityObject _reference;

    // This field will store the serialized reference casted to T which may or may not be a serializable type.
    [SerializeField]
    private T _value;

    public SerializableUnityRef() { }

    public SerializableUnityRef(T val)
    {
        Value = val;
    }

    /// <summary>
    /// Gets and Sets the current runtime value of this object. Note that if the value is set at runtime to something that is not a Unity Object,
    /// then the backing reference will be null.
    /// </summary>
    public T Value
    {
        get => _value == null ? _value = _reference as T : _value;
        set
        {
            bool changed = _value != value;

            _value = value;

            if (changed)
            {
                if (_value is UnityObject valueAsUnityObject)
                    _reference = valueAsUnityObject;
                else
                    _reference = null;
            }
        }
    }

    public bool HasValue => Value != null;

    public Type ValueType => typeof(T);

    /// <returns>
    /// The backing reference value of this object (The True Value). If null, then return the stored runtime value of this object without modifying it.
    /// This differs from the <see cref="Value"/> property getter which will adjust the stored value to match the backing reference if the value is null and the reference is not.
    /// </returns>
    public static T ValueOf(SerializableUnityRef<T> serializableUnityRef)
    {
        if (serializableUnityRef == null)
            return null;
        else if (serializableUnityRef._reference == null)
            return serializableUnityRef.Value;
        else
            return serializableUnityRef._reference as T;
    }

    public static implicit operator T(SerializableUnityRef<T> serializableRef) => serializableRef.Value;
    public static implicit operator SerializableUnityRef<T>(T val) => new SerializableUnityRef<T>() { Value = val };

    void ISerializationCallbackReceiver.OnBeforeSerialize()
    {
        ValidateReferenceObject();
    }

    void ISerializationCallbackReceiver.OnAfterDeserialize()
    {
        // do nothing
    }

    internal void ValidateReferenceObject()
    {
        if (_reference == null)
        {
            _value = null;
            return;
        }

        if (ValueType == typeof(GameObject) && _reference.GetType() == typeof(GameObject))
        {
            return;
        }

        if (_reference is GameObject go)
        {
            _reference = null;

            // find first component that inherits from T
            foreach (Component component in go.GetComponents<Component>())
            {
                if (component is T)
                {
                    _reference = component;
                    break;
                }
            }
        }
        else if (!(_reference is T))
        {
            _reference = null;
        }
    }
}

// This now shows up in the inspector!
[SerializeField]
private SerializableUnityRef<IDamageable> _target;

private void Attack()
{
    target.Value?.TakeDamage(10);
}

While this solution "works" it doesn't look very nice in the inspector and is missing some use cases that still makes it difficult to use properly.

What we have so far:

A wrapper to serialize a reference to a Unity Object in the inspector. Works for Monobehaviour and ScriptableObject derived classes.

What we are missing:

A better look and feel in the inspector. Requires a custom property drawer.
A way to drag and drop a GameObject and reference a specific component on that GameObject. If there are multiple components of the same reference type then we need some sort of dropdown in the inspector to help distinguish between them so we know which one we are injecting. Also requires a custom property drawer.

Let's build a custom property drawer so that we can fix the above problems. You will need to create a SerializableUnityRefPropertyDrawer script inside an Editor folder. We will also have to modify our SerializableUnityRef script and add an interface.

public interface ISerializableUnityRef : ISerializationCallbackReceiver
{
    public List<object> GetSiblingComponentsOfTypeFromReferenceObject();

    public Type ValueType { get; }
}

// change the class so that it inherits from our custom interface
[Serializable]
public class SerializableUnityRef<T> : ISerializableUnityRef where T : class
{
    // all other fields and methods remain the same ...

    // add the GetSiblingComponentsOfTypeFromReferenceObject method to respect our interface:

    /// <summary>
    /// If the referenced object is a Component, then this gets all components attached 
    /// to the same gameObject that are of type <typeparamref name="T"/>. <br />
    /// Otherwise, returns a single element list with just the reference object.
    /// </summary>
    /// <returns>
    /// A non-empty list of all components attached to the same gameObject as the 
    /// referenced object that are of type <typeparamref name="T"/>.
    /// </returns>
    public List<object> GetSiblingComponentsOfTypeFromReferenceObject()
    {
        List<object> siblingComponents = new List<object>();

        if (_reference == null)
            return siblingComponents;

        // we must cast the value and set the reference if value was set via code
        if (_reference == null && _value != null && _value is UnityObject valueAsUnityObject)
        {
            _reference = valueAsUnityObject;
        }

        if (_reference is Component component)
        {
            siblingComponents.AddRange(component.GetComponents<T>());
        }
        else if (!(_reference is T))
        {
            siblingComponents.Add(_reference);
        }

        return siblingComponents;
    }
}

Ok so the next part is just custom PropertyDrawer logic using the EditorGUI API. We will essentially check if the reference is a gameobject and if it is then we will use the function we just created to get all the components attached that inherit from the same type and let the user select the correct component via a dropdown. If it's not a gameobject then we just make it look like a normal single line serialized property field. If you don't understand what is going on here it's ok to just copy paste the following code (this article is not going to cover Unity Editor Custom Tool programming). Just be sure to include this next bit of code inside an Editor folder so that your build will not crash.

[CustomPropertyDrawer(typeof(SerializableUnityRef<>))]
public class SerializableUnityRefPropertyDrawer : PropertyDrawer
{
    private const string REFERENCE_OBJECT_FIELD_NAME = "_reference";

    private int _selectedReferenceIndex;

    public override float GetPropertyHeight(SerializedProperty property, GUIContent label)
    {
        return EditorGUIUtility.singleLineHeight;
    }

    public override void OnGUI(Rect position, SerializedProperty property, GUIContent label)
    {
        EditorGUI.BeginProperty(position, GUIContent.none, property);
        DrawReferenceField(ref position, property, label);
        EditorGUI.EndProperty();
    }

    private void DrawReferenceField(ref Rect position, SerializedProperty property, GUIContent label)
    {
        ISerializableUnityRef serializableRef = PropertyDrawerUtility.GetFieldValue<ISerializableUnityRef>(property);

        if (serializableRef == null)
            return;

        List<object> references = serializableRef.GetSiblingComponentsOfTypeFromReferenceObject();

        float propertyFieldWidth = position.width;

        if (references.Count > 1)
        {
            propertyFieldWidth = Mathf.Min(propertyFieldWidth * 0.7f, 400);
            EditorGUIUtility.labelWidth = Mathf.Clamp(EditorStyles.label.CalcSize(label).x, 100, _originalLabelWidth);
        }

        SerializedProperty spReferenceObject = property.FindPropertyRelative(REFERENCE_OBJECT_FIELD_NAME);

        Rect drawRect = new Rect(position.x, position.y, propertyFieldWidth, EditorGUIUtility.singleLineHeight);

        float horizontalSpacing = 2f;
        float horizontalSpaceUsed = drawRect.width + horizontalSpacing;
        position.x += horizontalSpaceUsed;
        position.width -= horizontalSpaceUsed;

        EditorGUI.PropertyField(drawRect, spReferenceObject, label);

        EditorGUIUtility.labelWidth = _originalLabelWidth;

        if (references.Count > 1)
        {
            string[] displayedOptions = new string[references.Count];
            for (int i = 0; i < references.Count; ++i)
            {
                displayedOptions[i] = $"{i} - {references[i].GetType().Name}";

                if (references[i].Equals(spReferenceObject.objectReferenceValue))
                    _selectedReferenceIndex = i;
            }

            drawRect = new Rect(position.x, position.y, position.width, EditorGUIUtility.singleLineHeight);

            horizontalSpaceUsed = drawRect.width + horizontalSpacing;
            position.x += horizontalSpaceUsed;
            position.width -= horizontalSpaceUsed;

            EditorGUI.BeginChangeCheck();
            {
                _selectedReferenceIndex = EditorGUI.Popup(drawRect, _selectedReferenceIndex, displayedOptions);
            }
            if (EditorGUI.EndChangeCheck())
            {
                spReferenceObject.objectReferenceValue = references[_selectedReferenceIndex] as UnityObject;
            }
        }
    }
}

// Helper functions contained inside a utility class:
public static class PropertyDrawerUtility
{
    /// <returns>The actual value of the given <paramref name="property"/>. Handles arrays/lists as well.</returns>
    public static T GetFieldValue<T>(SerializedProperty property) where T : class
    {
        object obj = GetTargetObjectOfProperty(property);

        if (obj == null)
            return null;

        Type objType = obj.GetType();
        bool isList = objType.IsGenericType && objType.GetGenericTypeDefinition() == typeof(List<>);

        T actualObject = null;
        if (objType.IsArray || isList)
        {
            int index = Convert.ToInt32(new string(property.propertyPath.Where(c => char.IsDigit(c)).ToArray()));

            if (isList)
                actualObject = (T)((IList)obj)[index];
            else
                actualObject = ((T[])obj)[index];
        }
        else
        {
            actualObject = obj as T;
        }

        return actualObject;
    }

    /// <returns>the object the property represents.</returns>
    public static object GetTargetObjectOfProperty(SerializedProperty property)
    {
        if (property == null) 
            return null;

        string path = property.propertyPath.Replace(".Array.data[", "[");
        object targetObj = property.serializedObject.targetObject;
        string[] elements = path.Split('.');
        foreach (string element in elements)
        {
            if (element.Contains("["))
            {
                string elementName = element.Substring(0, element.IndexOf("["));
                int index = Convert.ToInt32(element.Substring(element.IndexOf("[")).Replace("[", "").Replace("]", ""));
                targetObj = GetEnumerableObjectValue(targetObj, elementName, index);
            }
            else
            {
                targetObj = GetObjectValue(targetObj, element);
            }
        }

        return targetObj;
    }

    private static object GetObjectValue(object source, string name)
    {
        if (source == null)
            return null;

        Type type = source.GetType();

        while (type != null)
        {
            FieldInfo fieldInfo = type.GetField(name, BindingFlags.NonPublic | BindingFlags.Public | BindingFlags.Instance);

            if (fieldInfo != null)
                return fieldInfo.GetValue(source);

            PropertyInfo propertyInfo = type.GetProperty(name, BindingFlags.NonPublic | BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase);

            if (propertyInfo != null)
                return propertyInfo.GetValue(source, null);

            type = type.BaseType;
        }

        return null;
    }

    private static object GetEnumerableObjectValue(object source, string name, int index)
    {
        IEnumerable enumerable = GetObjectValue(source, name) as IEnumerable;

        if (enumerable == null) 
            return null;

        IEnumerator enumerator = enumerable.GetEnumerator();

        for (int i = 0; i <= index; i++)
        {
            if (!enumerator.MoveNext()) 
                return null;
        }

        return enumerator.Current;
    }
}

Now we have the following Inspector GUI. If there is only one possible reference then there will be no dropdown and the singular reference will be serialized. If there is more than one reference to choose from because we dragged a gameobject into the field, it automatically serialize the first reference it finds and will show the dropdown to let the user switch.

We now have the ability to create serializable unity object references but through an interface type. This is a very powerful tool and a big step towards helping us build cleaner software architecture and reduce spaghetti in our game.

Serializing Plain C# Object References

While we may be able to now serialize references in which the object inherits from UnityEngine.Object, what about plain C# object references? Our SerializableUnityRef will not work for those.

You may already know about this, but Unity will serialize plain C# objects and struct types using [SerializeField] as long as you mark the non-abstract class or struct with [System.Serializable].

[System.Serializable] // <-- This is needed for Serializing this type in the inspector
public class Ability
{
    // Quick tip: you can target the backing field of C# properties using "field:"
    [field: SerializeField]
    public string Name { get; private set; }

    [field: SerializeField]
    public int Cost { get; set; }
}

public class Test : MonoBehaviour
{
    [field: SerializeField]
    public Ability InherentAbility { get; private set; }

    [SerializeField]
    public List<Ability> Abilities;
}

This gives us the following in the inspector:

This is nice but we are not utilizing the power of interfaces here. Let's modify our Ability class and the references in our component so that we use interfaces/abstraction:

// I used an abstract class but this could also be an interface
public abstract class Ability
{
    [field: SerializeField]
    public string Name { get; private set; }

    [field: SerializeField]
    public int Cost { get; set; }
}

[System.Serializable]
public class FlyAbility : Ability
{
    public float MaxHeight = 1000;
}

[System.Serializable]
public class ExtraJumpsAbility : Ability
{
    public int ExtraJumps = 1;
}

public class Test : MonoBehaviour
{
    [field: SerializeField]
    public Ability InherentAbility { get; private set; }

    [SerializeField]
    public List<Ability> Abilities;
}

Not so great anymore, we lost our serialization:

In order to serialize plain C# objects by reference, we need to use Unity's [SerializeReference] attribute. It even works on List types allowing for serializing lists of different concrete element types. However, with this new attribute alone we still have a problem, the editor does not know how to serialize unset values because it obviously does not know what the concrete types we want.

Short of using [ContextMenu] to add options to the "three dots" component menu to add specific instances of abilities to the list or set the InherentAbility field, Unity expects you to use the [SerializeReference] attribute in conjunction with a custom editor script. Well, luckily for us someone has already implemented this for us so we don't need to do it ourselves. Simply grab the [SubclassSelector] attribute from this github user's repo : https://github.com/mackysoft/Unity-SerializeReferenceExtensions (see url for installation steps).

With the package installed, the [SubclassSelector] attribute allows us to use the same code we wrote above and easily add support for a search menu to assign (and even swap out) the concrete instances for [SerializeReference] fields directly in the inspector.

public class Test : MonoBehaviour
{
    [field: SerializeField, SubclassSelector]
    public Ability InherentAbility { get; private set; }

    [SerializeField, SubclassSelector]
    public List<Ability> Abilities;
}

Now we have successfully serialized our plain C# objects via interface/abstract class reference and we have a neat little tool to assign them in the inspector! The only thing we still cannot serialize via interface is structs but that's ok.

Decoupling Communication (Events)

Smart references solve the dependency problem when you strictly need to interact with a specific object (like a Turret shooting an IDamageable). But what about events?

When the player dies, the UIManager needs to show the game over screen, the AudioManager needs to play sad_trombone.mp3, and the AchievementManager needs to log a death. If your PlayerHealth script holds references to all three of those systems, it's now coupled to all of them. The player shouldn't know or care that these other systems exist.

This is where an Event Bus comes in. An Event Bus is a centralized hub for communication. Instead of objects talking directly to each other, they speak to the bus and the bus broadcasts those events.

Building a Simple Generic Global Event Bus

We can create a lightweight, type-safe Event Bus using C# delegates and a static dictionary. This allows any system to subscribe to a specific type of event without knowing who triggers it.

// an empty interface so we can constrain what qualifies as event data
public interface IEventData { }

public struct PlayerDamagedEventData : IEventData 
{
    public int DamageAmount;
    public int CurrentHealth;
}

Now, we build the Event Bus itself. We'll use a static generic class. The compiler will generate a unique static instance for every distinct type of EventBus<T>, meaning we don't need to manage a massive dictionary of types.

public static class EventBus<T> where T : IEventData
{
    public static event Action<T> OnEventRaised;

    public static void Subscribe(Action<T> handler)
    {
        OnEventRaised += handler;
    }

    public static void Unsubscribe(Action<T> handler)
    {
        OnEventRaised -= handler;
    }

    public static void Raise(T eventData)
    {
        OnEventRaised?.Invoke(eventData);
    }
}

With this architecture, the PlayerHealth script just raises the event on the EventBus<PlayerDamagedEventData> channel when it takes damage. Over in the other systems that need to wait for a damage event, you simply subscribe to the event. Each system only knows about the EventBus<PlayerDamagedEventData> event, but they don't have any direct dependencies on each other.

public class HealthUI : MonoBehaviour
{
    private void OnEnable()
    {
        EventBus<PlayerDamagedEventData>.Subscribe(EventBus_PlayerDamagedEvent);
    }

    private void OnDisable()
    {
        EventBus<PlayerDamagedEventData>.Unsubscribe(EventBus_PlayerDamagedEvent);
    }

    private void EventBus_PlayerDamagedEvent(PlayerDamagedEventData eventData)
    {
        Debug.Log($"Player took {eventData.DamageAmount} damage! Health is now {eventData.CurrentHealth}.");
    }
}

The Instance Specific Event Problem

This is a great solution for a event bus system that deals with global events however, as you may have already surmised, it falls apart completely if you have 50 Goblins in a scene and the UI only needs to track the health of the specific one you currently have targeted. If you use a global CharacterDamagedEvent, every CharacterHealthBarUI element in the game will update when any goblin takes damage.

As we can see, our event bus is better suited for global events. What we actually want is instance specific events. Fortunately, because of the work we did in the first half of the article, we have an incredibly clean way to handle this.

public interface IDamageable
{
    // The event is now part of the contract
    event Action<float> OnDamageTaken;
    event Action OnDeath;

    void TakeDamage(int amount);
}

Now, your concrete implementation (like CharacterHealth) implements the event:

public class CharacterHealth : MonoBehaviour, IDamageable
{
    public event Action<float> OnDamageTaken;
    public event Action OnDeath;

    private int _health = 100;

    public void TakeDamage(int amount)
    {
        _health -= amount;
        OnDamageTaken?.Invoke(_health);

        if (_health <= 0) 
            OnDeath?.Invoke();
    }
}

Then, over in the CharacterHealthBarUI script, you use the SerializableUnityRef we built earlier to inject the specific instance via the inspector, and subscribe directly to its interface event(s).

public class CharacterHealthBarUI : MonoBehaviour
{
    // Drag the CharacterHealth, BossHealth, CarHealth or a any other IDamageable here!
    [SerializeField]
    private SerializableUnityRef<IDamageable> _damageable;

    private void OnEnable()
    {
        if (_damageable.HasValue)
            _damageable.Value.OnDamageTaken += UpdateFillBar;
    }

    private void OnDisable()
    {
        if (_damageable.HasValue)
            _damageable.Value.OnDamageTaken -= UpdateFillBar;
    }

    private void Damageable_OnDamageTaken(float newHealth)
    {
        // update health bar fill amount ...
    }
}

Why this is powerful: The UI is listening to a specific instance, but it is still completely decoupled from the concrete class. It doesn't know exactly what it's referencing only that it's an IDamageable and adheres to that contract.

Instance Specific EventBus

We know that things like CharacterAnimator or CharacterAudio need to subscribe to the IDamageable instance OnDamageTaken event (maybe to play a sound on damage or death). However, CharacterAudio might also need to listen to CharacterMovement events or other events specific to the character instance and in a complex gameobject hierarchy it might be annoying to hook up all the references in the inspector. You might find yourself saying "I need a centralized hub (a bus) that is specific to the gameobject instance so that I don't have to manage many different dependencies on a complex prefab hierarchy. I'll just use the event bus pattern I learned earlier but localize it to my gameobject instance." and implementing a solution like so:

public class CharacterEventBus : MonoBehaviour
{
    public event Action<int> OnDamageTaken;
    public void RaiseDamageTaken(int amount) => OnDamageTaken?.Invoke(amount);

    public event Action OnDeath;
    public void RaiseDeath() => OnDeath?.Invoke();

    // keep adding events here as they come up in development ...
}

Now, your character's components just require the CharacterEventBus reference and they just need to ask the CharacterEventBus to fire their events out into the void and whoever is listening will hear them.

The hidden problem with this approach: While it may seem that we cleaned up our dependencies even further, all we did is move them all into a single class CharacterEventBus. In my professional opinion, this is the equivalent of a teenager "cleaning" his room by shoving everything in the closet.

For instance based events, using the interface design from earlier and letting the classes responsible for those events fire their own events is the better approach. It may be annoying to hook up all the dependencies on the gameobject/prefab but this is one time setup work and will save you time in the long run by increasing dependency visibility and allow you to easily see dependencies for a given object at a glance.

Instead of the teenager shoving everything inside the closet, as he gets new stuff he will keep things logically together (video games and film near the TV, books near the bed or desk where they are read, shoes near the door, etc).

A complex hierarchy with lots of component dependencies is like a room with a lot of stuff, it's not necessarily messy because there's lots of stuff everywhere, it's messy because of a lack of architecture and logic in where the stuff is placed (clothes on the floor, video games far from the TV, etc).

Serializing Events

While C# Action delegates are incredibly fast and type-safe, they exist entirely in code. If a level designer wants a door to open when a boss dies, they would have to ask a programmer to write a custom script to subscribe to the boss's OnDeath event. This slows down development. If only the designer could subscribe and tie the event to the specific Door's Open() function without needing the developer to step in. Well luckily for us you can do that in Unity by using the UnityEvent type.

Unlike standard C# events, UnityEvent can be serialized and displayed in the Inspector. This allows designers to drag and drop object references and select methods from a dropdown menu, wiring up complex interactions visually.

Let's look at an example:

public class BigBadBoss : MonoBehaviour
{
    [SerializeField] 
    private UnityEvent<int> _onDamageTaken;

    [SerializeField] 
    private UnityEvent _onDeath;

    private int _health = 1000;

    public void TakeDamage(int amount)
    {
        _health -= amount;
        _onDamageTaken?.Invoke(_health);

        if (_health <= 0) 
            _onDeath?.Invoke();
    }
}

At first glance you might think that this is great and that you can just change all your events to use UnityEvent instead of Action. Don't Do This! While using UnityEvent is incredibly powerful for letting designers and programmers to quickly hook up event logic without any code changes, they come with a few trade-offs that you should keep in mind:

Performance: UnityEvent is slightly slower than a standard C# Action because it relies on reflection under the hood. For events that fire every frame (like in the Update() loop), you should stick to C# Action. For infrequent events (like OnDeath), UnityEvent is perfectly fine.
Traceability: If you use C# Action, you can easily use "Find All References" in your IDE to see exactly what is listening to that event. With UnityEvent, the connections are hidden inside scene or prefab files, which reduces code visibility and can make debugging a little harder if you overuse them.

On a separate note, you might have noticed that using UnityEvent means that you would have to replace the C# Action members in your interfaces. This is not true, instead you should be using UnityAction instead of C# Action. Under the hood, UnityAction is just a thin wrapper or alias for a standard C# delegate, meaning they compile down to the same underlying code and perform identically during invocation.

What if you want to use UnityAction for code subscriptions and still leverage UnityEvent for serializing the same events. You can do this using the following pattern:

public interface IDamageable
{
    event UnityAction<float> OnDamageTaken;
    event UnityAction OnDeath;

    void TakeDamage(int amount);
}

public class CharacterHealth : MonoBehaviour, IDamageable
{
    public event UnityAction<float> OnDamageTaken;

    // we subscribe using the UnityAction which adds it to the UnityEvent and we always Invoke the UnityEvent.
    [SerializeField]
    protected UnityEvent<IInteractor, bool> _onDeath;
    public event UnityAction OnDeath { add => _onDeath?.AddListener(value); remove => _onDeath?.RemoveListener(value); }

    private int _health = 100;

    public void TakeDamage(int amount)
    {
        _health -= amount;
        OnDamageTaken?.Invoke(_health);

        if (_health <= 0) 
            _onDeath?.Invoke();
    }
}

This way we have the best of both worlds. We keep the event UnityAction OnDeath which follows our contract and we can subscribe through code. We also get the ability to add serialized event callbacks to the same event in the inspector!

The Golden Rule: Use UnityAction (not Action) for when systems need to talk to each other through code. Use UnityEvent for exposing design-specific logic to your design team and avoid using it for event callbacks that are called from performance critical code paths (like Update()). Use both if you need both but avoid using serialized UnityEvent for performance critical code paths.

Conclusion

By using interfaces for dependencies, we have went from tightly coupled architecture to a more loosely coupled one. We can listen to events fired from concrete implementations without needing a reference to each concrete type and what's even better is that we can do this and also take advantage of Unity's built in inspector serialization for dependency injection.

This strict isolation is the exact prerequisite needed to break your game down into independent modules. In the next post, we will discuss Assembly Definitions (asmdefs) and how you can "break off" a part of your game and reuse it as it's own separate module.

Unity Foundational Architecture: Managing Global State

Daniel Rinaldi (TenaciousDan) — Thu, 23 Jul 2026 03:28:01 +0000

Introduction

Every Unity developer eventually hits the exact same wall: how do I get my UI script to talk to my Game Manager without turning my codebase into a tangled web of dependencies? Managing global state is a fundamental challenge in game architecture, and the internet is full of conflicting, often dogmatic advice on how to handle it.

In this article, we are going to look at some popular approaches to managing global state: Static Constants, Singletons and Service Locator.

Before we start though, I encourage you to read some of my previous blog posts in this series on project scaffolding or, even more crucial to some sections in this article, the bootstrapping process.

Constants

Not every piece of global data needs a instance to live in, interfaces, or an initialization phase. Some data is constant and never changes at runtime (constants). These constants are usually defined with static readonly or const (at least they should be if they never change).
Example:

public static class MathConstants
{
    public const float MilesToKm = 1.60934f;
}

public class CharacterAnimationController : MonoBehaviour
{
    // we must use static readonly instead of const here because we need to generate the SpeedHash from the string literal.
    public static readonly int SpeedHash = Animator.StringToHash("Speed");
}

Constants are also tied to the type they are defined in. So to keep things neat, you should only define constants where appropriate. Meaning if you have a constant for the max networked inventory slot capacity, this shouldn't be defined in a class called NetworkedConstants and instead should reside inside the class that represents the NetworkedInventory which needs this data. In fact, if this is the only class that needs this data, you can even make it private although it's perfectly fine to make it public as well if there's a need for it in other scripts as long as you are not just creating dependencies just for accessing the constant field.

Constants are also tied to the type they are defined in. So to keep things neat, you should only define constants where appropriate. Meaning if you have a constant for the max networked inventory slot capacity, this shouldn't be defined in a class called NetworkedConstants and instead should reside inside the class that represents the NetworkedInventory and needs this data. In fact, if this is the only class that needs this data, you can even make it private although it's perfectly fine to make it public as well if there's a need for it in other scripts.

Magic strings are an architectural vulnerability. If someone changes the setting name from AudioSettings.SFXVolume to AudioSettings.SFXVolum (missing the e), the compiler will not warn you. If the programmer accidentally mistypes the string, the compiler will not warn you. Your code will compile perfectly, but the SetFloat call will silently fail to update the correct data at runtime, breaking your game's logic.

By transforming our magic strings into named constants we get:

No Typos: It prevents bugs caused by misspelling a hardcoded string in multiple files.
Code Completion: IDE auto-complete works perfectly with named constants.

Singletons & Services

Every Unity developer eventually hits the "Singleton Wall." It usually starts innocently enough, you usually need a single instance of some sort of "manager"(like a GameManager or AudioManager). The general common rules for these managers are the following:

Only ONE instance should ever be created at any given time (a single source of truth)
Accessible from anywhere
Needs to be initialized as the game starts and when hitting play in the editor before your gameplay scripts run and try to access it
May or may not need to survive scene loads

Let's start by addressing the elephant in the room: the Singleton. It has become a bit of a trend in software engineering circles to label the Singleton as an "anti-pattern." It is true that they have downsides. Specifically, they make mocking dependencies much harder, which can be a headache for unit testing.

But let's be realistic. For many developers, and especially for indie devs, the Singleton is incredibly valuable. It is easy to pick up, exceptionally fast to implement, and cleanly solves the immediate problem of global access. The singleton pattern is very useful and can sometimes also be seen in other patterns like Factory or even the Service Locator itself (part of building a service locator is making a single singleton: the "locator"). It is a widely used pattern for a reason. You should always choose your solutions based on your project's needs and its long term health.

In any case, we will go over how to build and implement both solutions, cut down on boiler plate code using generics, discuss how to make use of Unity's SerializeField for dependency injection, and what a Singleton lacks that would make you choose a ServiceLocator instead.

Now, there is some truth behind the rumors though as the service locator pattern does offer more utility and flexibility. However, some indie developers are content with the good old singleton pattern for their projects. This is totally fine, you should choose your solution based on your project's needs and its long term health. The Singleton pattern also requires less architecture & planning which can be beneficial for small teams, game jam projects, or quick prototypes. In any case, we will cover how to build and implement both solutions, cut down on boiler plate code using generics, and what a Singleton lacks that you'd want a ServiceLocator for.

Singleton

Problem & Intent

We all know the problem, we want a single global instance (source of truth) for a given type. The singleton pattern is a creational design pattern that ensures a class has only one instance, while also providing a static global access point to that instance.

Solution

All implementations of the Singleton pattern have these two things in common.

Make the default constructor private, to prevent other objects from using the new operator with the Singleton class. This gets a bit more complex when it comes to MonoBehaviours as we will have to check the instance count.
Create a static creation method that acts as a constructor. Under the hood, this method calls the private constructor to create an object and stores it in a static field. All following calls to this method return the cached object.

What the Singleton Pattern Lacks

The core issue is the lack of inheritence and lose coupling. It is the main reason behind the following downsides of the pattern:

It may be difficult to unit test the client code of the Singleton pattern because many test frameworks rely on inheritance when producing mock objects. Since the constructor of the singleton class is private and more importantly you access the instance statically by type name, you will need to think of a creative way to mock the singleton. If you need robust unit testing and the ability to mock instances, you should opt for the Service Locator pattern.
One other thing to note is the tight coupling to the Singleton's concrete type. In a large scale application this becomes much much more important. If you really need the lose coupling, you should opt for the Service Locator pattern.

Common Misuse

Developers frequently use singletons to bypass passing parameters, turning them into a global access point for arbitrary data and unnecessarily polluting the global scope. My main advice with Singletons is just try not to overuse them and first see if you can architect a solution by creating the least possible amount of Singletons. Luckily, I feel like most experienced devs will quickly learn this and consider this when working with Singletons ... I hope :).

Implementation

Let's start with the simplest implementation. We will create a singleton out of a plain old C# object (POCO).

public sealed class GameManager 
{
    private static readonly object _mutex = new object();
    private static volatile GameManager _instance;

    // ensure we are the only ones creating a new object
    private GameManager() 
    { 
        // initialize the GameManager here...
    }

    // Static global point of access
    public static GameManager Instance => GetOrCreate();
    public static GameManager GetOrCreate()
    {
        // double-checked locking pattern (thread lock)
        if (_instance == null)
        {
            lock (_mutex)
            {
                if (_instance == null)
                    _instance = new GameManager();
            }
        }

        return _instance;
    }

    // other non static methods containing business logic here...
}

// A client can call business logic from anywhere using the Singleton's type...
GameManager.Instance.XYZ();

Pretty simple right? Sure, but rewriting this logic for every Singleton is annoying, let's try to mitigate the writing of boiler plate code by making our solution generic.

public abstract class Singleton<T> where T : class
{
    private static readonly object _mutex = new object();
    private static volatile T _instance;

    private static readonly ConstructorInfo _cachedConstructor;

    // The static constructor runs exactly once per unique 'T'
    static Singleton()
    {
        _cachedConstructor = typeof(T).GetConstructor(
            BindingFlags.Instance | BindingFlags.NonPublic,
            null, 
            Type.EmptyTypes, 
            null
        );

        if (_cachedConstructor == null)
        {
            throw new InvalidOperationException(
                $"To enforce singleton behavior, {typeof(T).Name} must have a private or protected parameterless constructor.");
        }
    }

    // Static global point of access
    public static T Instance => GetOrCreate();
    public static T GetOrCreate()
    {
        // double-checked locking pattern (thread lock)
        if (_instance == null)
        {
            lock (_mutex)
            {
                if (_instance == null)
                    _instance = (T)_cachedConstructor.Invoke(null);
            }
        }

        return _instance;
    }
}

// Reduced boilerplate...
public sealed class GameManager : Singleton<GameManager>
{
    // Private constructor prevents client from calling 'new GameManager()'
    private GameManager() { }

    // other non static methods containing business logic here...
}

// Client usage...
GameManager.Instance.XYZ();

Now that we've completed the POCO singleton, let's take a look at a MonoBehaviour singleton implementation. Why? Dependency injection using serialized fields, that's why.

This is the typical MonoBehaviour singleton you'd find by doing a quick google search.

public sealed class GameManager : MonoBehaviour
{
    public static GameManager Instance { get; private set; }

    private void Awake()
    {
        if (Instance != null && Instance != this)
        {
            // Destroy duplicate instances
            Destroy(gameObject);
            return;
        }

        Instance = this;

        // Optional: Keep this object alive across scene changes
        DontDestroyOnLoad(gameObject); 
    }
}

While this works for quick & simple prototypes and throw away code, it quickly falls apart in production. Putting this into a real-world project is like driving a car without insurance, it works fine until you hit an engine edge case.

Here are some of the problems you can encounter with this naive approach:

The Execution Order Race Condition : Unity runs script Awake() cycles in an unpredictable, random order. If a normal gameplay script runs its Awake() before your GameManager executes its own, calling GameManager.Instance will return null and could crash your game on frame one.
- Solution : By explicitly locking the base class into [DefaultExecutionOrder(-50)], we guarantee that every singleton in the project initializes before any standard script (which defaults to 0) even wakes up. In an edge case, you can always set a lower value for DefaultExecutionOrder on concrete classes.
Accessing the Instance After its Been Cleaned Up : When you exit a Unity game, the engine destroys GameObjects in a random order. If a regular script tries to log data or clean up references inside its OnDestroy() or OnDisable() methods, it might call the Singleton instance again after Unity has already deleted it. If you are supporting lazy instantiation, this triggers a ghost lazy-reinstantiation loop, spawning leaky objects in a dying scene and causing potential errors or crashes in the application cleanup step.
- Solution : We manage a static HasQuit flag. In OnApplicationQuit(), we set this to true. If any script tries to access the singleton during the shutdown sequence, the Instance property returns null instead of spawning a zombie instance. This can lead to null refs in cleanup methods like OnDisable() and OnDestroy() so you should simply check the flag before using the Instance property in these cases.
Editor - Fast Enter Play Mode Initialization Bug : To speed up compile times, modern Unity projects heavily rely on disabling Domain Reload under Enter Play Mode Settings. However, skipping the domain reload means static fields are never wiped when you press Stop. The next time you press Play, Instance still points to the dead object from your previous session, causing your fresh script to immediately destroy itself.
- Solution : We use a C# static constructor and hook into EditorApplication.playModeStateChanged callback. This automatically intercepts the in-editor play state switch and resets HasQuit right before the runtime boots up, ensuring compatibility with Fast Enter Play Mode in Editor.
Lack of Architectural Control - Eager vs. Lazy : Our simple, naive GameManager monobehaviour singleton forces us to use the Eager loading paradigm. Meaning they must be manually dragged into every scene. This is usually fine for most Unity devs. In some rare cases though, you may want Lazy Loading meaning that the singleton's gameobject will be spawned in whenever the Instance is accessed.
- Solution : We create a custom MBSingletonOptionsAttribute that allows us to configure which instantiation paradigm a singleton should use. So either lazily spawn an empty container and build the gameobject instance ourselves through code, or let Unity automatically instantiate a fully pre-configured gameobject that exists in the scene and fail (returning null) otherwise.
Boilerplate Code : As usual, there is still the issue of boilerplate code that we don't want to rewrite for each concrete type.
- Solution : We do the same thing that we did for the POCO singleton and use generics to create a generic base class that handles all the generic singleton logic.

Alright let's start implementing a solution that solves our problems:

// other using statements...

#if UNITY_EDITOR
using UnityEditor;
#endif

// singletons should execute before "normal" scripts which have DefaultExecutionOrder = 0
[DefaultExecutionOrder(-50)]
public abstract class MBSingleton<T> : MonoBehaviour where T : MonoBehaviour
{
    private static T _instance;

    [SerializeField, Tooltip("Destroy this object when a new scene is loaded.")]
    private bool _destroyOnLoad = false;

#if UNITY_EDITOR
    static MBSingleton()
    {
        EditorApplication.playModeStateChanged -= OnPlayModeStateChanged;
        EditorApplication.playModeStateChanged += OnPlayModeStateChanged;
    }
    static void OnPlayModeStateChanged(PlayModeStateChange playModeState)
    {
        if (playModeState == PlayModeStateChange.ExitingEditMode)
        {
            HasQuit = false;
        }
    }
#endif

    protected MBSingleton() { }

    public static bool IsInitialized => _instance != null;

    /// <summary>
    /// True if application is quitting. When Unity quits it destroys game objects in a random order and this can create issues when working with singletons. <br />
    /// As such, you should check "if (!YourSingleton.HasQuit)" before using your singleton in cleanup methods like OnDisable, OnDestroy, etc...
    /// </summary>
    public static bool HasQuit { get; private set; }

    public static T Instance => GetOrCreate();
    public static T GetOrCreate(GameObject gameObject = null)
    {
        if (HasQuit) 
            return null;

        // no need for double checked locking pattern as MonoBehaviours are only created on the main tread
        if (_instance == null)
            Create(gameObject);

        return _instance;
    }

    private static void Create(GameObject gameObject = null)
    {
        // we'll implement this soon, keep reading...
    }

    /// <summary>
    /// Override this method to ensure that you run Initialization logic for your singleton only once (this will not be invoked on accidental duplicates before they are destroyed).
    /// </summary>
    protected virtual void Initialize()
    {
        //
    }

    protected virtual void Awake()
    {
        // we must check backing field (_instance) here because if null we want to call GetOrCreate() and pass it this gameObject
        if (_instance == null)
            GetOrCreate(gameObject);
        else
        {
            // an instance already exists and this is a duplicate, destroy it
            Destroy(gameObject);
            return;
        }

        DestroyOnLoad = _destroyOnLoad;
    }

    protected virtual void OnDestroy()
    {
        _instance = null;
    }

    protected virtual void OnApplicationQuit()
    {
        // When Unity quits it destroys game objects in a random order and this can create issues for monobehaviour singletons. 
        // So we prevent possible lazy re-instatiation and access to the instance when the application quits to prevent problems.
        HasQuit = true;
    }

    public bool DestroyOnLoad
    {
        get => _destroyOnLoad;
        set
        {
            _destroyOnLoad = value;
            if (_destroyOnLoad)
            {
                transform.SetParent(null);
                Scene activeScene = SceneManager.GetActiveScene();
                if (gameObject.scene != activeScene)
                    SceneManager.MoveGameObjectToScene(gameObject, activeScene);
            }
            else
            {
                transform.SetParent(null);
                DontDestroyOnLoad(gameObject);
            }
        }
    }
}

What this gives us is:

A MonoBehaviour that we can attach to a GameObject and a variable to control whether or not we want this singleton to live and die with the scene or whether we want it to survive scene load/unloads and exist in the persistent DontDestroyOnLoad scene. We also give the option to switch at runtime.
Static memory management and cleanup in editor for fast enter play mode.
A default DefaultExecutionOrder of -50 to allow us to execute before most normal scripts.
A virtual Initialize() method that can be used in place of Awake() for initialization. Why? Because when a new gameobject is spawned the Awake method is called even if it's a duplicate and our code will destroy it. We haven't implement the logic that calls it yet but the idea is to have this method for initialization on the singular "true" instance.
A Create(GameObject) method that we can either pass in the GameObject (for eager loading) or null (for lazy loading). To be honest, I mostly exclusively use Eager loading when it comes to monobehaviour singletons, mostly for the easy setup and dependency injection (serialized fields). However, it doesn't hurt to support both paradigms here.

Now, let's implement the heart of our MBSingleton script, the Create(GameObject) function as well as a LazyFallbackInstantiation(GameObject) function to allow us to Lazily construct our MBSingleton gameobject and configure any parameters.

private static void Create(GameObject gameObject = null)
{
    if (gameObject != null && gameObject.scene.name != null)
    {
        _instance = gameObject.GetComponent<T>();
        (_instance as MBSingleton<T>).Initialize();
        return;
    }

    T[] existingInstances = FindObjectsByType<T>();
    if (existingInstances.Length > 0)
    {
        _instance = existingInstances[0];

        for (int i = 1; i < existingInstances.Length; ++i)
        {
            DestroyImmediate(existingInstances[i]);
        }

        return;
    }

    Type typeofT = typeof(T);

    // handle how the user wants this type to be loaded ...
    MBSingletonOptionsAttribute typeOptionsAttr = typeofT.GetCustomAttribute<MBSingletonOptionsAttribute>();

    // eager loading (default) : the gameobject instance will be created when it's gameobject is loaded into memory by Unity
    if (typeOptionsAttr == null || typeOptionsAttr.loadType == EInstanceLoadingType.Eager)
        return;

    // lazy loading : create the gameobject instance for the user if it doesn't already exist (instance will always create a new GameObject)
    if (typeOptionsAttr.loadType == EInstanceLoadingType.Lazy)
    {
        // create a new GameObject that will house the singleton instance (lazy instantiation) ...
        string goNamePostFix = " (Lazy)";

        // if it's a prefab reference, then instantiate the prefab
        if (gameObject != null && gameObject.scene.name == null && gameObject.GetComponent(typeofT) != null)
        {
            // need to set instance before Instantiate() call otherwise we'll have an infinitely recursive situation in Awake()
            if (gameObject.TryGetComponent(out _instance))
            {
                gameObject = Instantiate(gameObject);
                gameObject.name += goNamePostFix;
                _instance = gameObject.GetComponent<T>();
                (_instance as MBSingleton<T>).Initialize();

                return;
            }
            else
                _instance = null;
        }

        // create an empty gameobject and attach this component.
        if (_instance == null)
        {
            gameObject = new GameObject(typeofT.Name + goNamePostFix, typeofT);
            T singletonComponent = gameObject.GetComponent<T>();
            _instance = singletonComponent;

            MBSingleton<T> mbSingleton = singletonComponent as MBSingleton<T>;
            mbSingleton.LazyFallbackInstantiation(gameObject);
            mbSingleton.Initialize();

            return;
        }
    }
}

/// <summary>
/// Override this method if you need to lazily construct the singleton from scratch.
/// </summary>
/// <param name="gameObjectRoot">The instantiated root gameobject.</param>
protected virtual void LazyFallbackInstantiation(GameObject gameObjectRoot)
{
    // to be overriden by subclasses for lazy loading...
}

With this we have a very robust and solid MonoBehaviour Singleton solution that can be used in any project. The best place to eagerly load your monobehaviour singletons are in the bootstrap scene or wherever you do your bootstrapping logic. You can also place MBSingletons in specific scenes so that they are tied to that scene, just remember to set the DestroyOnLoad variable to true so that it will not be persisted in the DontDestroyOnLoad scene.

Service Locator

Problem & Intent

The problem: We want global access to objects (services) and we want lose coupling by making everyone depend on a single global instance to fetch objects by interface/abstract type insetad of concrete type. The Service Locator pattern is an architectual pattern that solves these problems by providing a global point of access to an object instance (service) without tightly coupling users to the concrete class that implements it.

Solution

All implementations of the Service Locator pattern have these things in common.

A static global instance (Singleton) that acts as the middleman and a registry for our services.
A collection of service instances that is managed by our locator and a method to retrieve an instance of a service.
An interface that acts as a contract for our services to ensure they all implement some common functionality that our locator expects of them.

Key Difference from Singleton

If we look at the Singleton, a script is permanently glued to (dependant on) a specific concrete class. If your PlayerHealth script calls AudioManager.Instance.Play("Ouch"), it is hardcoded to depend on that exact AudioManager type. This makes unit testing more difficult because you can't easily swap the real audio manager for a dummy one without changing all the calls in the codebase with your new type.

Common Misuse

The Service Locator can index the services by their concrete type, however this is a common misuse of the pattern and will end up degrading your solution into a more complex singleton pattern which defeats our initial intent. DO NOT use Service Locator if you plan to do this as you are just adding more complexity to your project for no reason (instead just use Singleton). If you are using the Service Locator and creating services then you should also create an interface for each service you create in which you will almost explicitly use to talk to the service. You will be programming to an interface instead of a concrete type which means your dependencies are now losely coupled.

The Downside

While it sounds perfect, the Service Locator has one major downside and ironically it is a result of its greatest strength: hidden dependencies. When you look at a script that uses a Singleton, you immediately see the dependency (GameManager.Instance). With a Service Locator, a script might compile perfectly fine but throw a null reference exception at runtime and, at a glance, it may not be obvious which instance of the service is being used making it difficult to trace. However, if Singletons are causing friction in your project then this downside is an acceptable alternative and with the debugging tools Unity and IDEs offer developers it is often very manageable.

Implementation

Let's start by creating a ServiceLocator class using our Generic Singleton<T> implementation from earlier. While some implementations use a static class, we are going to just make it a singleton to save some time. If you do go the static class route, you have to make the class and every member/function static and you would have to make sure to handle cleanup for when the domain is not reloaded in editor and you re-enter play mode (Fast Enter Playmode).

public sealed class ServiceLocator : Singleton<ServiceLocator>
{
    private readonly Dictionary<Type, IService> _services = new Dictionary<Type, IService>();

    public void Register<T>(T service) where T : IService
    {
        var typeofT = typeof(T);
        if (!_services.ContainsKey(typeofT))
            _services.Add(typeofT, service);
        else
            Debug.LogWarning($"[{nameof(ServiceLocator)}] Service of type `{typeofT}` has already been registered!");
    }

    public void Unregister<T>() where T : IService
    {
        _services.Remove(typeof(T));
    }

    public T Get<T>() where T : IService
    {
        var typeofT = typeof(T);
        if (_services.TryGetValue(typeofT, out var service))
        {
            return (T)service;
        }

        Debug.LogError($"[{nameof(ServiceLocator)}] Service of type `{typeofT}` has not been registered!");
        return default;
    }
}

public interface IService
{
    // Called the moment the service is successfully added to the Locator
    public void OnRegister();
    // Called right before the service is removed from the Locator
    public void OnBeforeUnregister();
    // Called after the service is removed from the Locator
    public void OnUnregister();
}

We will have to register all our services somewhere in our game's code. Again, the best place for this would be where we do our bootstrapping logic. You can make use of Unity's [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)] attribute for pure C# services. If we want to make use of dependency injection through the use of Unity's SerializeField attribute then we need to do this in Awake(). Let's make a script that allows us to register services on startup.

// We want services to be registered before the Awake() of normal scripts fire.
[DefaultExecutionOrder(-10)]
public class ServiceBootstrapper : MonoBehaviour
{
    [Header("Services")]
    [SerializeField] 
    private GameManager _gameManager;
    [SerializeField] 
    private AudioManager _audioManager;

    private void Awake()
    {
        // register our services here ...

        YourService yourService = new();
        Register<IYourService>(yourService);

        ServiceLocator.Register<IGameService>(_gameManager);
        ServiceLocator.Register<IAudioService>(_audioManager);
    }
}

// Now instead of this (tight coupling!):
GameManager.Instance.XYZ();

// We now do this (lose coupling):
ServiceLocator.Get<IGameService>().XYZ();

What we now have is a proper ServiceLocator implementation with the following traits:

A static global instance that will hold a reference to a dictionary of services by type.
A way to add to our collection of services using our Register<T>(T service) function.
A way to remove from our collection of services using our Unregister<T>() function.
A way to fetch from our collection of services using our Get<T>() function.
We have a class that handles the bootstrapping process of registering our services and gives us control over the registration order as well.
A base interface for all our services so that they can all abide to a common contract. Currently, the only methods that we enforce is two callback methods OnRegister(), OnBeforeUnregister() and OnUnregister() to give our services some hooks into the service registration process.
When creating a service, we can define a unique interface to use as our contract for our service (provided it inherits from the IService interface) and then we can swap out our services at any time as long as the new instance implements the same interface. This is very useful for unit testing where we'd want to mock a service and alter its functionality for testing.

What's neat about this pattern is that you can easily convert anything into a service, even the Singletons we made earlier. You simply have to make an interface for the singleton to inherit from and then register it with the locator.

That's pretty much it. There's a bit more setup involved than what we had with singletons (we need to create the interface and the concrete type and then we need to add it to our bootstrapper to register it), but on larger scale projects with bigger teams that require you to do a lot of mocking/unit testing this pattern can save you some headaches down the line.

Conclusion

Managing global state doesn't have to mean turning your Unity project into a tangled web of dependencies. The key is choosing the right architectural tool for the specific problem at hand rather than rigidly adhering to a single doctrine.

When data never changes at runtime, Constants keep your codebase clean, eliminate typo-induced bugs from magic strings, and provide full IDE autocompletion without any instantiation overhead.

For dynamic global systems, the choice between a Singleton and a Service Locator ultimately comes down to the scale and needs of your game. Despite the criticism it sometimes receives in software engineering circles, the Singleton pattern remains incredibly valuable—especially for indie developers. It is quick to implement, easy to pick up, and solves the immediate need for global access efficiently without over-engineering your prototype.

However, as a project grows in complexity, the Singleton's limitations become more apparent. If your architecture demands loose coupling, interface-driven design, and robust unit testing with mock objects, the Service Locator provides the flexibility your codebase needs to scale healthily.

There is no one-size-fits-all answer. The only true mistake is treating global access as a lazy shortcut to avoid passing parameters. By evaluating the long-term health of your project and balancing the need for testability against the realities of rapid development, you can build a foundation that empowers you to focus on what actually matters: shipping your game.

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 during the first frame in a build, assuming the Bootstrap scene is loaded first, 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).

The final application control flow should look like this:

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.

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

First we'll create our .gitignore and .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

Next, let's map out our 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, camera management, 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: Loose Coupling, Interfaces & Events

Table of Contents:

Introduction

The Power of Interfaces

The Unity Serialization Wall

Building a Serializable Unity Object Reference

Serializing Plain C# Object References

Decoupling Communication (Events)

Building a Simple Generic Global Event Bus

The Instance Specific Event Problem

Instance Specific EventBus

Serializing Events

Conclusion

Unity Foundational Architecture: Managing Global State

Table of Contents:

Introduction

Constants

Singletons & Services

Singleton

Problem & Intent

Solution

What the Singleton Pattern Lacks

Common Misuse

Implementation

Service Locator

Problem & Intent

Solution

Key Difference from Singleton

Common Misuse

The Downside

Implementation

Conclusion

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