version: "1.0.3" name: unity-patterns description: Advises on choosing Unity design patterns — ScriptableObject, event systems, state machines, object pooling, observer, and more. Use when deciding which pattern fits a problem, structuring decoupled systems, or choosing between event/state-machine/pool approaches, even if the user just asks "用什么模式" or "该用状态机吗". 为选择 Unity 设计模式提供建议(ScriptableObject、事件系统、状态机、对象池、观察者等);当用户要判断哪种模式适合某问题、构建解耦系统、或在事件/状态机/对象池方案间抉择时使用。

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"

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