Unity Editor Scripting Extras

Unity Editor Scripting Extras

These three APIs sit a level below unity-editor-tooling (which owns Inspectors/PropertyDrawers/EditorWindows/Gizmos/MenuItems/AssetPostprocessor) and unity-project-structure (which owns .asmdef/manifest.json/version control as static configuration). This skill covers the scripting/automation surface on top of those: writing a brand-new file-type importer from scratch, driving package installation programmatically instead of through the Package Manager window, and reading/writing the compiler's own state (define symbols, assembly graph, recompiles) from editor code. The throughline is tooling that runs without a human clicking through UI — CI project bootstrap, automated onboarding scripts, custom file-format pipelines. Prefer retrieval over pre-training: request/async signatures and obsolete-vs-current API names shift between Unity versions (e.g. PlayerSettings.SetScriptingDefineSymbolsForGroup is obsolete in 6.3, superseded by SetScriptingDefineSymbols(NamedBuildTarget, ...)). All paths below are relative to /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/ and were verified to exist on disk.

Retrieval Sources

Key Guidelines

Writing a ScriptedImporter

A ScriptedImporter (Manual/ScriptedImporters.html, ScriptReference/AssetImporters.ScriptedImporter.html) is how you teach Unity to treat an arbitrary file extension as a first-class asset type, the same way .fbx or .png are natively handled. The class lives in the UnityEditor.AssetImporters namespace (so it must be editor-only — put it under an Editor/ folder or an editor-only .asmdef, per unity-editor-tooling/unity-project-structure conventions), derives from the abstract ScriptedImporter, and carries a [ScriptedImporter(version, ext)] attribute that registers which file extension(s) route through it. Unity calls your single required override, OnImportAsset(AssetImportContext ctx), once per import; everything the importer produces — the primary asset, any sub-assets, warnings/errors — is written through the ctx parameter rather than returned. Public serialized fields on the importer class behave exactly like MonoBehaviour fields: they show up in the importer's Inspector and are what a paired ScriptedImporterEditor reads/writes.

Two rules matter for correctness beyond getting an example compiling. First, you must call ctx.SetMainObject(...) on exactly one of the objects you add via ctx.AddObjectToAsset(identifier, obj) — only the designated Main Asset is eligible to become a Prefab or be referenced as "the" asset in other Inspectors; the identifier string passed to AddObjectToAsset must stay stable across reimports of the same file, since it's how Unity tracks sub-asset identity between import runs (changing it orphans references that pointed at the old identifier). Second, any temporary Unity object created during import that is not passed to AddObjectToAsset must be explicitly destroyed with DestroyImmediate before OnImportAsset returns — the import pipeline does not garbage-collect unregistered native objects for you.

using System.IO;
using UnityEngine;
using UnityEditor.AssetImporters;

// Registers a custom importer for files with the ".widget" extension.
// version: bump this integer whenever OnImportAsset's logic changes, so
// Unity invalidates previously cached import results for existing .widget assets.
[ScriptedImporter(version: 1, ext: "widget")]
public class WidgetImporter : ScriptedImporter
{
    [SerializeField] float scale = 1f;
    [SerializeField] Color tint = Color.white;

    public override void OnImportAsset(AssetImportContext ctx)
    {
        // Register a dependency: if this config file changes, Unity reimports
        // every .widget asset that declared the dependency, even though the
        // .widget file itself didn't change on disk.
        const string configPath = "Assets/Config/WidgetDefaults.asset";
        if (File.Exists(configPath))
            ctx.DependsOnArtifact(configPath);

        string json;
        try
        {
            json = File.ReadAllText(ctx.assetPath);
        }
        catch (IOException e)
        {
            ctx.LogImportError($"Could not read widget file: {e.Message}");
            return;
        }

        var data = JsonUtility.FromJson<WidgetData>(json);

        var go = new GameObject("Widget");
        var mesh = BuildWidgetMesh(data, scale);
        var meshFilter = go.AddComponent<MeshFilter>();
        meshFilter.sharedMesh = mesh;

        var material = new Material(Shader.Find("Standard")) { color = tint };
        var renderer = go.AddComponent<MeshRenderer>();
        renderer.sharedMaterial = material;

        // Identifiers must stay stable across reimports; they're the sub-asset's identity.
        ctx.AddObjectToAsset("mesh", mesh);
        ctx.AddObjectToAsset("material", material);
        ctx.AddObjectToAsset("main", go);
        ctx.SetMainObject(go);
    }

