Skip to content

A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.

29.7 KB
Raw Blame
#nullable enable
using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using Statecraft.Game.Boot;
using UnityEngine;
using UnityEngine.Networking;

namespace Statecraft.Game.Map.Collection
{
    /// <summary>Streams The 1948 Collection's models after the first frame (issue #664; owner, 15 October 2026: "we need to
    /// make sure this is built in a way that doesnt make the game extremely hard to load"). Ask for a model with
    /// <see cref="Request"/>: nothing comes back at once, so the caller draws its placeholder (or nothing), and the callback
    /// later gets the model's prefab to instantiate. Nothing is fetched until the frame after the first request, so a
    /// request never delays the frame that made it, and nothing is fetched at all until something asks.
    /// It fails open: a bundle that is missing, damaged or will not load logs one warning, every request for it gets null,
    /// and the map runs on without those models. An id the collection does not have gets null and one warning. An exception
    /// from the source or from a caller's callback is caught for that request alone: it logs one warning (once per bundle,
    /// prefab or id) and the stream goes on serving every later request.
    /// The player reads the bundles from StreamingAssets/<see cref="CollectionCatalog.StreamingFolder"/> (every Build.*
    /// player build, Web, Mac, Linux and Windows, puts them there); the editor reads the prefabs from the AssetDatabase, so map work needs no bundle build.
    /// The same loader serves any other set of streamed bundles through its own <see cref="Catalog"/> (the hex tiles' props,
    /// HexProps; owner, 23 October 2026: "Own streamed bundle"), each with its own folder, checks file and shared stream.</summary>
    public sealed class CollectionStream
    {
        /// <summary>What a stream serves: its bundles' folder in StreamingAssets, the checks file beside them (written by the
        /// bundle build, <see cref="CollectionCatalog.ChecksFile"/>'s format), and each model id's bundle and prefab path.</summary>
        public sealed class Catalog
        {
            public readonly string Name, StreamingFolder, ChecksFile;
            public readonly Func<string, string?> BundleOf;
            public readonly Func<string, CollectionDetail, string> PrefabPath;

            public Catalog(string name, string streamingFolder, string checksFile, Func<string, string?> bundleOf,
                Func<string, CollectionDetail, string> prefabPath)
            {
                Name = name; StreamingFolder = streamingFolder; ChecksFile = checksFile; BundleOf = bundleOf; PrefabPath = prefabPath;
            }
        }

        /// <summary>The 1948 Collection (<see cref="CollectionCatalog"/>), the stream's default.</summary>
        public static readonly Catalog Collection = new Catalog("The 1948 Collection", CollectionCatalog.StreamingFolder,
            CollectionCatalog.ChecksFile, CollectionCatalog.BundleOf, CollectionCatalog.PrefabPath);

        /// <summary>Where the models come from: bundles in a build, the AssetDatabase in the editor, a fake in tests.</summary>
        public interface ISource
        {
            /// <summary>Opens <paramref name="bundle"/>; calls <paramref name="done"/> with null on success or with why it failed.</summary>
            IEnumerator Open(string bundle, Action<string?> done);
            /// <summary>Loads the prefab at <paramref name="path"/> from the opened <paramref name="bundle"/> (null if absent).</summary>
            IEnumerator Load(string bundle, string path, Action<GameObject?> done);
            /// <summary>Releases one bundle only after every acquired consumer has retired.</summary>
            void Unload(string bundle);
        }

        enum State { Closed, Open, Failed }

        readonly ISource source;
        readonly Catalog catalog;
        readonly Dictionary<string, State> bundles = new Dictionary<string, State>(StringComparer.Ordinal);
        readonly Dictionary<string, GameObject?> loaded = new Dictionary<string, GameObject?>(StringComparer.Ordinal);
        readonly HashSet<string> warnedIds = new HashSet<string>(StringComparer.Ordinal);
        readonly HashSet<string> warnedCallbacks = new HashSet<string>(StringComparer.Ordinal);
        readonly Queue<(string Id, CollectionDetail Detail, Action<GameObject?> Done, Lease? Owner)> pending =
            new Queue<(string, CollectionDetail, Action<GameObject?>, Lease?)>();
        readonly Dictionary<string, int> owners = new Dictionary<string, int>(StringComparer.Ordinal);
        readonly Dictionary<string, string> paths = new Dictionary<string, string>(StringComparer.Ordinal);
        readonly HashSet<string> pinned = new HashSet<string>(StringComparer.Ordinal);
        readonly HashSet<string> inflight = new HashSet<string>(StringComparer.Ordinal);
        readonly HashSet<string> pendingEvictions = new HashSet<string>(StringComparer.Ordinal);
        readonly HashSet<string> warnedRelease = new HashSet<string>(StringComparer.Ordinal);

