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
- Unity project architecture
- Legacy Unity migration and mobile build gates
- Unity 6 MCP and runtime UI notes
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.
1---2name: unity-mobile-game-development3description: 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.4metadata: {portable: true, compatible_with: [claude-code, codex]}5---67# Unity Mobile Game Development8Build 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.910## Prerequisites1112Load `world-class-engineering`, the approved game/system specification, and current official documentation for the pinned Unity version.13<!-- dual-compat-start -->14## Use When15- Creating or changing a Unity game, C# component, scene, prefab, ScriptableObject, mobile build, or Unity test.16- Migrating legacy UnityScript, old scene loading, input, UI, render-pipeline, networking, or platform code.17## Do Not Use When18- The project uses Godot; use `godot-mobile-game-development`.19- The task is engine-neutral design, art, audio, performance strategy, or release operations.20## Required Inputs21Repository and Unity version, render pipeline, target platforms/devices, package manifest, architecture, acceptance criteria, performance budgets, build/signing posture, and existing tests.22## Workflow231. Inspect project settings, packages, assemblies, scenes, prefabs, assets, build scripts and tests before editing.242. Record an ADR for costly choices: render pipeline, input, asset delivery, save model, scene flow, third-party SDKs and backend boundary.253. Keep pure domain/gameplay logic separate from `MonoBehaviour`; use composition, explicit interfaces and event ownership.264. Define a bootstrap/composition root, additive scene policy, prefab boundaries, data assets, lifetime rules and deterministic save identifiers.275. Use the current supported input, UI, async loading, addressable-content and build paths verified for the pinned editor version.286. Add edit-mode tests for pure logic, play-mode tests for integration, and physical-device smoke tests.297. Profile development and release-like IL2CPP builds on the device panel; close with reproducible build and rollback evidence.30## Quality Standards31- Pin editor and package versions; commit text-serialised project assets and review dependency changes.32- Avoid hidden global state, stringly typed scene/object lookup, per-frame allocation, synchronous heavy I/O, and unbounded `Update` work.33- Keep secrets out of client builds and treat every analytics, ads, IAP or social SDK as a privacy, size, performance and failure dependency.34- Do not copy obsolete book APIs into production; translate the durable pattern into current official APIs.35## Anti-Patterns36- `Find` calls and singleton sprawl. Fix: explicit composition and scoped services.37- Business rules inside scene components. Fix: testable C# domain classes.38- One giant persistent scene. Fix: bounded additive scenes and ownership rules.39- Optimising only in Editor. Fix: device profiler and release-like build evidence.40- Upgrading packages casually. Fix: ADR, compatibility check, backup, tests and measured diff.41## Outputs42Unity architecture map; project/version manifest; system and scene specifications; implementation and tests; device profile; build pipeline; Unity-specific release evidence and residual-risk record.43## References44- [Unity project architecture](references/unity-project-architecture.md)45- [Legacy Unity migration and mobile build gates](references/unity-mobile-build-gates.md)46- [Unity 6 MCP and runtime UI notes](references/unity-6-mcp-and-runtime-ui-notes.md)47<!-- dual-compat-end -->48## Decision Rules49| Condition | Choice |50|---|---|51| Exact API/package behaviour is version-sensitive | Check official docs and package changelog before coding |52| Logic can run without Unity objects | Keep it in a plain C# assembly and unit-test it |53| Asset is large, optional or patchable | Evaluate addressable/remote delivery with offline failure handling |54| Plugin lacks maintenance, privacy or rollback evidence | Do not admit it |55## Read Next56Use `gameplay-systems-architecture`, `game-math-and-simulation`, `real-time-game-graphics`, `mobile-game-performance`, and `game-testing-polish` for their respective gates.
peterbamuhigire