    [System.Serializable]
    class WidgetData { public float[] points; }

    static Mesh BuildWidgetMesh(WidgetData data, float scale) => new Mesh();
}

Pair it with a ScriptedImporterEditor (ScriptReference/AssetImporters.ScriptedImporterEditor.html) when the importer's own settings (here scale/tint) need a custom Inspector layout beyond the default field list; it follows the same Apply/Revert lifecycle every AssetImporterEditor uses (ApplyRevertGUI, Apply, CanApply, HasModified), which is distinct from the ordinary CustomEditor/Editor pattern covered in unity-editor-tooling because importer settings are staged and only committed (triggering a real reimport) on Apply.

PackageManager.Client Scripting (async Request pattern)

PackageManager.Client (ScriptReference/PackageManager.Client.html, conceptual walkthrough in Manual/upm-api.html) is the scripted equivalent of the Package Manager window: Client.Add, .Remove, .List, .Search/.SearchAll, .Embed, .Resolve, .AddAndRemove. Every one of these methods is asynchronous and non-blocking — each returns immediately with a Request subclass (AddRequest, RemoveRequest, ListRequest, …) whose work happens on a background thread/process while the Editor keeps ticking. There is no synchronous "wait for it" call in this API; the only supported way to observe completion is polling Request.IsCompleted from an editor-tick callback, most commonly EditorApplication.update (ScriptReference/PackageManager.Requests.Request.html, and the canonical add-a-package example in Manual/upm-api.html does exactly this). Once IsCompleted is true, check Request.Status against PackageManager.StatusCode before touching .Result — StatusCode.Success means the typed .Result (from the generic Request<T>/Request_1 base) is populated, while any code >= StatusCode.Failure means .Result is not meaningful and the failure detail lives in Request.Error (PackageManager.Error, with a coarse PackageManager.ErrorCode like Conflict, NotFound, Forbidden, ConnectionError).

using UnityEditor;
using UnityEditor.PackageManager;
using UnityEditor.PackageManager.Requests;
using UnityEngine;

// Editor-only automation: install a package by name, poll to completion,
// and unsubscribe once done so the update callback doesn't leak.
public static class PackageBootstrap
{
    static AddRequest addRequest;

    [MenuItem("Tools/CI/Install Addressables Package")]
    public static void InstallAddressables()
    {
        // Bare name = latest compatible released version.
        // Use "com.unity.addressables@1.21.19" to pin an exact version.
        addRequest = Client.Add("com.unity.addressables");
        EditorApplication.update += Poll;
    }

    static void Poll()
    {
        if (addRequest == null || !addRequest.IsCompleted)
            return;

        if (addRequest.Status == StatusCode.Success)
            Debug.Log($"Installed {addRequest.Result.packageId}");
        else if (addRequest.Status >= StatusCode.Failure)
            Debug.LogError($"Package install failed: {addRequest.Error.message} ({addRequest.Error.errorCode})");

        EditorApplication.update -= Poll;
        addRequest = null;
    }
}

