Unity Game Engine Architecture Guide

This guide provides Unity-specific guidance for solution architecture generation.

Unity-Specific Questions

1. Unity Version and Render Pipeline

Ask:

Guidance:

Record ADR: Unity version and render pipeline choice

2. Architecture Pattern

Ask:

Guidance:

Record ADR: Architecture pattern choice and justification

3. Data Management Strategy

Ask:

Guidance:

Record ADR: Data management approach

Unity-Specific Architecture Sections

Game Systems Architecture

Components to define:

Unity-specific patterns:

// Singleton GameManager pattern
public class GameManager : MonoBehaviour
{
    public static GameManager Instance { get; private set; }

    void Awake()
    {
        if (Instance == null) Instance = this;
        else Destroy(gameObject);
        DontDestroyOnLoad(gameObject);
    }
}

// ScriptableObject data pattern
[CreateAssetMenu(fileName = "EnemyData", menuName = "Game/Enemy")]
public class EnemyData : ScriptableObject
{
    public string enemyName;
    public int health;
    public float speed;
    public GameObject prefab;
}

Unity Events and Communication

Ask:

Guidance:

Pattern:

// Event-driven damage system
public class HealthSystem : MonoBehaviour
{
    public UnityEvent<int> OnDamaged;
    public UnityEvent OnDeath;

    public void TakeDamage(int amount)
    {
        health -= amount;
        OnDamaged?.Invoke(amount);
        if (health <= 0) OnDeath?.Invoke();
    }
}

Performance Optimization

Unity-specific considerations:

Target Performance:

Testing Strategy

Unity Test Framework:

Example:

[UnityTest]
public IEnumerator Player_TakesDamage_DecreasesHealth()
{
    var player = new GameObject().AddComponent<Player>();
    player.health = 100;

    player.TakeDamage(20);

    yield return null; // Wait one frame

    Assert.AreEqual(80, player.health);
}

Source Tree Structure

Unity-specific folders:

Assets/
├── Scenes/              # All .unity scene files
│   ├── MainMenu.unity
│   ├── Level1.unity
│   └── Level2.unity
├── Scripts/             # All C# code
│   ├── Player/
│   ├── Enemies/
│   ├── Managers/
│   ├── UI/
│   └── Utilities/
├── Prefabs/             # Reusable game objects
├── ScriptableObjects/   # Game data assets
│   ├── Enemies/
│   ├── Items/
│   └── Levels/
├── Materials/
├── Textures/
├── Audio/
│   ├── Music/
│   └── SFX/
├── Fonts/
├── Animations/
├── Resources/           # Avoid - use Addressables instead
└── Plugins/             # Third-party SDKs

Deployment and Build

Platform-specific:

Build pipeline:

Specialist Recommendations

Audio Designer

When needed: Games with music, sound effects, ambience Responsibilities:

Performance Optimizer

When needed: Mobile games, large-scale games, VR Responsibilities:

Multiplayer Architect

When needed: Multiplayer/co-op games Responsibilities:

Monetization Specialist

When needed: F2P, mobile games with IAP Responsibilities:

Common Pitfalls

  1. Over-using GetComponent - Cache references in Awake/Start
  2. Empty Update methods - Remove them, they have overhead
  3. String comparisons for tags - Use CompareTag() instead
  4. Resources folder abuse - Migrate to Addressables
  5. Not using object pooling - Instantiate/Destroy is expensive
  6. Ignoring the Profiler - Profile early, profile often
  7. Not testing on target hardware - Mobile performance differs vastly

Key Architecture Decision Records

ADR Template for Unity Projects

ADR-XXX: [Title]

Context: What Unity-specific issue are we solving?

Options:

  1. Unity Built-in Solution (e.g., Built-in Input System)
  2. Unity Package (e.g., New Input System)
  3. Third-party Asset (e.g., Rewired)
  4. Custom Implementation

Decision: We chose [Option X]

Unity-specific Rationale:

Consequences:

This guide is specific to Unity Engine. For other engines, see: