unity-project-architecture

Unity Project Architecture

Overview

Unity makes it easy to put everything in one MonoBehaviour that finds its collaborators with FindObjectOfType and a static Instance. That works for a jam and collapses after a few months: nothing is testable, compile times grow, and scene order decides behaviour. Structure the project as assemblies with a dependency direction, plain C# for rules, thin components for engine glue, and data in assets.

Core principle: Rules in plain C# assemblies, components as adapters, data in ScriptableObjects, dependencies passed in. The repository's existing layout and DI choice win.

Assemblies and direction

Game.Core      (noEngineReferences: rules, math, state machines, save DTOs)
   ↑
Game.Runtime   (MonoBehaviours, ScriptableObjects, adapters; references Core)
   ↑
Game.UI        (views and presenters; references Runtime/Core, never the reverse)
Game.Editor    (includePlatforms: Editor; tools, validators)
Tests.EditMode / Tests.PlayMode (test assemblies; see unity-testing)

{
  "name": "Game.Core",
  "rootNamespace": "Game.Core",
  "references": [],
  "noEngineReferences": true,
  "autoReferenced": false
}

• An assembly per layer keeps compile times down and makes a wrong-way reference a compile error instead of a review comment.
• Game.Core with noEngineReferences: true can be compiled and tested by plain dotnet test when the editor is missing (testable-game-logic).
• Gameplay never references UI; UI observes gameplay through events.

Components

// ❌ lookups every frame, public mutable fields, rules inside the component
public class Enemy : MonoBehaviour {
    public int hp = 100;
    void Update() {
        var player = GameObject.Find("Player");
        if (Vector3.Distance(transform.position, player.transform.position) < 5) GetComponent<Animator>().SetTrigger("Attack");
    }
}

// ✅ cached references, serialized private fields, rule delegated to plain C#
[RequireComponent(typeof(Animator))]
public sealed class EnemyView : MonoBehaviour {
    static readonly int AttackHash = Animator.StringToHash("Attack");
    [SerializeField] EnemyDefinition definition;
    Animator _animator; EnemyBrain _brain; ITargetProvider _targets;

    public void Construct(ITargetProvider targets) => _targets = targets;
    void Awake() { _animator = GetComponent<Animator>(); _brain = new EnemyBrain(definition.AttackRange); }
    void Update() {
        if (_brain.ShouldAttack(transform.position, _targets.PlayerPosition)) _animator.SetTrigger(AttackHash);
    }
}