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