        sealed class Lease : IDisposable
        {
            CollectionStream? owner;
            readonly string? bundle;
            public bool Active => owner != null;
            public Lease(CollectionStream owner, string? bundle) { this.owner = owner; this.bundle = bundle; }
            public void Dispose()
            {
                var stream = owner; owner = null;
                if (stream == null || bundle == null) return;
                int left = stream.owners[bundle] - 1;
                if (left == 0) stream.owners.Remove(bundle); else stream.owners[bundle] = left;
                stream.Evict(bundle);
            }
        }

        /// <summary>An owned request. Dispose after destroying instances and clearing asset references; late answers are
        /// suppressed. Legacy Enqueue/Request callers keep their bundles pinned.</summary>
        public IDisposable Retain(string id, CollectionDetail detail, Action<GameObject?> done)
        {
            var bundle = catalog.BundleOf(id);
            var lease = new Lease(this, bundle);
            if (bundle == null) { Enqueue(id, detail, done); lease.Dispose(); return lease; }
            owners.TryGetValue(bundle, out int count); owners[bundle] = count + 1;
            pending.Enqueue((id, detail, done, lease));
            CollectionResidencyMetrics.MarkDirty();
            return lease;
        }

        void Evict(string bundle)
        {
            if (Application.isPlaying) { pendingEvictions.Add(bundle); return; }
            EvictNow(bundle);
        }
        void DrainEvictions()
        {
            var pending = new List<string>(pendingEvictions); pendingEvictions.Clear(); pending.Sort(StringComparer.Ordinal);
            foreach (var bundle in pending) EvictNow(bundle);
        }
        void EvictNow(string bundle)
        {
            CollectionResidencyMetrics.MarkDirty();
            if (pinned.Contains(bundle) || owners.ContainsKey(bundle) || inflight.Contains(bundle)) return;
            if (!bundles.TryGetValue(bundle, out var state)) return;
            var remove = new List<string>();
            foreach (var pair in paths) if (pair.Value == bundle) remove.Add(pair.Key);
            if (state == State.Open)
            {
                try { source.Unload(bundle); }
                catch (Exception e)
                {
                    pendingEvictions.Add(bundle);
                    if (warnedRelease.Add(bundle)) Debug.LogWarning($"Collection: could not release {bundle} ({Describe(e)}).");
                    return;
                }
            }
            foreach (string path in remove) { loaded.Remove(path); paths.Remove(path); }
            bundles.Remove(bundle);
        }

        /// <summary>A detached diagnostic view, per ORIGINAL bundle (not category); no residency mutations.</summary>
        public sealed class BundleDiagnostic
        {
            public string Bundle { get; internal set; } = "";
            public string State { get; internal set; } = "";
            public int Owners { get; internal set; }
            public int CachedPrefabs { get; internal set; }
            public int CachedPaths { get; internal set; }
            public int PendingRequests { get; internal set; }
            public bool Pinned { get; internal set; }
            public bool InFlight { get; internal set; }
            public bool EvictionQueued { get; internal set; }
        }
        public IReadOnlyList<BundleDiagnostic> Diagnostics()
        {
            var names = new SortedSet<string>(bundles.Keys, StringComparer.Ordinal);
            names.UnionWith(owners.Keys); names.UnionWith(pinned); names.UnionWith(inflight); names.UnionWith(pendingEvictions);
            foreach (var request in pending) { var name = catalog.BundleOf(request.Id); if (name != null) names.Add(name); }
            var rows = new List<BundleDiagnostic>();
            foreach (string name in names)
            {
                var row = new BundleDiagnostic { Bundle = name, State = bundles.TryGetValue(name, out var state) ? state.ToString() : "Pending",
                    Owners = owners.TryGetValue(name, out int count) ? count : 0, Pinned = pinned.Contains(name),
                    InFlight = inflight.Contains(name), EvictionQueued = pendingEvictions.Contains(name) };
                foreach (var path in paths)
                    if (path.Value == name)
                    {
                        row.CachedPaths++;
                        if (loaded.TryGetValue(path.Key, out var prefab) && prefab != null) row.CachedPrefabs++;
                    }
                foreach (var request in pending) if (catalog.BundleOf(request.Id) == name) row.PendingRequests++;
                rows.Add(row);
            }
            return rows.AsReadOnly();
        }
        internal static IReadOnlyList<BundleDiagnostic> SharedDiagnostics() =>
            shared == null ? Array.Empty<BundleDiagnostic>() : shared.Diagnostics();
        internal static bool Settled(IReadOnlyList<(string id, CollectionDetail detail)> keys)
        {
            if (shared == null) return true;
            foreach (var key in keys)
            {
                var bundle = CollectionCatalog.BundleOf(key.id);
                if (bundle == null) continue;
                if (shared.inflight.Contains(bundle) || shared.pendingEvictions.Contains(bundle)) return false;
                foreach (var request in shared.pending)
                    if (CollectionCatalog.BundleOf(request.Id) == bundle) return false;
            }
            return true;
        }