The identifier string accepted by Client.Add overloads its meaning by format: a bare package name resolves to the latest compatible released version; "name@version" pins an exact version (the only way to install a pre-release); a git URL ("https://github.com/org/repo.git", optionally #revision) installs a git dependency; and "file:/path/to/folder" or "file:/path/to/package.tgz" install a local package or tarball — the same source forms documented for manifest.json entries in unity-project-structure, just issued through code instead of hand-edited JSON. Client.List(offlineMode: true) skips a registry round-trip when you only need locally-known package state (faster, works without network), while the default offlineMode: false refreshes against the registry first. Client.AddAndRemove batches an add and a remove into one manifest resolution pass — prefer it over sequential Add then Remove calls when swapping one package for another, since two separate calls trigger two separate dependency-graph resolutions.

Scripting Define Symbols

Scripting define symbols are per-platform C# preprocessor symbols (#if MY_SYMBOL) layered on top of Unity's built-in platform symbols (UNITY_EDITOR, UNITY_ANDROID, UNITY_IOS, etc. — background in Manual/platform-dependent-compilation.html). The current scripting API keys them by Build.NamedBuildTarget (ScriptReference/Build.NamedBuildTarget.html), a struct with static members like NamedBuildTarget.Standalone, .Android, .iOS, .Server, plus FromBuildTargetGroup/ToBuildTargetGroup converters: PlayerSettings.SetScriptingDefineSymbols(NamedBuildTarget, string[]) and PlayerSettings.GetScriptingDefineSymbols(NamedBuildTarget) (ScriptReference/PlayerSettings.SetScriptingDefineSymbols.html, .GetScriptingDefineSymbols.html). The older BuildTargetGroup-keyed overloads (SetScriptingDefineSymbolsForGroup/GetScriptingDefineSymbolsForGroup) are marked obsolete in-docs in favor of these — expect to see the old form in existing project code and migrate it opportunistically, but write new tooling against the NamedBuildTarget overloads.

using UnityEditor;
using UnityEditor.Build;
using UnityEngine;

public static class DefineSymbolTool
{
    [MenuItem("Tools/CI/Add DEBUG_TELEMETRY Symbol")]
    public static void AddTelemetrySymbol()
    {
        var target = NamedBuildTarget.Standalone;
        var existing = PlayerSettings.GetScriptingDefineSymbols(target)
            .Split(';');

        if (System.Array.IndexOf(existing, "DEBUG_TELEMETRY") >= 0)
            return; // already present

        var updated = new System.Collections.Generic.List<string>(existing) { "DEBUG_TELEMETRY" };
        PlayerSettings.SetScriptingDefineSymbols(target, updated.ToArray());
        // Symbol is now staged; it only takes effect once the next
        // domain reload/recompile actually runs (see Compilation Callbacks below).
    }
}

Because a define-symbol change only changes what the next compile sees, not the code Unity is currently running, setting a symbol and immediately checking #if MY_SYMBOL-gated behavior in the same editor tick will observe the old state — the change is inert until a domain reload happens. If your automation needs code to observe the new symbol, either explicitly trigger a recompile (CompilationPipeline.RequestScriptCompilation()) and wait for compilationFinished, or accept that Unity's own auto-recompile-on-focus-change/on-file-save behavior will pick it up on the next natural reload.

Compilation Callbacks & Forcing Recompiles

Compilation.CompilationPipeline (ScriptReference/Compilation.CompilationPipeline.html) is the scripting window into the compiler itself: querying the current assembly graph (GetAssemblies(AssembliesType), returning Compilation.Assembly[] with name/output path/defines/source files/references), mapping a script file to its owning assembly (GetAssemblyDefinitionFilePathFromScriptPath, GetAssemblyNameFromScriptPath), and subscribing to compilation lifecycle events. Two event pairs exist at different granularity: compilationStarted/compilationFinished fire once for the whole compile cycle (a compilationFinished callback receives a context object correlating it to the matching compilationStarted call and is guaranteed to fire after every assemblyCompilationFinished in that cycle), while assemblyCompilationStarted/assemblyCompilationFinished/assemblyCompilationNotRequired fire once per individual assembly — assemblyCompilationFinished hands you the output path and a CompilerMessage[] you should scan for CompilerMessageType.Error to detect a failed assembly build (a failed compile does not throw or otherwise interrupt your subscriber; you must check the messages yourself).

CompilationPipeline.RequestScriptCompilation() asks Unity to check for a recompile — it is a request, not a guarantee: if Unity determines nothing actually needs recompiling (no changed files, no changed defines/references it hasn't already picked up), no compile happens and none of the events above fire. Pass RequestScriptCompilationOptions.CleanBuildCache when a define-symbol or other invalidation you made isn't itself sufficient to force Unity to notice (rare — normally changing symbols or writing a script file is enough to make the next request meaningful).

using UnityEditor;
using UnityEditor.Compilation;
using UnityEngine;

// Editor-only automation that forces a recompile and reports success/failure
// once the whole cycle completes.
[InitializeOnLoad]
public static class RecompileWatcher
{
    static RecompileWatcher()
    {
        CompilationPipeline.assemblyCompilationFinished += OnAssemblyDone;
        CompilationPipeline.compilationFinished += OnCycleDone;
    }

    static bool anyErrors;

    static void OnAssemblyDone(string assemblyPath, CompilerMessage[] messages)
    {
        foreach (var m in messages)
        {
            if (m.type == CompilerMessageType.Error)
            {
                anyErrors = true;
                Debug.LogError($"{assemblyPath}: {m.message} ({m.file}:{m.line})");
            }
        }
    }

    static void OnCycleDone(object context)
    {
        Debug.Log(anyErrors ? "Recompile finished WITH ERRORS" : "Recompile finished cleanly");
        anyErrors = false;
    }

    [MenuItem("Tools/CI/Force Recompile")]
    static void ForceRecompile() => CompilationPipeline.RequestScriptCompilation();
}

[InitializeOnLoad] (covered fully in unity-editor-tooling) is what makes the static constructor re-subscribe on every domain reload — subscribing once in a [MenuItem]-invoked method without also re-subscribing after reloads means the handler silently stops firing the moment a recompile actually happens, since the domain (and every non-[InitializeOnLoad] static subscription on it) is torn down and rebuilt.

Combining These for CI/Automated Project Setup

The three systems compose into a single unattended "bootstrap a project" script because they sit in a strict dependency order: packages must be installed before code that references their types can compile; define symbols that gate that code must be set before or alongside the package install; and nothing downstream (a build, a test run, further scripted asset generation) should proceed until the resulting recompile has actually finished cleanly. See Advanced Notes for the full composed script.

Common Mistakes

Quick Reference

Advanced Notes

Composing a one-command project bootstrap. The three systems chain in a fixed causal order, and the chain is exactly why none of them can be driven synchronously end-to-end in one function call: install packages (async Client.Add/AddAndRemove, which itself may trigger a domain reload once new package assemblies are pulled in) → set scripting define symbols that gate code depending on those packages (PlayerSettings.SetScriptingDefineSymbols, inert until the next compile) → explicitly force and wait for that compile (CompilationPipeline.RequestScriptCompilation + compilationFinished) → only then is it safe to run anything (tests, further scripted asset generation, a build) that depends on the newly-available types and symbols actually being live in the running domain. A minimal composed driver:

using UnityEditor;
using UnityEditor.Build;
using UnityEditor.Compilation;
using UnityEditor.PackageManager;
using UnityEditor.PackageManager.Requests;
using UnityEngine;

[InitializeOnLoad]
public static class ProjectBootstrap
{
    const string DefineSymbol = "USES_ADDRESSABLES";
    static AddRequest addRequest;

    static ProjectBootstrap()
    {
        CompilationPipeline.compilationFinished += OnCompileFinished;
    }

    [MenuItem("Tools/CI/Bootstrap Project")]
    public static void Run()
    {
        addRequest = Client.Add("com.unity.addressables");
        EditorApplication.update += PollAdd;
    }

    static void PollAdd()
    {
        if (!addRequest.IsCompleted) return;
        EditorApplication.update -= PollAdd;

        if (addRequest.Status != StatusCode.Success)
        {
            Debug.LogError($"Bootstrap failed at package install: {addRequest.Error.message}");
            return;
        }

        var target = NamedBuildTarget.Standalone;
        var defines = new System.Collections.Generic.List<string>(
            PlayerSettings.GetScriptingDefineSymbols(target).Split(';'));
        if (!defines.Contains(DefineSymbol))
        {
            defines.Add(DefineSymbol);
            PlayerSettings.SetScriptingDefineSymbols(target, defines.ToArray());
        }

        // Package add + define change likely already queued a reload;
        // request explicitly so we get a deterministic completion signal either way.
        CompilationPipeline.RequestScriptCompilation();
    }

    static void OnCompileFinished(object context)
    {
        Debug.Log("Bootstrap complete: package installed, symbol set, project recompiled.");
        // Safe from here to run EditMode tests, generate assets via a ScriptedImporter-backed
        // pipeline, or kick off a build — all data this method depends on is now live.
    }
}

Why [InitializeOnLoad] matters here specifically. A package install or a define-symbol change routinely causes a domain reload on its own — Unity reloads the domain whenever the compiled assembly set changes. If the compilationFinished subscription were made inside Run() (a [MenuItem]-invoked instance method call) rather than in a static constructor decorated with [InitializeOnLoad], the very reload the bootstrap triggers would tear down that subscription before it could fire, and the "bootstrap complete" signal would silently never arrive. This is the general s

…(truncated)