---
name: unity-patterns
description: Advise on choosing Unity design patterns
---

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

## Triggers
- Deciding which pattern fits a problem
- Structuring decoupled systems
- Choosing event/state-machine/pool approaches
- 判断哪种模式适合某问题、构建解耦系统、在事件/状态机/对象池方案间抉择

# 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


---
Source attribution: Besty0728
Original project: https://github.com/Besty0728/Unity-Skills
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Gabriel Moreira

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: Besty0728
Original project: https://github.com/Besty0728/Unity-Skills
Attribution basis: Upstream repository explicitly recorded in package mirror path

Fields of work: Design, Development & Engineering, Product Management
Roles: Game Developer, Product Manager, UX Designer
Specialties: API, Backend, Design, Word Documents, Frontend, Testing
Tools: Unity
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: b8f99a0b6abdb5dafe3742a75c07c4899c9d5206d7aa7e38aadd1e717cb4ae4e