| name | unity-mobile-game-development |
| description | Use when building, restructuring, profiling, testing, or packaging a Unity mobile game in C# for Android or iOS; covers project architecture, scenes, prefabs, data, input, assets, saves, builds, and Unity-specific release evidence. |
| metadata | {"portable":true,"compatible_with":["claude-code","codex"]} |
Unity Mobile Game Development
Build a Unity game as modular, testable C# systems with reproducible mobile builds and measured target-device behaviour. Verify APIs and package guidance against the project's exact Unity version.
Prerequisites
Load world-class-engineering, the approved game/system specification, and current official documentation for the pinned Unity version.
Use When
- Creating or changing a Unity game, C# component, scene, prefab, ScriptableObject, mobile build, or Unity test.
- Migrating legacy UnityScript, old scene loading, input, UI, render-pipeline, networking, or platform code.
Do Not Use When
- The project uses Godot; use
godot-mobile-game-development.
- The task is engine-neutral design, art, audio, performance strategy, or release operations.
Required Inputs
Repository and Unity version, render pipeline, target platforms/devices, package manifest, architecture, acceptance criteria, performance budgets, build/signing posture, and existing tests.
Workflow
- Inspect project settings, packages, assemblies, scenes, prefabs, assets, build scripts and tests before editing.
- Record an ADR for costly choices: render pipeline, input, asset delivery, save model, scene flow, third-party SDKs and backend boundary.
- Keep pure domain/gameplay logic separate from
MonoBehaviour; use composition, explicit interfaces and event ownership.
- Define a bootstrap/composition root, additive scene policy, prefab boundaries, data assets, lifetime rules and deterministic save identifiers.
- Use the current supported input, UI, async loading, addressable-content and build paths verified for the pinned editor version.
- Add edit-mode tests for pure logic, play-mode tests for integration, and physical-device smoke tests.
- Profile development and release-like IL2CPP builds on the device panel; close with reproducible build and rollback evidence.
Quality Standards
- Pin editor and package versions; commit text-serialised project assets and review dependency changes.
- Avoid hidden global state, stringly typed scene/object lookup, per-frame allocation, synchronous heavy I/O, and unbounded
Update work.
- Keep secrets out of client builds and treat every analytics, ads, IAP or social SDK as a privacy, size, performance and failure dependency.
- Do not copy obsolete book APIs into production; translate the durable pattern into current official APIs.
Anti-Patterns
Find calls and singleton sprawl. Fix: explicit composition and scoped services.- Business rules inside scene components. Fix: testable C# domain classes.
- One giant persistent scene. Fix: bounded additive scenes and ownership rules.
- Optimising only in Editor. Fix: device profiler and release-like build evidence.
- Upgrading packages casually. Fix: ADR, compatibility check, backup, tests and measured diff.
Outputs
Unity architecture map; project/version manifest; system and scene specifications; implementation and tests; device profile; build pipeline; Unity-specific release evidence and residual-risk record.
References
Decision Rules
| Condition | Choice |
|---|
| Exact API/package behaviour is version-sensitive | Check official docs and package changelog before coding |
| Logic can run without Unity objects | Keep it in a plain C# assembly and unit-test it |
| Asset is large, optional or patchable | Evaluate addressable/remote delivery with offline failure handling |
| Plugin lacks maintenance, privacy or rollback evidence | Do not admit it |
Read Next
Use gameplay-systems-architecture, game-math-and-simulation, real-time-game-graphics, mobile-game-performance, and game-testing-polish for their respective gates.