        public CollectionStream(ISource source, Catalog? catalog = null) { this.source = source; this.catalog = catalog ?? Collection; }

        /// <summary>The game's stream, made on the first request with the source for this player (or the editor).</summary>
        static int readyFrame = -1;
        public static void GameReady() { if (readyFrame < 0) readyFrame = Time.frameCount; }
        public static bool MayFetch(int frame, int ready) => ready >= 0 && frame > ready + 2;
        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
        static void ResetFrame() { readyFrame = -1; shared = null; host = null; }
        static CollectionStream? shared;
        static CollectionStreamHost? host;

        /// <summary>The other catalogs' streams (the hex props), one per catalog, each made on its first request with the
        /// source for this player (or the editor), and each run by its own host.</summary>
        static readonly Dictionary<Catalog, CollectionStream> streams = new Dictionary<Catalog, CollectionStream>();
        static readonly Dictionary<Catalog, CollectionStreamHost> hosts = new Dictionary<Catalog, CollectionStreamHost>();

        /// <summary>Asks for model <paramref name="id"/> at <paramref name="detail"/>; <paramref name="done"/> runs on a later
        /// frame with the prefab, or with null when the model cannot be had (fail open).</summary>
        public static void Request(string id, CollectionDetail detail, Action<GameObject?> done)
        {
            shared ??= new CollectionStream(DefaultSource(Collection));
            if (shared.Enqueue(id, detail, done)) StartHost();
        }

        /// <summary><see cref="Request(string, CollectionDetail, Action{GameObject})"/> from <paramref name="catalog"/>'s
        /// stream; nothing of it is fetched until something asks.</summary>
        public static void Request(Catalog catalog, string id, CollectionDetail detail, Action<GameObject?> done)
        {
            if (catalog == Collection) { Request(id, detail, done); return; }
            if (!streams.TryGetValue(catalog, out var stream)) streams[catalog] = stream = new CollectionStream(DefaultSource(catalog), catalog);
            if (stream.Enqueue(id, detail, done) && (!hosts.TryGetValue(catalog, out var other) || other == null))
            {
                var go = new GameObject("CollectionStream " + catalog.StreamingFolder) { hideFlags = HideFlags.HideAndDontSave };
                if (Application.isPlaying) UnityEngine.Object.DontDestroyOnLoad(go);
                hosts[catalog] = other = go.AddComponent<CollectionStreamHost>();
                other.StartCoroutine(other.Run(stream));
            }
        }

        /// <summary>Acquires a model from the same stream as the other map layers, without permanently pinning it.</summary>
        public static IDisposable Acquire(string id, CollectionDetail detail, Action<GameObject?> done)
        {
            shared ??= new CollectionStream(DefaultSource(Collection));
            var lease = shared.Retain(id, detail, done);
            if (CollectionCatalog.BundleOf(id) != null) StartHost();
            return lease;
        }

        static void StartHost()
        {
            if (host != null) return;
            var go = new GameObject("CollectionStream") { hideFlags = HideFlags.HideAndDontSave };
            if (Application.isPlaying) UnityEngine.Object.DontDestroyOnLoad(go);
            host = go.AddComponent<CollectionStreamHost>();
            host.StartCoroutine(host.Run(shared!));
        }

        static ISource DefaultSource(Catalog catalog)
        {
#if UNITY_EDITOR
            return new EditorSource();
#else
            return new BundleSource(Path.Combine(Application.streamingAssetsPath, catalog.StreamingFolder), catalog.ChecksFile);
#endif
        }

