Unity

Unity Engine C# Editor & Runtime AI Skill Guide (Claude)

Overview & Engine Architecture

Unity is a component-driven real-time engine with a C# scripting layer (Mono / IL2CPP), an Editor extensibility surface (UnityEditor namespace), and player runtimes for desktop, mobile, console, and WebGL. Projects are organized as Scenes + Prefabs + ScriptableObjects, with rendering via Built-in, URP, or HDRP. Claude operates as a Principal Unity Engineer, specializing in Editor scripts and custom windows, deterministic play-mode tooling, Addressables content pipelines, and -batchmode -quit -executeMethod CI builds.

Unity Editor / Player Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Unity Engine Architecture                   │
│                                                             │
│  Authoring (Editor)                                         │
│  ├── UnityEditor APIs (MenuItem, EditorWindow, AssetDatabase│
│  ├── Importers, BuildPipeline, ScriptableBuildPipeline      │
│  └── Domain Reload / Enter Play Mode Options                │
│                                                             │
│  Runtime (Player)                                           │
│  ├── GameObject + MonoBehaviour / ScriptableObject          │
│  ├── SceneManager, Physics, Animation, UI Toolkit/uGUI      │
│  └── URP/HDRP Render Pipeline Asset                         │
│                                                             │
│  Content & CI                                               │
│  ├── Addressables / AssetBundles                            │
│  ├── Unity -batchmode -projectPath -executeMethod           │
│  └── IL2CPP / Mono scripting backends                       │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Editor vs Runtime Separation: Put Editor-only code under #if UNITY_EDITOR or in an Editor/ assembly; never ship UnityEditor references to players.
2. AssetDatabase Hygiene: After creating assets in Editor scripts, call AssetDatabase.CreateAsset, SaveAssets, and Refresh in the correct order.
3. Build Automation: Expose static methods for -executeMethod that set BuildPlayerOptions and return non-zero on failure via EditorApplication.Exit(code).
4. Play Mode Safety: Avoid expensive FindObjectOfType loops; prefer serialized references, dependency injection, or Addressables keys.
5. Pipeline Awareness: Detect URP/HDRP via installed packages before recommending shader/material APIs.

Production C#: Editor Menu + Batch Build Entry Point

Save as Assets/Editor/BuildPlayerMenu.cs:

// ==============================================================================
// Unity Editor: menu item + CI -executeMethod build entry
// ==============================================================================
#if UNITY_EDITOR
using System.IO;
using UnityEditor;
using UnityEditor.Build.Reporting;
using UnityEngine;

public static class BuildPlayerMenu
{
    [MenuItem("Tools/Build/Windows Player")]
    public static void BuildWindowsFromMenu()
    {
        var ok = BuildWindowsInternal();
        if (!ok) Debug.LogError("Windows build failed.");
    }

    // Unity.exe -batchmode -quit -projectPath <path> -executeMethod BuildPlayerMenu.BuildWindowsCI
    public static void BuildWindowsCI()
    {
        var ok = BuildWindowsInternal();
        EditorApplication.Exit(ok ? 0 : 1);
    }

    static bool BuildWindowsInternal()
    {
        var outDir = Path.Combine("Builds", "Windows");
        Directory.CreateDirectory(outDir);

        var options = new BuildPlayerOptions
        {
            scenes = GetEnabledScenes(),
            locationPathName = Path.Combine(outDir, "Game.exe"),
            target = BuildTarget.StandaloneWindows64,
            options = BuildOptions.CompressWithLz4HC
        };

        var report = BuildPipeline.BuildPlayer(options);
        var summary = report.summary;
        Debug.Log($"Build result: {summary.result} size={summary.totalSize}");
        return summary.result == BuildResult.Succeeded;
    }

    static string[] GetEnabledScenes()
    {
        var scenes = EditorBuildSettings.scenes;
        var enabled = new System.Collections.Generic.List<string>();
        foreach (var s in scenes)
            if (s.enabled) enabled.Add(s.path);
        return enabled.ToArray();
    }
}
#endif

Technical Troubleshooting Matrix

Essential CLI Patterns

# CI build (Windows example)
Unity.exe -batchmode -nographics -quit ^
  -projectPath "C:\work\MyGame" ^
  -executeMethod BuildPlayerMenu.BuildWindowsCI ^
  -logFile "C:\work\MyGame\Builds\build.log"

Essential Paths

• Project: Assets/, Packages/manifest.json, ProjectSettings/
• Library (generated): Library/ - safe to delete to force reimport
• Logs: Editor.log under local AppData Unity folders

Agent Operational Directive

MANDATORY: Isolate Editor code from runtime assemblies. For CI, use -batchmode -quit -executeMethod with explicit exit codes. Prefer serialized references over scene searches in production gameplay code.