Unity Architect Helper

Your agent for Unity game development — covering C# scripting, component architecture, scene management, performance optimization, and Unity-specific design patterns.

When to Use This Agent

Choose Unity Architect Helper when:

• Building games or applications in the Unity engine
• Writing C# scripts for gameplay, UI, and system management
• Designing Unity project architecture (managers, service locators, events)
• Optimizing Unity performance (batching, pooling, profiling)
• Implementing Unity-specific features (Addressables, Input System, Cinemachine)

Consider alternatives when:

• You need Unreal Engine — use an Unreal Engine agent
• You need Godot — use a Godot agent
• You need web-based 3D (Three.js) — use a 3D Navigator agent

Quick Start

Copy
# .claude/agents/unity-architect.yml
name: Unity Architect Helper
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Unity game development agent for C# scripting, component architecture, and engine optimization

Example invocation:

claude "Design an inventory system in Unity — scriptable object-based items, UI with drag-and-drop, save/load with JSON serialization, and event-driven updates"

Core Concepts

Unity Architecture Patterns

Pattern	Purpose	Example
Singleton Manager	Global services	AudioManager, GameManager
Service Locator	Dependency access	ServiceLocator.Get<IAudio>()
Scriptable Objects	Data containers	ItemData, EnemyConfig, DialogueData
Event System	Decoupled communication	UnityEvent, C# events, ScriptableObject events
Object Pooling	Reuse objects	BulletPool, ParticlePool
State Machine	Character states	PlayerStateMachine (Idle, Run, Jump)

Unity Project Structure

Assets/
├── Scripts/
│   ├── Core/              # Managers, singletons, utilities
│   ├── Gameplay/           # Player, enemies, items
│   ├── UI/                 # UI controllers, views
│   ├── Data/               # Data models, serialization
│   └── Editor/             # Custom editor scripts
├── ScriptableObjects/      # SO asset definitions
├── Prefabs/                # Reusable GameObjects
├── Scenes/                 # Game scenes
├── Materials/              # Materials and shaders
├── Textures/               # Image assets
├── Audio/                  # Sound effects and music
└── Plugins/                # Third-party libraries

Configuration

Parameter	Description	Default
unity_version	Unity version	2023.x LTS
render_pipeline	Render pipeline (built-in, urp, hdrp)	urp
input_system	Input handling (old, new)	new
target_platform	Build target (pc, mobile, console, webgl)	pc
architecture	Code architecture (simple, service-locator, di)	service-locator

Best Practices

1. Use ScriptableObjects for game data configuration. Items, enemy stats, dialogue, and ability definitions should be ScriptableObjects rather than hardcoded values. This separates data from logic, enables designer editing without code changes, and prevents data duplication.

2. Avoid Find methods in Update loops. GameObject.Find(), FindObjectOfType(), and GetComponent() are expensive. Cache references in Awake() or Start() and reuse them. In hot loops, even GetComponent should be cached.

3. Use the new Input System for cross-platform input. The new Input System supports multiple devices (keyboard, gamepad, touch) with a single action map. Define Input Actions as an asset, and bind them in code with InputAction.performed += callback.

4. Implement object pooling for anything created at runtime. Bullets, particles, UI popups, and enemies should be pooled rather than instantiated/destroyed. Unity's ObjectPool<T> class provides a built-in pooling solution.

5. Profile on target hardware, not just in the editor. The Unity Editor adds overhead that masks real performance characteristics. Build and profile on the target device (especially mobile) to identify actual bottlenecks.

Common Issues

Garbage collection causes frame rate spikes. Allocations in Update() (string concatenation, LINQ, foreach on collections) trigger GC. Use StringBuilder for strings, avoid LINQ in hot paths, and cache array/list allocations.

Scene loading causes long freezes. Use SceneManager.LoadSceneAsync() instead of synchronous loading. Show a loading screen and load scenes additively. For large scenes, split into smaller scenes loaded on demand.

Physics interactions are inconsistent between builds. Non-deterministic physics and floating-point differences cause issues. Move physics logic to FixedUpdate(), use Time.fixedDeltaTime, and avoid modifying physics objects in Update().