        /// <summary>Queues a request; false (and <paramref name="done"/> already called with null) for an unknown id.</summary>
        public bool Enqueue(string id, CollectionDetail detail, Action<GameObject?> done)
        {
            if (catalog.BundleOf(id) == null)
            {
                if (warnedIds.Add(id)) Debug.LogWarning($"Collection: no model '{id}' in {catalog.Name}; nothing is drawn for it.");
                done(null);
                return false;
            }
            pinned.Add(catalog.BundleOf(id)!);
            pending.Enqueue((id, detail, done, null));
            CollectionResidencyMetrics.MarkDirty();
            return true;
        }

        /// <summary>Serves the queued requests, one frame after it starts, then each new one as it comes, for ever (the host
        /// runs it as a coroutine; tests step it by hand).</summary>
        public IEnumerator Run()
        {
            yield return null;   // after the frame that made the first request
            while (Application.isPlaying && !MayFetch(Time.frameCount, readyFrame)) yield return null;
            while (true)
            {
                DrainEvictions();
                while (pending.Count > 0)
                {
                    var (id, detail, done, owner) = Next();
                    var bundle = catalog.BundleOf(id)!;
                    if (owner != null && !owner.Active) { Evict(bundle); continue; }
                    inflight.Add(bundle);
                    try
                    {
                        if (!bundles.TryGetValue(bundle, out var state))
                        {
                            string? error = null;
                            yield return Guard(() => source.Open(bundle, e => error = e), e => error = e);
                            state = error == null ? State.Open : State.Failed;
                            bundles[bundle] = state;
                            if (error != null) Debug.LogWarning($"Collection: bundle {bundle} did not load ({error}); its models stay off the map.");
                        }
                        if (owner != null && !owner.Active) continue;
                        if (state != State.Open) { Answer(id, done, null); continue; }
                        var path = catalog.PrefabPath(id, detail);
                        if (!loaded.TryGetValue(path, out var prefab))
                        {
                            string? error = null;
                            yield return Guard(() => source.Load(bundle, path, p => prefab = p), e => error = e);
                            if (error != null) prefab = null;
                            loaded[path] = prefab; paths[path] = bundle; CollectionResidencyMetrics.MarkDirty();
                            if (error != null) Debug.LogWarning($"Collection: bundle {bundle} did not load {path} ({error}); nothing is drawn for it.");
                            else if (prefab == null) Debug.LogWarning($"Collection: bundle {bundle} has no {path}; nothing is drawn for it.");
                        }
                        if (owner == null || owner.Active) Answer(id, done, prefab);
                    }
                    finally { inflight.Remove(bundle); Evict(bundle); }
                }
                yield return null;
            }
        }

        /// <summary>The next queued request to serve, in order, except that a request for a bundle that comes
        /// <see cref="CollectionCatalog.After"/> another waits behind a queued request for that other bundle until it has
        /// settled. It never waits for a bundle nobody has asked for, and a failed bundle counts as settled (fail open).</summary>
        (string Id, CollectionDetail Detail, Action<GameObject?> Done, Lease? Owner) Next()
        {
            for (int n = pending.Count; n > 0; n--)
            {
                var next = pending.Dequeue();
                if (!CollectionCatalog.After.TryGetValue(catalog.BundleOf(next.Id)!, out var first) || bundles.ContainsKey(first)
                    || !Queued(first))
                    return next;
                pending.Enqueue(next);
            }
            return pending.Dequeue();
        }

        bool Queued(string bundle)
        {
            foreach (var p in pending)
            {
                if (catalog.BundleOf(p.Id) == bundle) return true;
                foreach (var group in CollectionCatalog.Groups)
                    if (group.Bundle == bundle && Array.IndexOf(group.Ids, p.Id) >= 0) return true;
            }
            return false;
        }

        /// <summary>Hands <paramref name="prefab"/> to the caller; a callback that throws logs one warning per id and never
        /// stops the stream.</summary>
        void Answer(string id, Action<GameObject?> done, GameObject? prefab)
        {
            try { done(prefab); }
            catch (Exception e)
            {
                if (warnedCallbacks.Add(id))
                    Debug.LogWarning($"Collection: the callback for '{id}' threw ({Describe(e)}); the stream serves the next request.");
            }
        }

