Scoped registry in Unity

2025-07-19 17:57 UTC o3-pro Open in ChatGPT ↗

Short answer

You can list another package that lives in a custom/scoped registry in the dependencies section of your own package’s package.json, but Unity will not fetch it automatically unless the project that installs your package has already declared that registry in its project Packages/manifest.json.
Because scopedRegistries is only supported in the project manifest, not inside a package manifest, your package on its own cannot “bring along” the registry definition – the user (or an installer script you provide) must add it first. citeturn10search0turn7view0turn15view0

How Unity resolves a package dependency

Step	What Unity’s Package Manager does	Where the information comes from
1	Reads the list of registries it is allowed to query	`scopedRegistries` array in `Packages/manifest.json` of the project citeturn7view0
2	Looks at every entry in your package’s `"dependencies"` object	Your package’s `package.json`
3	Chooses the registry whose scope most closely matches the package name	The scopes defined in the project manifest
4	Downloads the dependency	Only succeeds if that registry entry exists and the package version is present there

If the required registry is missing, Unity shows “Cannot find package …” and installation of your package fails.

Practical implications for package authors

Document the prerequisite
Tell users to add the registry (example for OpenUPM):

// Packages/manifest.json (project level)
{
  "scopedRegistries": [
    {
      "name": "OpenUPM",
      "url":  "https://package.openupm.com",
      "scopes": [ "com.company" ]
    }
  ],
  "dependencies": {
    "com.company.mypackage": "1.2.3"          // your package
  }
}

Optionally add an editor script that edits Packages/manifest.json on first import to insert the registry; several open‑source tools (e.g. Google EDM4U) do this.
Guard against a missing dependency
Use Version Defines or pre‑processor checks so that your code compiles even when the secondary package is absent, and display an explanatory dialog.

Alternative distribution tactics

Technique	Pros	Cons
Ship the third‑party code inside your own package (sub‑folder, subtree, git submodule)	Works out‑of‑the‑box	Larger package, harder to update/upstream fixes
Ask users to install the other package manually first	Simple for you	Extra step for user, easy to forget
Provide a “meta” installer UnityPackage or custom wizard that adds the registry then installs	Smoothest UX	Extra maintenance work
Wait for Unity to support registry declarations in packages (not on the public roadmap as of Unity 6.0/2025)	Future‑proof	Not available today

Key takeaways

Listing the dependency alone is not enough.
You cannot declare scopedRegistries inside a package; only the consuming project can.
Plan your onboarding flow (documentation, installer script, or bundling) so that the required registry is present before Unity evaluates your package’s dependencies.

Below is a drop‑in template you can copy into your package.
Everything is plain C# / JSON, so it works from Unity 2020.3 LTS up to Unity 6.x.

## 2 — Editor script that injects the scoped registry automatically

Create Editor/RegistryBootstrap.cs inside your package:

#if UNITY_EDITOR
using System.IO;
using System.Linq;
using System.Text;
using UnityEditor;
using UnityEngine;

// You need Newtonsoft.Json for robust JSON editing.
// Unity ships it as the built‑in package "com.unity.nuget.newtonsoft-json"
using Newtonsoft.Json.Linq;

namespace Com.Company.MyPackage.Editor
{
    /// <summary>Adds the registry once per project, then stays silent.</summary>
    [InitializeOnLoad]                // runs as soon as the editor loads domain
    internal static class RegistryBootstrap
    {
        // ----  CHANGE THESE CONSTANTS TO MATCH YOUR REGISTRY  ----
        private const string RegistryName = "OpenUPM";
        private const string RegistryUrl  = "https://package.openupm.com";
        private static readonly string[] Scopes = { "com.company" };
        // ---------------------------------------------------------

        static RegistryBootstrap() => TryAddRegistry();

        private static void TryAddRegistry()
        {
            string manifestPath = Path.Combine(Application.dataPath, "..", "Packages", "manifest.json");

            if (!File.Exists(manifestPath)) return;                               // should always exist citeturn8view0

            // 1. Read & parse
            var json = JObject.Parse(File.ReadAllText(manifestPath, Encoding.UTF8));

            // 2. Ensure the array exists
            var registries = (JArray)(json["scopedRegistries"] ?? new JArray());
            json["scopedRegistries"] = registries;                                // keep reference if it was missing

            // 3. Already present?
            bool present = registries
                .OfType<JObject>()
                .Any(r => (string)r["name"] == RegistryName);

            if (present) return;

            // 4. Append ours
            var newReg = new JObject
            {
                ["name"]   = RegistryName,
                ["url"]    = RegistryUrl,
                ["scopes"] = new JArray(Scopes)
            };
            registries.Add(newReg);

            // 5. Write back, pretty‑printed for humans
            File.WriteAllText(manifestPath, json.ToString(Newtonsoft.Json.Formatting.Indented), Encoding.UTF8);
            AssetDatabase.Refresh();

            EditorUtility.DisplayDialog(
                $"{RegistryName} added",
                $"The registry was written to Packages/manifest.json so that packages in {string.Join(", ", Scopes)} can resolve.",
                "OK");
        }
    }
}
#endif

### How it works

Location – Packages/manifest.json lives one folder above Assets in every project citeturn8view0.
Logic – On the first domain reload after your package is imported, the static constructor checks the scopedRegistries array and adds an entry if it’s missing.
Safety – If the user already declared the registry (possibly with different URL/scopes) the script does nothing.
Dependencies – Starting with 2021.1 Unity embeds Newtonsoft.Json; on older versions declare a dependency on "com.unity.nuget.newtonsoft-json" in your package manifest.

