quiccsite

Claude Code for Unity Game Development: A Practical Setup

2026-04-02

Claude Code pairs well with Unity. C# is one of the languages Claude handles best -- there's a massive amount of training data from the .NET ecosystem, StackOverflow, and Unity forums. Compared to something like GDScript (see Claude Code for Godot), you'll get noticeably fewer hallucinations and more idiomatic code out of the box.

That said, Unity has its own patterns that Claude needs guidance on. Here's how to set it up properly.

Setting up CLAUDE.md for Unity

Create a CLAUDE.md at the root of your Unity project. This is where you teach Claude the conventions that matter for your codebase:

Unity 2022 LTS project using C#.

## Project structure
- Game scripts in `Assets/Scripts/`
- Editor scripts in `Assets/Editor/`
- ScriptableObjects in `Assets/Data/`
- Prefabs in `Assets/Prefabs/`

## Conventions
- Use [SerializeField] private fields instead of public fields
- Never use Find() or FindObjectOfType() at runtime — cache references in Awake()
- Use CompareTag() instead of == for tag comparisons
- Prefer TextMeshPro over legacy Text components

## MonoBehaviour lifecycle
- Awake() for self-initialization and caching GetComponent references
- OnEnable()/OnDisable() for subscribing/unsubscribing from events
- Start() for initialization that depends on other objects being ready
- Never call Awake(), Start(), or Update() directly — they are lifecycle callbacks
- Don't put heavy logic in Update() — use coroutines or event-driven patterns

## Async patterns
- Use coroutines (IEnumerator + StartCoroutine) for frame-dependent delays and sequences
- Use async/await with UniTask for actual async operations (network, file I/O)
- Never use System.Threading.Task in MonoBehaviours — it doesn't respect Unity's threading model
- Coroutines stop when the GameObject is disabled. Account for this.

## Don't
- Don't modify prefabs at runtime expecting changes to persist
- Don't use Resources.Load — use Addressables or direct references
- Don't add [RequireComponent] without checking existing prefabs first

Adjust the rules to match your actual project. The key is giving Claude the guardrails that prevent the most common Unity mistakes.

Setting up the C# LSP

Claude Code can use OmniSharp as a language server for C# code intelligence. This gives Claude access to type information, error diagnostics, and symbol resolution across your project.

  1. Make sure your Unity project has generated the .csproj and .sln files (Edit > Preferences > External Tools > Regenerate project files in Unity).
  2. Install the C# LSP extension or ensure OmniSharp is available in your environment.
  3. Point OmniSharp at your .sln file.

With the LSP running, Claude gets real-time feedback about type errors and missing references. This matters a lot for Unity -- the API surface is huge, and the LSP catches issues like wrong method signatures or deprecated APIs before you ever hit Play.

Practical workflows

Writing game systems

"Create an inventory system using ScriptableObjects. Items should have a name, icon, stack size, and item type enum. The player inventory should be a MonoBehaviour with a fixed number of slots."

Claude handles this kind of structural C# work well. It understands ScriptableObject patterns, generics, and serialization. Review the [SerializeField] usage and make sure it matches your inspector workflow.

Debugging null reference exceptions

"I'm getting a NullReferenceException on line 47 of PlayerCombat.cs. Read that file and EnemyHealth.cs to figure out what's null."

This is where Claude shines. Unity's NullReferenceException messages are famously unhelpful -- they don't tell you which reference is null when a line has multiple. Claude can read the code, trace the initialization order, and usually identify whether it's a missing GetComponent call, a race condition between Awake/Start, or a destroyed reference.

Tell Claude which object has the script and how the scene is set up. The more context about the runtime state, the better.

Writing editor scripts

"Write a custom inspector for the WaveSpawner component that shows a preview of the spawn timeline and lets me reorder waves with drag and drop."

Editor scripting is one of the best uses for Claude Code with Unity. Custom inspectors, property drawers, editor windows, and build scripts are pure C# with well-documented APIs. Claude produces solid results here because these are code-only problems with no visual ambiguity.

Working with prefab structure

When you need Claude to modify or create components that live on prefabs, describe the hierarchy explicitly:

"The Player prefab has a root with PlayerController, a child 'Model' with Animator, and a child 'GroundCheck' with a trigger collider. Add a dash ability to PlayerController that uses GroundCheck to verify grounding."

Claude cannot open your scene or inspect the hierarchy, so you need to be its eyes.

What Claude can't do

Claude cannot see your scene hierarchy. It doesn't know what GameObjects exist, how they're parented, or what components are attached unless you describe it. When debugging, paste the relevant hierarchy or describe it in plain text.

Claude cannot preview your game. It can't see what the camera renders, whether animations play correctly, or if UI elements overlap. You are the visual feedback loop. Run the game, describe what happens, and let Claude iterate from there.

Claude cannot modify .unity or .prefab files reliably. These are serialized YAML files with GUIDs and fileIDs. Editing them by hand is fragile. Let Claude write the C# scripts and you handle the scene/prefab wiring in the Unity editor.

Tips for effective workflows

Describe your scene when asking about runtime bugs. "The enemy is a child of the EnemyPool object and gets reparented when spawned" is the kind of context that prevents Claude from giving you advice that assumes a different hierarchy.

Use plan mode for system design. Before building a dialogue system, quest manager, or save system, have Claude design the architecture first. Unity projects get tangled fast when you skip this step.

Keep MonoBehaviours focused. One responsibility per component. Claude reasons about code much better when a script does one thing. A 400-line PlayerController that handles movement, combat, inventory, and UI is hard for anyone to work with -- Claude included.

Paste compiler errors directly. When something fails to compile, paste the full error including the CS error code. Claude knows the C# error codes well and can fix issues faster with the exact diagnostic.

Use asmdef files. Assembly definitions keep your project modular and your compile times fast. They also help Claude understand the dependency boundaries in your codebase.