        static string Describe(Exception e) => e.GetType().Name + ": " + e.Message;

        /// <summary>Runs the source's coroutine (and any it nests) so that an exception, thrown when it starts or at any step,
        /// ends only that coroutine and reaches <paramref name="failed"/>, instead of ending <see cref="Run"/> with it. (C#
        /// cannot yield inside a try with a catch, so each step is taken inside one and yielded outside it.)</summary>
        static IEnumerator Guard(Func<IEnumerator> start, Action<string> failed)
        {
            IEnumerator inner;
            try { inner = start(); }
            catch (Exception e) { failed(Describe(e)); inner = Done(); }
            while (true)
            {
                object? current = null;
                bool more;
                try
                {
                    more = inner.MoveNext();
                    if (more) current = inner.Current;
                }
                catch (Exception e) { failed(Describe(e)); more = false; }
                if (!more) yield break;
                yield return current is IEnumerator nested ? Guard(() => nested, failed) : current;
            }
        }

        static IEnumerator Done() { yield break; }

        /// <summary>Reads the bundles from a folder: by URL on WebGL (StreamingAssets is served beside the page; StreamingFetch
        /// retries a dropped connection, a 429 or a 5xx, #1054), from disk elsewhere. Each bundle must match its line of the
        /// checks file (<see cref="CollectionCatalog.ChecksFile"/> unless the catalog names another), written by the bundle build: Unity is given the bundle's CRC on both paths, and on disk a missing file, one that is not a whole
        /// AssetBundle by its header (<see cref="CheckHeader"/>) or one whose size or SHA-256 differs from the build fails at
        /// once without asking Unity to open it, so it logs this class's one warning and not Unity's own errors too.</summary>
        public sealed class BundleSource : ISource
        {
            readonly string folder, checksFile;
            readonly Dictionary<string, AssetBundle> open = new Dictionary<string, AssetBundle>(StringComparer.Ordinal);
            Dictionary<string, CollectionCatalog.BundleCheck>? checks;
            string? checksError;
            bool checksRead;

            public BundleSource(string folder, string checksFile = CollectionCatalog.ChecksFile) { this.folder = folder; this.checksFile = checksFile; }

            public IEnumerator Open(string bundle, Action<string?> done)
            {
                var path = Path.Combine(folder, bundle);
                AssetBundle? b = null;
                if (path.Contains("://"))
                {
                    yield return ReadChecks();
                    var (check, why) = Lookup(bundle);
                    if (check == null) { done(why); yield break; }
                    // Unity checks the CRC as it reads, and refuses a bundle that does not match (the request then fails,
                    // and is not retried: only no response or a server-side status is, StreamingFetch).
                    var url = folder + "/" + bundle;
                    var crc = check.Value.Crc;
                    var download = StreamingFetch.Start(() => UnityWebRequestAssetBundle.GetAssetBundle(url, crc));
                    string? failed = null;
                    yield return Await(StreamingFetch.Done(download, bundle, StreamingFetch.StallSeconds), e => failed = e);
                    if (failed != null) { done(failed); yield break; }
                    try { b = DownloadHandlerAssetBundle.GetContent(download.Request); }
                    finally { download.Release(); }
                }
                else
                {
#if UNITY_WEBGL && !UNITY_EDITOR
                    done("WebGL reads the bundles by URL, not from disk " + path); yield break;   // keeps SHA-256 out of the wasm
#else
                    if (!File.Exists(path)) { done("no file " + path); yield break; }
                    var damaged = CheckHeader(path);
                    if (damaged != null) { done(damaged + " " + path); yield break; }
                    yield return ReadChecks();
                    var (check, why) = Lookup(bundle);
                    if (check == null) { done(why); yield break; }
                    // The whole file against the build's size and SHA-256 first, so a damaged bundle never reaches Unity's
                    // reader (which logs errors of its own for one, and crashed the editor on a cut-short one).
                    if (new FileInfo(path).Length != check.Value.Bytes || CollectionCatalog.Sha256(path) != check.Value.Sha256)
                    { done("it does not match the build that made it: " + path); yield break; }
                    var op = AssetBundle.LoadFromFileAsync(path, check.Value.Crc);
                    yield return op;
                    b = op.assetBundle;
#endif
                }
                if (b == null) { done("not an AssetBundle"); yield break; }
                open[bundle] = b;
                done(null);
            }

