unity-patterns

name	unity-patterns
description	Unity design pattern selector. Use when users want advice on ScriptableObject, events, state machines, object pools, observer, or other patterns. Triggers: design pattern, which pattern, ScriptableObject, event channel, observer, state machine, object pool, singleton, service locator, 设计模式, 用什么模式, 事件系统, 状态机, 对象池, 观察者模式, 该用什么模式.

Unity Pattern Selector

Use this skill to decide whether a pattern is justified. Do not recommend every pattern at once.

Guardrails

Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

• Recommend at most 1-3 patterns, and explain why simpler options are not enough.

Pattern Guide

• ScriptableObject

  • Use for authored config, shared static data, event channels, and reusable data assets.
  • Avoid as the default home for per-run mutable gameplay state.

• C# events / delegates

  • Use for one-to-many notifications with clear ownership and unsubscribe points.
  • Avoid for imperative flows that need ordering, return values, or complex debugging.

• Global event bus / observer hub

  • Use sparingly and only when many systems truly need broad decoupled notifications.
  • Avoid as the default answer to coupling. It often hides ownership and makes debugging harder.

• Interfaces

  • Use when multiple implementations or clearer dependency boundaries are needed.
  • Avoid adding interfaces around every class without a real seam.

• State machine

  • Use for actors with mutually exclusive states and explicit transitions.
  • Avoid when a few booleans or a small command flow is enough.

• Object pool

  • Use for frequent spawn/despawn of bullets, VFX, enemies, UI items.
  • Avoid for rare objects or when lifetime is simple.

• Service layer

  • Use for a small number of cross-scene systems with explicit bootstrap and interfaces.
  • Avoid turning everything into hidden singletons or service locators.

• Generics / custom attributes

  • Use when they remove repeated boilerplate with clear type safety or editor metadata value.
  • Avoid when they make gameplay code harder to read than duplicated simple code.

Decision Lab: Same Goal, Multiple Implementations

The Pattern Guide above answers "which pattern?". For most non-trivial design decisions, the better exercise is: pick the 2-3 plausible implementations, put them side by side, and compare on switch cost, query cost, code complexity, and failure modes. Below is a worked example; use it as the shape for other decisions rather than as the answer.

Worked example: "Pause AI on 100 enemies for a cutscene"

Implementation	Switch cost (enter/exit cutscene)	Per-frame cost while paused	Code complexity	Failure modes
Field flag: each EnemyAI.Update starts with if (_paused) return;; manager sets the flag	O(N) writes, no allocations	N branch tests + dispatch overhead per frame	Lowest — one bool, one guard clause	Silent bugs when a dev adds a new Update and forgets the guard
enabled = false: manager disables the MonoBehaviour on every enemy	O(N) writes, no allocations	Zero — Unity skips disabled Behaviours in its message list	Low, but state spread across components	OnDisable / OnEnable side effects (coroutines stop, listeners unsubscribe) may fire unexpectedly
Subset list: manager keeps _active / _frozen lists; no per-enemy Update — manager ticks only _active	O(N) list move on switch	Proportional to _active count only — perfect early-cull	Highest — one source of truth for ownership, requires managed ticking	Adding a new Update on enemies reintroduces per-frame cost; the list is easy to desync if other code respawns enemies directly

How to use

• Pick the smallest scale where the trade-off matters. At N=5 all three are indistinguishable; at N=5000 only the subset list stays flat.
• State what gets worse under each option, not only what improves. A table with only upsides is a sign you haven't thought about it yet.
• The ECS lesson is that the same three shapes (value change, structural change, enableable) show up everywhere — the labels transfer even when the framework does not. Source: Dots101/Entities101/Assets/HelloCube/13. StateChange/SetStateSystem.cs:42-80 — one system dispatches to three implementations behind config.Mode, each with measurably different cost in the profiler.

When to skip this exercise

If one option is obviously bounded (N ≤ 10, state changes once per session, or the code runs once at startup), a single paragraph "we picked X because it's simplest" is enough. Decision Lab is for choices that will outlive the current task.

Output Format

• Recommended pattern(s)
• Why they fit this case
• Why not the simpler alternative
• Minimal implementation boundary
• Known tradeoffs