unity-game-architecture
Unity game architecture decision patterns. Service Locator vs Singleton vs DI, Event Bus vs ScriptableObject channels, MonoBehaviour vs plain C#, component composition, manager bootstrap sequences. DECISION format: WHEN/DECISION/SCAFFOLD/GOTCHA. Based on Unity 6.3 LTS.
Nice-Wolf-Studio · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Nice-Wolf-Studio/unity-claude-skills --skill unity-game-architectureAbout this skill
name: unity-game-architecture description: > Unity game architecture decision patterns. Service Locator vs Singleton vs DI, Event Bus vs ScriptableObject channels, MonoBehaviour vs plain C#, component composition, manager bootstrap sequences. DECISION format: WHEN/DECISION/SCAFFOLD/GOTCHA. Based on Unity 6.3 LTS. globs:
- "**/*.cs"
Game Systems Architecture -- Decision Patterns
Prerequisite skills:
unity-scripting(MonoBehaviour, ScriptableObjects, events),unity-lifecycle(RuntimeInitializeOnLoadMethod, DontDestroyOnLoad, SubsystemRegistration),unity-foundations(components, GameObjects)
These patterns address the most common architectural failure: Claude defaults to fat MonoBehaviours with direct references and singletons everywhere. This works for prototypes but collapses at system scale.
PATTERN: Global Service Access
WHEN: Systems need to find other systems at runtime (AudioManager, InputManager, SaveManager, etc.)
DECISION:
- Lazy Singleton -- Tiny project, 1-3 managers, no testing needed.
static Instance+DontDestroyOnLoad. Fast to write, impossible to mock. - Service Locator -- Medium project, want to swap implementations for testing (mock audio, stub save). Central registry with
Register<T>/Get<T>. Dependencies are implicit but swappable. - Constructor/Method DI -- Large project or library code, maximum testability. Pass dependencies explicitly. Use VContainer or Zenject for MonoBehaviour injection.
SCAFFOLD (Service Locator):
public static class Services
{
private static readonly Dictionary<Type, object> _services = new();
public static void Register<T>(T service) where T : class
{
_services[typeof(T)] = service;
}
public static T Get<T>() where T : class
{
if (_services.TryGetValue(typeof(T), out var service))
return (T)service;
throw new InvalidOperationException($"Service {typeof(T).Name} not registered");
}
public static bool TryGet<T>(out T service) where T : class
{
if (_services.TryGetValue(typeof(T), out var obj))
{
service = (T)obj;
return true;
}
service = null;
return false;
}
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
static void Reset() => _services.Clear();
}
// Registration (in a bootstrap MonoBehaviour or RuntimeInitializeOnLoadMethod):
Services.Register<IAudioService>(new AudioService());
Services.Register<ISaveService>(new SaveService());
// Usage (anywhere):
Services.Get<IAudioService>().PlaySFX("explosion");
GOTCHA: Service Locator hides dependencies -- you cannot see what a class needs by looking at its constructor. Use it for true infrastructure services only (audio, save, analytics), not for gameplay dependencies. Always back services with interfaces (IAudioService, not AudioManager) so tests can register mocks. The SubsystemRegistration reset is critical for Enter Play Mode Options with domain reload disabled.
PATTERN: MonoBehaviour vs Plain C# Class
WHEN: Deciding whether a new class should inherit from MonoBehaviour
DECISION:
- MonoBehaviour -- Needs any of: Inspector serialization via
[SerializeField], Unity callbacks (Update, OnTriggerEnter), Transform/GameObject access, coroutines/Awaitable withdestroyCancellationToken, or being a component on a GameObject. - Plain C# class -- Pure logic: state machines, pathfinding algorithms, data processing, inventory logic, damage calculation, save/load DTOs. Owned and driven by a MonoBehaviour.
SCAFFOLD (Plain C# class owned by MonoBehaviour):
// Pure logic class -- testable without Unity
public class HealthSystem
{
public int Current { get; private set; }
public int Max { get; }
public bool IsDead => Current <= 0;
public event Action OnDied;
public event Action<int, int> OnChanged; // current, max
public HealthSystem(int maxHealth)
{
Max = maxHealth;
Current = maxHealth;
}
public void TakeDamage(int amount)
{
if (IsDead) return;
Current = Mathf.Max(0, Current - amount);
OnChanged?.Invoke(Current, Max);
if (IsDead) OnDied?.Invoke();
}
public void Heal(int amount)
{
if (IsDead) return;
Current = Mathf.Min(Max, Current + amount);
OnChanged?.Invoke(Current, Max);
}
}
// Thin MonoBehaviour wrapper -- bridges Unity and logic
public class HealthComponent : MonoBehaviour
{
[SerializeField] private int maxHealth = 100;
public HealthSystem Health { get; private set; }
void Awake()
{
Health = new HealthSystem(maxHealth);
}
// Optional: expose events for Unity-side wiring
void OnEnable() => Health.OnDied += HandleDeath;
void OnDisable() => Health.OnDied -= HandleDeath;
void HandleDeath()
{
// Unity-specific: play VFX, disable collider, etc.
Destroy(gameObject, 2f);
}
}
GOTCHA: Plain C# classes cannot use [SerializeField]. Use [System.Serializable] for nested display in the Inspector. They have no destroyCancellationToken -- pass one from the owning MonoBehaviour if they do async work. Use Mathf (not System.Math) for Unity-compatible math in plain C# classes that reference UnityEngine.
PATTERN: Component Composition vs Inheritance
WHEN: Multiple GameObjects share some behavior but differ in specifics (enemies with different attacks, interactable objects)
DECISION:
- Composition with interfaces (default) -- Separate capabilities into focused components (
Health,Mover,DamageDealer). Consumers query viaGetComponent<IDamageable>(). Maximum flexibility, easy to mix-and-match. - Abstract base class -- Only when there is genuine IS-A relationship with shared STATE and shared IMPLEMENTATION (not just shared interface). Example:
Projectilebase withBulletProjectileand `Rock