            /// <summary>Reads the checks file once (by URL or from disk, like the bundles).</summary>
            IEnumerator ReadChecks()
            {
                if (checksRead) yield break;
                checksRead = true;
                string? text = null;
                if (folder.Contains("://"))
                {
                    var download = StreamingFetch.Get(folder + "/" + checksFile);
                    string? failed = null;
                    yield return Await(StreamingFetch.Done(download, checksFile, StreamingFetch.StallSeconds), e => failed = e);
                    if (failed != null) checksError = $"no {checksFile} ({failed})";
                    else
                    {
                        try { text = download.Request.downloadHandler.text; }
                        finally { download.Release(); }
                    }
                }
                else
                {
                    var file = Path.Combine(folder, checksFile);
                    if (File.Exists(file)) text = File.ReadAllText(file);
                    else checksError = "no file " + file;
                }
                if (text != null && (checks = CollectionCatalog.ParseChecks(text)) == null)
                    checksError = $"a damaged {checksFile}";
            }

            /// <summary>Waits a frame at a time for a StreamingFetch download (with its retries) to end; a final failure
            /// (the IOException naming the file) goes to <paramref name="failed"/>.</summary>
            static IEnumerator Await(Awaitable fetch, Action<string> failed)
            {
                var a = fetch.GetAwaiter();
                while (!a.IsCompleted) yield return null;
                try { a.GetResult(); }
                catch (IOException e) { failed(e.Message); }
            }

            /// <summary>The bundle's line of the checks file, or null and why not.</summary>
            (CollectionCatalog.BundleCheck? Check, string Why) Lookup(string bundle)
            {
                if (checks == null) return (null, checksError ?? "no " + checksFile);
                return checks.TryGetValue(bundle, out var c) ? (c, "") : (null, $"not in {checksFile}");
            }

            public IEnumerator Load(string bundle, string path, Action<GameObject?> done)
            {
                var op = open[bundle].LoadAssetAsync<GameObject>(path);
                yield return op;
                done(op.asset as GameObject);
            }

            /// <summary>Null when the file at <paramref name="path"/> starts with an AssetBundle header ("UnityFS", format
            /// version, two version strings, then the whole file's size, big-endian) whose size is the file's own; else why
            /// not. (Unity's own reader would log an error for such a file, on top of this class's warning.)</summary>
            public static string? CheckHeader(string path)
            {
                try
                {
                    using var f = File.OpenRead(path);
                    using var r = new BinaryReader(f);
                    string Text()
                    {
                        var b = new List<byte>();
                        for (int c; (c = f.ReadByte()) > 0 && b.Count < 64;) b.Add((byte)c);
                        return System.Text.Encoding.ASCII.GetString(b.ToArray());
                    }
                    if (Text() != "UnityFS") return "not an AssetBundle";
                    if (f.Length < f.Position + 4) return "not an AssetBundle";
                    r.ReadBytes(4);   // format version
                    Text();           // engine versions
                    Text();
                    var size = r.ReadBytes(8);
                    if (size.Length < 8) return "not an AssetBundle";
                    long declared = 0;
                    foreach (var b in size) declared = (declared << 8) | b;
                    return declared == f.Length ? null : $"a damaged AssetBundle ({f.Length} bytes, its header says {declared})";
                }
                catch (Exception e) when (e is IOException || e is UnauthorizedAccessException) { return "unreadable (" + e.Message + ")"; }
            }

            /// <summary>Unloads one retired bundle and its objects; other acquired consumers keep their own bundles.</summary>
            public void Unload(string bundle)
            {
                if (!open.TryGetValue(bundle, out var asset)) return;
                if (asset != null) asset.Unload(true); open.Remove(bundle);
            }

            /// <summary>Unloads every bundle this source opened, and the objects loaded from them.</summary>
            public void UnloadAll()
            {
                foreach (var b in open.Values) b.Unload(true);
                open.Clear();
            }
        }

#if UNITY_EDITOR
        /// <summary>The editor's source: the prefabs as they stand in the project.</summary>
        public sealed class EditorSource : ISource
        {
            public void Unload(string bundle) { } // AssetDatabase owns these assets; never destroy them.

            public IEnumerator Open(string bundle, Action<string?> done) { done(null); yield break; }

            public IEnumerator Load(string bundle, string path, Action<GameObject?> done)
            {
                done(UnityEditor.AssetDatabase.LoadAssetAtPath<GameObject>(path));
                yield break;
            }
        }
#endif
    }
}