Tip: If you prefer to prompt instead of writing automatically, replace step 4/5 with EditorUtility.DisplayDialogComplex() and write only when the user clicks “Yes”.

## 3 — Guarding your code when the dependency is missing

### a) Add a Version Define to your assembly definition

Open the .asmdef that holds the code which uses the external package (for example Runtime/MyPackage.asmdef) and add:

{
  "name": "Com.Company.MyPackage",
  "references": [],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,

  "versionDefines": [
    {
      "name": "com.external.cool‑lib", // ← the *package name* you depend on
      "expression": ">=1.0.0",        // any SemVer or range is allowed
      "define": "COOL_LIB_PRESENT"    // this symbol will appear when present
    }
  ]
}

The Version Defines feature lets you emit a compile‑time symbol when (and only when) a specific package and version is installed, so you don’t need hard references that break when it isn’t. Unity documents the mechanism here citeturn3view0turn7search1.

### b) Isolate the optional code

#if COOL_LIB_PRESENT
using CoolLib;                       // only compiles if the lib is installed
#endif

namespace Com.Company.MyPackage
{
    internal static class OptionalFeature
    {
#if COOL_LIB_PRESENT
        public static void DoStuff()
        {
            CoolLibApi.Run();
        }
#else
        // Fallback or stub keeps the API stable:
        public static void DoStuff() =>
            UnityEngine.Debug.LogWarning(
                "Install 'com.external.cool‑lib' to enable advanced features.");
#endif
    }
}

### c) (Optional) Show an editor‑time warning

If you prefer a pop‑up rather than a compile stub:

#if !COOL_LIB_PRESENT && UNITY_EDITOR
using UnityEditor;
using UnityEngine;
[InitializeOnLoad]
internal static class MissingCoolLibNotifier
{
    static MissingCoolLibNotifier()
    {
        if (EditorPrefs.GetBool("Com.Company.MyPackage.HideMissingCoolLibPrompt"))
            return;

        if (EditorUtility.DisplayDialog(
            "Optional dependency missing",
            "Install 'com.external.cool‑lib' (via Package Manager) to enable XYZ.",
            "Open Package Manager", "Ignore"))
        {
            UnityEditor.PackageManager.UI.Window.Open("");
        }
        else
        {
            EditorPrefs.SetBool("Com.Company.MyPackage.HideMissingCoolLibPrompt", true);
        }
    }
}
#endif

## What you just achieved

Zero‑click onboarding – the first time your package lands in a project, the registry entry appears automatically, so Unity can resolve your indirect dependency.
Safe compilation – projects compile whether or not the secondary package is present; advanced features simply light up when it is.
Friendly guidance – developers see a clear dialog or console message explaining why something is disabled instead of staring at compiler errors.

With these two building blocks your package behaves like a polished Unity first‑party package even though it pulls content from a scoped registry that the user didn’t configure beforehand.

Why Unity is complaining

Char 65279 is the UTF‑8 byte‑order mark (BOM) – an invisible “zero‑width no‑break space” (U+FEFF) that sits before the opening { in your Packages/manifest.json.
Unity’s Package Manager JSON reader does not accept any bytes before the first {, so it stops with “Non‑whitespace before {[” and won’t load any packages. Stack Overflow threads about the same error confirm the BOM as the culprit citeturn5view0.
The template script I gave earlier used Encoding.UTF8, which, on Windows/.NET, adds the BOM when it rewrites the file – that is how the stray character appeared. Developers on Unity forums hit the same “Failed to resolve packages” issue after a merge tool inserted a BOM citeturn1search8.

Immediate rescue – get your project compiling again

Open UnityCore_Project/Packages/manifest.json in a plain‑text editor that lets you choose the encoding (VS Code, Notepad++, Rider, etc.).
Re‑save the file as “UTF‑8 (without BOM)” or “UTF‑8‑No‑Signature”.
After the save, the very first byte of the file must be “{” – nothing else, even if you can’t see it.
Relaunch Unity or press Retry in the Package Manager error dialog. Packages should now resolve.

(If you can’t use an editor, PowerShell works too:)

Get-Content Packages\manifest.json | Out-File Packages\manifest.json -Encoding utf8NoBOM

Permanent fix – patch the bootstrap script

Replace the final write call so it never emits a BOM:

// using System.Text;
var utf8NoBom = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false);

File.WriteAllText(
    manifestPath,
    json.ToString(Newtonsoft.Json.Formatting.Indented),
    utf8NoBom);   // ← no BOM!

Why this works: new UTF8Encoding(false) tells .NET not to prefix the file with EF BB BF (char 65279). When Unity later re‑opens the file, the first byte is {, exactly what its parser expects.

Optional safety net – strip an existing BOM automatically

Add this helper right before you parse the manifest:

string text = File.ReadAllText(manifestPath, Encoding.UTF8);

// Trim a BOM if the user’s editor inserted one
if (text.Length > 0 && text[0] == '\uFEFF')
    text = text.Substring(1);

var json = JObject.Parse(text);

Now the script heals any future BOMs that might creep in through manual edits or merge tools.

Take‑away

Unity project manifests must be plain UTF‑8 with no BOM.
Saving with the wrong encoder (or using Encoding.UTF8 without the explicit false flag) adds the BOM and breaks Package Manager.
Updating your bootstrap to write UTF‑8 without BOM prevents the problem for everyone who installs your package.