EngineState.cs

using System.IO.Compression;
using Gondwana.Assets;
using Gondwana.Audio;
using Gondwana.Audio.GSND;
using Gondwana.Drawing;
using Gondwana.Drawing.Animation;
using Gondwana.Drawing.Animation.GANI;
using Gondwana.Drawing.Sprites;
using Gondwana.Drawing.Sprites.GSPR;
using Gondwana.Drawing.Tilesheets;
using Gondwana.Drawing.Tilesheets.GTS;
using Gondwana.Scenes;
using Gondwana.Scenes.GSCN;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
 
namespace Gondwana;

[JsonObject(IsReference = true)]
public sealed partial class EngineState
{
    [JsonConverter(typeof(SpriteStateEntryConverter))]
    private sealed class SpriteStateEntry : DefinitionStateEntry
    {
        public string? GsprPath { get; set; }
        public SpriteDefinition? Definition { get; set; }
        [JsonIgnore] public List<Sprite>? LegacySprites { get; set; }
    }
 
    private sealed class SpriteStateEntryConverter : JsonConverter<SpriteStateEntry>
    {
        public override SpriteStateEntry? ReadJson(JsonReader reader, Type objectType,
            SpriteStateEntry? existingValue, bool hasExistingValue, JsonSerializer serializer)
        {
            if (reader.TokenType == JsonToken.Null) return null;
            var token = JToken.Load(reader);
            // PreserveReferencesHandling.All wrapped historical arrays in $values.
            if (token is JArray || token["$values"] is not null)
                return new() { LegacySprites = token.ToObject<List<Sprite>>(serializer) };
            if (token is not JObject obj)
                throw new JsonSerializationException("Invalid Sprite state entry.");
            return new()
            {
                AssetsFilePath = obj.GetValue("AssetsFilePath", StringComparison.OrdinalIgnoreCase)?.ToObject<string>(serializer),
                AssetEntryName = obj.GetValue("AssetEntryName", StringComparison.OrdinalIgnoreCase)?.ToObject<string>(serializer),
                GsprPath = obj.GetValue("GsprPath", StringComparison.OrdinalIgnoreCase)?.ToObject<string>(serializer),
                Definition = obj.GetValue("Definition", StringComparison.OrdinalIgnoreCase)?.ToObject<SpriteDefinition>(serializer)
            };
        }
        public override bool CanWrite => false;
        public override void WriteJson(JsonWriter writer, SpriteStateEntry? value, JsonSerializer serializer) => throw new NotSupportedException();
    }

    private sealed class TilesheetStateEntry : DefinitionStateEntry
    {
        [JsonProperty]
        public string? GtsPath { get; set; }

        [JsonProperty]
        public TilesheetDefinition? Definition { get; set; }
    }
 

    private sealed class AnimationStateEntry : DefinitionStateEntry
    {
        [JsonProperty]
        public string? GaniPath { get; set; }

        [JsonProperty]
        public AnimationDefinition? Definition { get; set; }
    }

    private sealed class AudioStateEntry : DefinitionStateEntry
    {
        [JsonProperty]
        public string? GsndPath { get; set; }

        [JsonProperty]
        public AudioDefinition? Definition { get; set; }
    }

    [JsonConverter(typeof(SceneStateEntryConverter))]
    private sealed class SceneStateEntry : DefinitionStateEntry
    {
        [JsonProperty]
        public string? GscnPath { get; set; }

        [JsonProperty]
        public SceneDefinition? Definition { get; set; }

        [JsonIgnore]
        public Scene? LegacyScene { get; set; }
    }

    private sealed class SceneStateEntryConverter : JsonConverter<SceneStateEntry>
    {
        public override SceneStateEntry? ReadJson(
            JsonReader reader,
            Type objectType,
            SceneStateEntry? existingValue,
            bool hasExistingValue,
            JsonSerializer serializer)
        {
            if (reader.TokenType == JsonToken.Null)
                return null;
 
            var obj = JObject.Load(reader);
 
            if (obj.Property(nameof(SceneStateEntry.GscnPath), StringComparison.OrdinalIgnoreCase) is not null ||
                obj.Property(nameof(SceneStateEntry.Definition), StringComparison.OrdinalIgnoreCase) is not null ||
                obj.Property("AssetsFilePath", StringComparison.OrdinalIgnoreCase) is not null ||
                obj.Property("AssetEntryName", StringComparison.OrdinalIgnoreCase) is not null)
            {
                return new SceneStateEntry
                {
                    AssetsFilePath = obj.GetValue("AssetsFilePath", StringComparison.OrdinalIgnoreCase)?.ToObject<string>(serializer),
                    AssetEntryName = obj.GetValue("AssetEntryName", StringComparison.OrdinalIgnoreCase)?.ToObject<string>(serializer),
                    GscnPath = obj.GetValue(
                        nameof(SceneStateEntry.GscnPath),
                        StringComparison.OrdinalIgnoreCase)?.ToObject<string>(serializer),
                    Definition = obj.GetValue(
                        nameof(SceneStateEntry.Definition),
                        StringComparison.OrdinalIgnoreCase)?.ToObject<SceneDefinition>(serializer)
                };
            }
 
            // Backward compatibility: pre-GSCN EngineState files stored Scene objects
            // directly in the Scenes list. Keep the deserialized instance intact so any
            // preserved references from other legacy objects still resolve to it.
            var legacyScene = obj.ToObject<Scene>(serializer)
                ?? throw new JsonSerializationException(
                    "Legacy EngineState scene entry deserialized to null.");
 
            return new SceneStateEntry
            {
                LegacyScene = legacyScene
            };
        }

        public override void WriteJson(
            JsonWriter writer,
            SceneStateEntry? value,
            JsonSerializer serializer) =>
            throw new NotSupportedException();

        public override bool CanWrite => false;
    }

    public static JsonSerializerSettings JsonSerializerSettings { get; set; }
        = new JsonSerializerSettings
        {
            TypeNameHandling = TypeNameHandling.Auto,
            Formatting = Formatting.Indented,
            PreserveReferencesHandling = PreserveReferencesHandling.All,
            Converters =
            {
                new FrameJsonConverter()
            }
        };

    [JsonProperty]
    public IEnumerable<AssetsFile> AssetsFiles => AssetsFile.AllAssetsFiles;

    [JsonProperty]
    public IDictionary<string, TilesheetDefinition> Tilesheets => CaptureTilesheetDefinitions(baseDirectory: null);

    [JsonProperty]
    public Dictionary<string, Cycle> Cycles => Cycle._cycles;

    [JsonProperty]
    public List<Scene> Scenes => Scene._allScenes;

    [JsonProperty]
    public List<Sprite> Sprites => SpriteManager.Instance._spriteList;

    [JsonProperty]
    public Dictionary<string, AudioResource> SoundResources => AudioResourceManager.Instance.GetAll();

    [JsonIgnore]
    public TypedValueBag ValueBag { get; set; } = new();

    internal void Clear()
    {
        AssetsFile.ClearAll();
        TilesheetRegistry.Instance.Clear();
        Cycle.ClearAllAnimationCycles();
        Scene.ClearAllScenes();
        SpriteManager.Instance.Clear();
        AudioResourceManager.Instance.Dispose();
        ValueBag.Clear();
    }

    public void SaveToFile(string path,
                           bool compress = false,
                           bool separateGtsFiles = false,
                           EngineStateParts parts = EngineStateParts.All,
                           bool separateGscnFiles = false,
                           bool separateGaniFiles = false,
                           bool separateGsndFile = false,
                           bool separateGsprFile = false)
        => SaveToFile(path, new EngineStateSaveOptions
        {
            Compress = compress,
            Parts = parts,
            Tilesheets = separateGtsFiles ? DefinitionPersistence.Loose : DefinitionPersistence.Inline,
            Scenes = separateGscnFiles ? DefinitionPersistence.Loose : DefinitionPersistence.Inline,
            Cycles = separateGaniFiles ? DefinitionPersistence.Loose : DefinitionPersistence.Inline,
            Audio = separateGsndFile ? DefinitionPersistence.Loose : DefinitionPersistence.Inline,
            Sprites = separateGsprFile ? DefinitionPersistence.Loose : DefinitionPersistence.Inline
        });

    public void SaveToFile(string path, EngineStateSaveOptions options)
    {
        if (string.IsNullOrWhiteSpace(path))
            throw new ArgumentException("Engine state path must be a non-empty string.", nameof(path));
 
        var fullPath = Path.GetFullPath(path);
        var baseDirectory = Path.GetDirectoryName(fullPath);
 
        ArgumentNullException.ThrowIfNull(options);
        foreach (var mode in new[] { options.Tilesheets, options.Cycles, options.Scenes, options.Audio, options.Sprites })
            if (!Enum.IsDefined(mode)) throw new ArgumentOutOfRangeException(nameof(options));
        var parts = options.Parts;
        if (parts.HasFlag(EngineStateParts.Sprites) && options.Sprites == DefinitionPersistence.PreserveSource)
            parts |= EngineStateParts.Scenes | EngineStateParts.Cycles | EngineStateParts.Tilesheets;
        if (parts.HasFlag(EngineStateParts.Scenes) && options.Scenes == DefinitionPersistence.PreserveSource)
            parts |= EngineStateParts.Cycles | EngineStateParts.Tilesheets;
        var snapshot = BuildSnapshot(NormalizeParts(parts), baseDirectory, fullPath, options);
 
        var json = JsonConvert.SerializeObject(snapshot, JsonSerializerSettings);
 
        if (options.Compress)
        {
            using var file = File.Create(fullPath);
            using var zip = new GZipStream(file, CompressionMode.Compress);
            using var writer = new StreamWriter(zip);
            writer.Write(json);
        }
        else
        {
            File.WriteAllText(fullPath, json);
        }
    }

    public static void LoadFromFile(string path, bool compressed = false, EngineStateParts parts = EngineStateParts.All)
    {
        if (string.IsNullOrWhiteSpace(path))
            throw new ArgumentException("Engine state path must be a non-empty string.", nameof(path));
 
        var fullPath = Path.GetFullPath(path);
        var baseDirectory = Path.GetDirectoryName(fullPath);
 
        string json = ReadJsonFile(fullPath, compressed);
 
        // Important: EngineState's collections are mostly getter-only proxies over registries,
        // so deserialize into a snapshot DTO with setters.
        var snapshot =
            JsonConvert.DeserializeObject<EngineStateSnapshot>(json, JsonSerializerSettings)
            ?? new EngineStateSnapshot();
 
        // Merge into the live engine state (registries)
        ApplySnapshot(snapshot, clearExisting: true, overwriteExisting: true, parts, baseDirectory);
    }

    public static void MergeFromFile(string path, bool compressed = false, bool overwriteExisting = false, EngineStateParts parts = EngineStateParts.All)
    {
        if (string.IsNullOrWhiteSpace(path))
            throw new ArgumentException("Engine state path must be a non-empty string.", nameof(path));
 
        var fullPath = Path.GetFullPath(path);
        var baseDirectory = Path.GetDirectoryName(fullPath);
 
        string json = ReadJsonFile(fullPath, compressed);
 
        var snapshot =
            JsonConvert.DeserializeObject<EngineStateSnapshot>(json, JsonSerializerSettings)
            ?? new EngineStateSnapshot();
 
        // Merge into the live engine state (registries)
        ApplySnapshot(snapshot, clearExisting: false, overwriteExisting: overwriteExisting, parts, baseDirectory);
    }
 
    #region deserialization helpers
 
    private sealed class EngineStateSnapshot
    {
        [JsonProperty(TypeNameHandling = TypeNameHandling.None, ItemTypeNameHandling = TypeNameHandling.None)]
        public List<AssetsFileStateEntry>? AssetsFiles { get; set; }
        [JsonProperty] public Dictionary<string, TilesheetStateEntry>? Tilesheets { get; set; }
        [JsonProperty] public Dictionary<string, AnimationStateEntry>? Cycles { get; set; }
        [JsonProperty] public List<SceneStateEntry>? Scenes { get; set; }
        [JsonProperty] public SpriteStateEntry? Sprites { get; set; }
        [JsonProperty] public AudioStateEntry? Audio { get; set; }
 
        // Legacy compatibility: pre-GSND EngineState files serialized runtime
        // AudioResource objects directly under SoundResources.
        [JsonProperty] public Dictionary<string, AudioResource>? SoundResources { get; set; }
    }
 
    private static EngineStateParts NormalizeParts(EngineStateParts parts, EngineStateSnapshot? snapshot = null)
    {
        // Expand content dependencies for packed definitions without changing legacy
        // sprite-only and scene-only merges that deliberately use existing registries.
        if (parts.HasFlag(EngineStateParts.Sprites) && snapshot?.Sprites?.AssetsFilePath is not null)
        {
            if (snapshot.Scenes is not null) parts |= EngineStateParts.Scenes;
            if (snapshot.Cycles is not null) parts |= EngineStateParts.Cycles;
            if (snapshot.Tilesheets is not null) parts |= EngineStateParts.Tilesheets;
        }
        if (parts.HasFlag(EngineStateParts.Scenes) && snapshot?.Scenes?.Any(entry => entry?.AssetsFilePath is not null) == true)
        {
            if (snapshot.Cycles is not null) parts |= EngineStateParts.Cycles;
            if (snapshot.Tilesheets is not null) parts |= EngineStateParts.Tilesheets;
        }
 
        // GANI definitions resolve Frame references through the TilesheetRegistry.
        if (parts.HasFlag(EngineStateParts.Cycles))
            parts |= EngineStateParts.Tilesheets;
 
        // Tilesheets and Audio may depend on AssetsFiles for AssetIdentifier.Data.
        if (parts.HasFlag(EngineStateParts.Tilesheets) ||
            parts.HasFlag(EngineStateParts.Audio) ||
            (parts.HasFlag(EngineStateParts.Scenes) && snapshot?.Scenes?.Any(entry => entry?.AssetsFilePath is not null) == true) ||
            (parts.HasFlag(EngineStateParts.Sprites) && snapshot?.Sprites?.AssetsFilePath is not null))
        {
            parts |= EngineStateParts.AssetsFiles;
        }
 
        return parts;
    }
 
    private EngineStateSnapshot BuildSnapshot(EngineStateParts parts,
                                              string? baseDirectory,
                                              string engineStatePath,
                                              EngineStateSaveOptions options)
    {
        return new EngineStateSnapshot
        {
            AssetsFiles = parts.HasFlag(EngineStateParts.AssetsFiles)
                ? AssetsFiles.Where(file => !string.IsNullOrWhiteSpace(file.SourcePath))
                    .Select(file => new AssetsFileStateEntry
                    {
                        FilePath = MakeRelativePath(file.SourcePath!, baseDirectory),
                        Password = file.Password,
                        UseEncryption = file.UseEncryption
                    }).ToList()
                : null,
 
            Tilesheets = parts.HasFlag(EngineStateParts.Tilesheets)
                ? CaptureTilesheetEntries(
                    baseDirectory,
                    engineStatePath,
                    options.Tilesheets)
                : null,
 
            Cycles = parts.HasFlag(EngineStateParts.Cycles)
                ? CaptureAnimationEntries(
                    baseDirectory,
                    engineStatePath,
                    options.Cycles)
                : null,
 
            Scenes = parts.HasFlag(EngineStateParts.Scenes)
                ? CaptureSceneEntries(
                    baseDirectory,
                    engineStatePath,
                    options.Scenes)
                : null,
 
            Sprites = parts.HasFlag(EngineStateParts.Sprites)
                ? CaptureSpriteEntry(baseDirectory, engineStatePath, options.Sprites)
                : null,
 
            Audio = parts.HasFlag(EngineStateParts.Audio)
                ? CaptureAudioEntry(
                    baseDirectory,
                    engineStatePath,
                    options.Audio)
                : null,
 
            // New saves use the clean GSND definition shape. This member remains
            // only so older EngineState files can still be read.
            SoundResources = null,
        };
    }
 
    private SpriteStateEntry CaptureSpriteEntry(string? baseDirectory, string engineStatePath, DefinitionPersistence persistence)
    {
        var definition = SpriteDefinitionSerializer.FromSprites(SpriteManager.Instance.AllSprites);
        var entry = new SpriteStateEntry();
        if (TryPreserve(entry, SpriteManager.Instance.DefinitionProvenance, definition, persistence, baseDirectory, out var loosePath))
        {
            entry.GsprPath = loosePath;
            return entry;
        }
        if (persistence != DefinitionPersistence.Loose) return new() { Definition = definition };
        var path = Path.Combine(Path.GetDirectoryName(engineStatePath)!,
            Path.GetFileNameWithoutExtension(engineStatePath) + ".sprites.gspr");
        SpriteDefinitionSerializer.Save(path, definition);
        return new() { GsprPath = MakeRelativePath(path, baseDirectory) };
    }
 
    private static AudioStateEntry CaptureAudioEntry(
        string? baseDirectory,
        string engineStatePath,
        DefinitionPersistence persistence)
    {
        var entry = new AudioStateEntry();
        var currentAudio = AudioDefinitionSerializer.FromManager(AudioResourceManager.Instance);
        if (TryPreserve(entry, AudioResourceManager.Instance.DefinitionProvenance,
            currentAudio, persistence, baseDirectory, out var loosePath))
        {
            entry.GsndPath = loosePath;
            return entry;
        }
        // Anonymous stream packages cannot be named in a reloadable GSND. Export their
        // audio payloads to loose files; do not invent or mutate an archive.
        var anonymousAudio = currentAudio.Resources.Where(resource =>
            resource.SourceKind == AudioResourceSourceKind.PackedAsset &&
            string.IsNullOrWhiteSpace(resource.AssetsFilePath)).ToList();
        if (anonymousAudio.Count != 0)
        {
            var directory = GetAudioStateDirectory(engineStatePath);
            Directory.CreateDirectory(directory);
            for (int i = 0; i < anonymousAudio.Count; i++)
            {
                var resource = anonymousAudio[i];
                var runtime = AudioResourceManager.Instance.Get(resource.Key)!;
                var extension = Path.GetExtension(runtime.SourceExtension ?? ".wav");
                var mediaPath = Path.Combine(directory, $"{i}-{SanitizeFileName(resource.Key)}{extension}");
                using (var source = runtime.AssetIdentifier!.Data)
                using (var output = File.Create(mediaPath))
                    source.CopyTo(output);
                resource.SourceKind = AudioResourceSourceKind.LooseFile;
                resource.FilePath = mediaPath;
                resource.AssetsFilePath = null;
                resource.AssetEntryName = null;
            }
            var definitionPath = Path.Combine(directory, "audio.gsnd");
            AudioDefinitionSerializer.Save(definitionPath, currentAudio);
            return new AudioStateEntry { GsndPath = MakeRelativePath(definitionPath, baseDirectory) };
        }
        if (persistence == DefinitionPersistence.Loose)
        {
            var gsndDirectory = GetAudioStateDirectory(engineStatePath);
            Directory.CreateDirectory(gsndDirectory);
 
            var gsndFullPath = Path.Combine(gsndDirectory, "audio.gsnd");
            AudioDefinitionSerializer.Save(
                gsndFullPath,
                AudioResourceManager.Instance);
 
            return new AudioStateEntry
            {
                GsndPath = MakeRelativePath(gsndFullPath, baseDirectory)
            };
        }
 
        return new AudioStateEntry
        {
            Definition = AudioDefinitionSerializer.FromManager(
                AudioResourceManager.Instance,
                baseDirectory,
                makePathsRelative: !string.IsNullOrWhiteSpace(baseDirectory))
        };
    }
 
    private static Dictionary<string, AnimationStateEntry> CaptureAnimationEntries(
        string? baseDirectory,
        string engineStatePath,
        DefinitionPersistence persistence)
    {
        var result = new Dictionary<string, AnimationStateEntry>(StringComparer.Ordinal);
        var usedFileNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
 
        // Work from a stable registry snapshot in case definitions are changed while
        // the EngineState snapshot is being assembled.
        foreach (var (key, cycle) in Cycle._cycles.ToList())
        {
            if (cycle is null)
                continue;
 
            var preserved = new AnimationStateEntry();
            if (cycle.DefinitionProvenance is { } provenance &&
                TryPreserve(preserved, provenance, AnimationDefinitionSerializer.FromCycle(cycle), persistence, baseDirectory, out var loosePath))
            {
                preserved.GaniPath = loosePath;
                result[key] = preserved;
                continue;
            }
 
            if (persistence == DefinitionPersistence.Loose)
            {
                var ganiDirectory = GetAnimationStateDirectory(engineStatePath);
                Directory.CreateDirectory(ganiDirectory);
 
                var baseFileName = SanitizeFileName(key);
                var ganiFileName = $"{baseFileName}.gani";
                int suffix = 2;
 
                while (!usedFileNames.Add(ganiFileName))
                    ganiFileName = $"{baseFileName}_{suffix++}.gani";
 
                var ganiFullPath = Path.Combine(ganiDirectory, ganiFileName);
 
                // Use the standalone serializer so .gani files do not acquire
                // EngineState-specific $id/$ref metadata.
                AnimationDefinitionSerializer.Save(ganiFullPath, cycle);
 
                result[key] = new AnimationStateEntry
                {
                    GaniPath = MakeRelativePath(ganiFullPath, baseDirectory)
                };
            }
            else
            {
                result[key] = new AnimationStateEntry
                {
                    Definition = AnimationDefinitionSerializer.FromCycle(cycle)
                };
            }
        }
 
        return result;
    }
 
    private static List<SceneStateEntry> CaptureSceneEntries(
        string? baseDirectory,
        string engineStatePath,
        DefinitionPersistence persistence)
    {
        var result = new List<SceneStateEntry>();
        var usedFileNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
 
        // Work from a stable snapshot. Scene construction/disposal may occur on
        // other threads while a state file is being assembled.
        foreach (var scene in Scene._allScenes.ToList())
        {
            if (scene is null)
                continue;
 
            var preserved = new SceneStateEntry();
            if (scene.DefinitionProvenance is { } provenance &&
                TryPreserve(preserved, provenance, SceneDefinitionSerializer.FromScene(scene), persistence, baseDirectory, out var loosePath))
            {
                preserved.GscnPath = loosePath;
                result.Add(preserved);
                continue;
            }
 
            if (persistence == DefinitionPersistence.Loose)
            {
                var gscnDirectory = GetSceneStateDirectory(engineStatePath);
                Directory.CreateDirectory(gscnDirectory);
 
                var baseFileName = SanitizeFileName(scene.ID);
                var gscnFileName = $"{baseFileName}.gscn";
                int suffix = 2;
 
                while (!usedFileNames.Add(gscnFileName))
                    gscnFileName = $"{baseFileName}_{suffix++}.gscn";
 
                var gscnFullPath = Path.Combine(gscnDirectory, gscnFileName);
 
                // Use the standalone GSCN serializer so the external file remains a
                // clean scene definition without EngineState $id/$ref metadata.
                SceneDefinitionSerializer.Save(gscnFullPath, scene);
 
                result.Add(new SceneStateEntry
                {
                    GscnPath = MakeRelativePath(
                        gscnFullPath,
                        baseDirectory)
                });
            }
            else
            {
                result.Add(new SceneStateEntry
                {
                    Definition = SceneDefinitionSerializer.FromScene(scene)
                });
            }
        }
 
        return result;
    }
 
    private static string ReadJsonFile(string path, bool compressed)
    {
        if (compressed)
        {
            using var file = File.OpenRead(path);
            using var zip = new GZipStream(file, CompressionMode.Decompress);
            using var reader = new StreamReader(zip);
            return reader.ReadToEnd();
        }
        else
        {
            return File.ReadAllText(path);
        }
    }

    private static void ApplySnapshot(
        EngineStateSnapshot snapshot,
        bool clearExisting,
        bool overwriteExisting,
        EngineStateParts parts,
        string? baseDirectory)
    {
        parts = NormalizeParts(parts, snapshot);
 
        // Legacy raw objects may register themselves while the snapshot DTO is
        // deserialized. Detach those incoming instances before clearing or merging so
        // they are treated as snapshot data rather than pre-existing live state.
        DetachLegacySnapshotScenes(snapshot.Scenes);
        DetachSnapshotSprites(snapshot.Sprites?.LegacySprites);
 
        ValidateSelectedSources(snapshot, parts);
 
        // clear only what we're about to load.
        if (clearExisting)
            ClearSelected(parts);
 
        if (parts.HasFlag(EngineStateParts.AssetsFiles))
            LoadAssetsFiles(snapshot.AssetsFiles ?? Enumerable.Empty<AssetsFileStateEntry>(), overwriteExisting, baseDirectory, PackedEntries(snapshot, parts));
 
        if (parts.HasFlag(EngineStateParts.Audio))
            MergeAudio(
                snapshot.AssetsFiles?.Select(raw => FindAssetsFile(ResolvePath(raw.FilePath, baseDirectory)))
                    .OfType<AssetsFile>().ToList(),
                snapshot.Audio,
                snapshot.SoundResources,
                overwriteExisting,
                baseDirectory);
 
        if (parts.HasFlag(EngineStateParts.Tilesheets))
            MergeTilesheets(snapshot.Tilesheets, overwriteExisting, baseDirectory);
 
        if (parts.HasFlag(EngineStateParts.Cycles))
            MergeAnimations(snapshot.Cycles, overwriteExisting, baseDirectory);
 
        if (parts.HasFlag(EngineStateParts.Scenes))
            MergeScenes(snapshot.Scenes, overwriteExisting, baseDirectory);
 
        if (parts.HasFlag(EngineStateParts.Sprites))
        {
            var entry = snapshot.Sprites;
            if (entry is not null)
            {
                var incoming = entry.LegacySprites;
                if (incoming is null)
                {
                    var definition = entry.AssetsFilePath is not null
                        ? LoadPacked(entry, baseDirectory, AssetTypes.SpriteDefinition, SpriteDefinitionSerializer.Load)
                        : !string.IsNullOrWhiteSpace(entry.GsprPath)
                        ? SpriteDefinitionSerializer.Load(ResolvePath(entry.GsprPath, baseDirectory))
                        : entry.Definition ?? throw new InvalidDataException("Sprite state entry requires GsprPath or Definition.");
                    incoming = WithDefinitionContext(entry, baseDirectory,
                        () => SpriteDefinitionSerializer.ToSprites(definition, allowDuplicateNicknames: true));
                    DetachSnapshotSprites(incoming);
                }
                MergeSprites(incoming, overwriteExisting);
            }
        }
    }
 
    private static void ClearSelected(EngineStateParts parts)
    {
        if (parts.HasFlag(EngineStateParts.AssetsFiles))
        {
            AssetsFile.ClearAll();
            SvgResourceManager.Instance.Clear();
        }
 
        if (parts.HasFlag(EngineStateParts.Tilesheets))
            TilesheetRegistry.Instance.Clear();
 
        if (parts.HasFlag(EngineStateParts.Cycles))
            Cycle.ClearAllAnimationCycles();
 
        if (parts.HasFlag(EngineStateParts.Scenes))
            Scene.ClearAllScenes();
 
        if (parts.HasFlag(EngineStateParts.Sprites))
        {
            SpriteManager.Instance.DefinitionProvenance = null;
            // EngineState replacement is synchronous; normal game-loop disposal is deferred.
            foreach (var sprite in SpriteManager.Instance.AllSprites)
            {
                SpriteManager.Instance._spriteList.Remove(sprite);
                sprite.DisposeImmediate();
            }
        }
 
        if (parts.HasFlag(EngineStateParts.Audio))
            AudioResourceManager.Instance.Dispose();
    }
 
    private static void LoadAssetsFiles(IEnumerable<AssetsFileStateEntry> resourceFiles, bool overwriteExisting, string? baseDirectory, IEnumerable<DefinitionStateEntry> packedEntries)
    {
        // Replace raw deserialized resource files with proper loaded instances
        if (resourceFiles.Any())
        {
            foreach (var raw in resourceFiles)
            {
                try
                {
                    var path = ResolvePath(raw.FilePath, baseDirectory);
                    var loaded = FindAssetsFile(path);
                    if (loaded is null)
                    {
                        if (!File.Exists(path)) throw new FileNotFoundException($"EngineState assets file not found: {path}", path);
                        loaded = AssetsFile.LoadOrCreate(path, raw.Password, raw.UseEncryption);
                    }
 
                    if (overwriteExisting)
                    {
                        foreach (var entry in loaded.GetAllEntries().Where(e => e.AssetType == AssetTypes.Svg))
                            SvgResourceManager.Instance.Unload(entry.AssetName);
                    }
 
                    SvgResourceManager.Instance.LoadFromEngineAssetsFile(loaded);
                }
                catch (Exception ex)
                {
                    Engine.Logger.LogError(ex, "Failed to load resource file '{FilePath}'", raw.FilePath);
                    var dependency = packedEntries.FirstOrDefault(entry => string.Equals(
                        ResolvePath(entry.AssetsFilePath!, baseDirectory), ResolvePath(raw.FilePath, baseDirectory),
                        OperatingSystem.IsWindows() ? StringComparison.OrdinalIgnoreCase : StringComparison.Ordinal));
                    if (dependency is not null)
                        throw new InvalidDataException($"Cannot load packed definition '{dependency.AssetEntryName}' from GAF '{ResolvePath(raw.FilePath, baseDirectory)}'.", ex);
                    throw;
                }
            }
        }
    }
 
    private static void MergeAudio(
        List<AssetsFile>? assetsFiles,
        AudioStateEntry? audio,
        Dictionary<string, AudioResource>? soundSpecs,
        bool overwriteExisting,
        string? baseDirectory)
    {
        if (audio is not null)
        {
            AudioDefinition definition;
 
            if (audio.AssetsFilePath is not null)
            {
                definition = LoadPacked(audio, baseDirectory, AssetTypes.AudioDefinition, AudioDefinitionSerializer.Load);
            }
            else if (!string.IsNullOrWhiteSpace(audio.GsndPath))
            {
                definition = AudioDefinitionSerializer.Load(
                    ResolvePath(audio.GsndPath, baseDirectory));
            }
            else if (audio.Definition is not null)
            {
                definition = audio.Definition;
            }
            else
            {
                throw new InvalidDataException(
                    "Audio state entry does not contain a GSND path or inline definition.");
            }
 
            WithDefinitionContext(audio, baseDirectory, () => AudioDefinitionSerializer.LoadIntoManager(
                definition,
                overwriteExisting,
                audio.Definition is not null ? baseDirectory :
                    audio.GsndPath is not null ? Path.GetDirectoryName(ResolvePath(audio.GsndPath, baseDirectory)) : null));
            return;
        }
 
        // Legacy EngineState compatibility: load old asset packs first, then
        // apply the serialized AudioResource specs / overrides.
        if (assetsFiles is not null)
        {
            foreach (var af in assetsFiles)
            {
                if (overwriteExisting)
                {
                    foreach (var entry in af.GetAllEntries())
                    {
                        if (entry.AssetType == AssetTypes.Audio)
                            AudioResourceManager.Instance.Unload(entry.AssetName);
                    }
                }
 
                AudioResourceManager.Instance.LoadFromEngineAssetsFile(af);
            }
        }
 
        // 2) Apply loose-file specs / overrides
        if (soundSpecs is null)
            return;
 
        foreach (var (key, spec) in soundSpecs)
        {
            if (AudioResourceManager.Instance.Contains(key))
            {
                if (!overwriteExisting)
                {
                    var existing = AudioResourceManager.Instance.Get(key);
                    if (existing is not null)
                    {
                        existing.Volume = spec.Volume;
                        existing.Pan = spec.Pan;
                        existing.PlaybackSpeed = spec.PlaybackSpeed;
                        existing.IsLooping = spec.IsLooping;
                    }
                    continue;
                }
 
                AudioResourceManager.Instance.Unload(key);
            }
 
            // Ensure the audio spec is (re)created/registered in the manager.
            spec.ReloadIntoManager();
        }
    }
 
    private static Dictionary<string, TilesheetDefinition> CaptureTilesheetDefinitions(string? baseDirectory)
    {
        return TilesheetRegistry.Instance
            .GetAll()
            .ToDictionary(
                kvp => kvp.Key,
                kvp => TilesheetDefinitionSerializer.FromTilesheet(
                    kvp.Value,
                    baseDirectory,
                    makePathsRelative: !string.IsNullOrWhiteSpace(baseDirectory)));
    }
 
    private static Dictionary<string, TilesheetStateEntry> CaptureTilesheetEntries(
        string? baseDirectory,
        string engineStatePath,
        DefinitionPersistence persistence)
    {
        var result = new Dictionary<string, TilesheetStateEntry>(StringComparer.Ordinal);
 
        foreach (var (key, tilesheet) in TilesheetRegistry.Instance.GetAll())
        {
            var preserved = new TilesheetStateEntry();
            if (tilesheet.DefinitionProvenance is { } provenance &&
                TryPreserve(preserved, provenance, TilesheetDefinitionSerializer.FromTilesheet(tilesheet), persistence, baseDirectory, out var loosePath))
            {
                preserved.GtsPath = loosePath;
                result[key] = preserved;
                continue;
            }
 
            if (persistence == DefinitionPersistence.Loose ||
                (persistence == DefinitionPersistence.PreserveSource &&
                 string.IsNullOrWhiteSpace(tilesheet.ImageFilePath) &&
                 string.IsNullOrWhiteSpace(tilesheet.AssetIdentifier?.AssetsFile.SourcePath)))
            {
                var gtsDirectory = GetTilesheetStateDirectory(engineStatePath);
                Directory.CreateDirectory(gtsDirectory);
 
                var gtsFileName = $"{SanitizeFileName(key)}.gts";
                var gtsFullPath = Path.Combine(gtsDirectory, gtsFileName);
 
                // Important:
                // Save the GTS using the GTS serializer, not EngineState.JsonSerializerSettings.
                // This avoids $id/$values noise in the .gts file.
                TilesheetDefinitionSerializer.Save(
                    gtsFullPath,
                    tilesheet,
                    makePathsRelative: true);
 
                var gtsPathForState = MakeRelativePath(
                    gtsFullPath,
                    baseDirectory);
 
                result[key] = new TilesheetStateEntry
                {
                    GtsPath = gtsPathForState
                };
            }
            else
            {
                result[key] = new TilesheetStateEntry
                {
                    Definition = TilesheetDefinitionSerializer.FromTilesheet(
                        tilesheet,
                        baseDirectory,
                        makePathsRelative: !string.IsNullOrWhiteSpace(baseDirectory))
                };
            }
        }
 
        return result;
    }
 
    private static string GetTilesheetStateDirectory(string engineStatePath)
    {
        var directory = Path.GetDirectoryName(engineStatePath) ?? string.Empty;
        var fileName = Path.GetFileNameWithoutExtension(engineStatePath);
 
        return Path.Combine(directory, $"{fileName}.tilesheets");
    }
 
 
    private static string GetAnimationStateDirectory(string engineStatePath)
    {
        var directory = Path.GetDirectoryName(engineStatePath) ?? string.Empty;
        var fileName = Path.GetFileNameWithoutExtension(engineStatePath);
 
        return Path.Combine(directory, $"{fileName}.animations");
    }
 
 
    private static string GetAudioStateDirectory(string engineStatePath)
    {
        var directory = Path.GetDirectoryName(engineStatePath) ?? string.Empty;
        var fileName = Path.GetFileNameWithoutExtension(engineStatePath);
 
        return Path.Combine(directory, $"{fileName}.audio");
    }
 
 
    private static string GetSceneStateDirectory(string engineStatePath)
    {
        var directory = Path.GetDirectoryName(engineStatePath) ?? string.Empty;
        var fileName = Path.GetFileNameWithoutExtension(engineStatePath);
 
        return Path.Combine(directory, $"{fileName}.scenes");
    }
 
    private static string MakeRelativePath(string path, string? baseDirectory)
    {
        if (string.IsNullOrWhiteSpace(baseDirectory))
            return path;
 
        return Path.GetRelativePath(
            Path.GetFullPath(baseDirectory),
            Path.GetFullPath(path));
    }
 
    private static string SanitizeFileName(string value)
    {
        if (string.IsNullOrWhiteSpace(value))
            return Guid.NewGuid().ToString("N");
 
        var invalidChars = Path.GetInvalidFileNameChars();
        var sanitized = new string(
            value.Select(ch => invalidChars.Contains(ch) ? '_' : ch).ToArray());
 
        return string.IsNullOrWhiteSpace(sanitized)
            ? Guid.NewGuid().ToString("N")
            : sanitized;
    }
 
    private static void MergeTilesheets(
        Dictionary<string, TilesheetStateEntry>? tilesheets,
        bool overwriteExisting,
        string? baseDirectory)
    {
        if (tilesheets is null || tilesheets.Count == 0)
            return;
 
        var registry = TilesheetRegistry.Instance.GetAll();
 
        foreach (var (key, entry) in tilesheets)
        {
            if (entry is null)
                continue;
 
            var existingKey = key;
 
            if (!overwriteExisting && registry.ContainsKey(existingKey))
                continue;
 
            Tilesheet rebuilt;
 
            if (entry.AssetsFilePath is not null)
            {
                rebuilt = LoadPacked(entry, baseDirectory, AssetTypes.TilesheetDefinition, TilesheetFactory.FromDefinitionAsset);
            }
            else if (!string.IsNullOrWhiteSpace(entry.GtsPath))
            {
                var gtsPath = ResolvePath(entry.GtsPath, baseDirectory);
 
                rebuilt = TilesheetFactory.FromDefinitionFile(gtsPath);
            }
            else if (entry.Definition is not null)
            {
                if (string.IsNullOrWhiteSpace(entry.Definition.Name))
                    entry.Definition.Name = key;
 
                rebuilt = TilesheetFactory.FromDefinition(
                    entry.Definition,
                    baseDirectory);
            }
            else
            {
                throw new InvalidDataException(
                    $"Tilesheet state entry '{key}' does not contain a GTS path or inline definition.");
            }
 
            TilesheetRegistry.Instance.Register(
                rebuilt,
                disposeReplaced: overwriteExisting);
        }
    }
 
    private static string ResolvePath(string path, string? baseDirectory)
    {
        if (Path.IsPathRooted(path))
            return path;
 
        if (string.IsNullOrWhiteSpace(baseDirectory))
            return path;
 
        return Path.GetFullPath(Path.Combine(baseDirectory, path));
    }
 
    private static void MergeAnimations(
        Dictionary<string, AnimationStateEntry>? animations,
        bool overwriteExisting,
        string? baseDirectory)
    {
        if (animations is null || animations.Count == 0)
            return;
 
        var definitions = new List<AnimationDefinition>();
        var sourceEntries = new Dictionary<AnimationDefinition, AnimationStateEntry>();
 
        foreach (var (key, entry) in animations)
        {
            if (entry is null)
                continue;
 
            if (!overwriteExisting && Cycle._cycles.ContainsKey(key))
                continue;
 
            AnimationDefinition definition;
 
            if (entry.AssetsFilePath is not null)
            {
                definition = LoadPacked(entry, baseDirectory, AssetTypes.AnimationDefinition, AnimationDefinitionSerializer.Load);
            }
            else if (!string.IsNullOrWhiteSpace(entry.GaniPath))
            {
                var ganiPath = ResolvePath(entry.GaniPath, baseDirectory);
                definition = AnimationDefinitionSerializer.Load(ganiPath);
            }
            else if (entry.Definition is not null)
            {
                definition = entry.Definition;
            }
            else
            {
                throw new InvalidDataException(
                    $"Animation state entry '{key}' does not contain a GANI path or inline definition.");
            }
 
            if (string.IsNullOrWhiteSpace(definition.Key))
            {
                definition.Key = key;
            }
            else if (!string.Equals(definition.Key, key, StringComparison.Ordinal))
            {
                throw DefinitionError(entry, baseDirectory, new InvalidDataException(
                    $"Animation state entry '{key}' contains definition key '{definition.Key}'."));
            }
 
            definitions.Add(definition);
            sourceEntries.Add(definition, entry);
        }
 
        // Validate next-cycle identities before mutating the registry. Two-phase
        // materialization allows circular transitions such as idle -> blink -> idle.
        var availableKeys = new HashSet<string>(
            Cycle._cycles.Keys,
            StringComparer.Ordinal);
 
        foreach (var definition in definitions)
            availableKeys.Add(definition.Key);
 
        foreach (var definition in definitions)
        {
            if (!string.IsNullOrWhiteSpace(definition.NextCycleKey) &&
                !string.Equals(
                    definition.NextCycleKey,
                    definition.Key,
                    StringComparison.Ordinal) &&
                !availableKeys.Contains(definition.NextCycleKey))
            {
                throw DefinitionError(sourceEntries[definition], baseDirectory, new InvalidDataException(
                    $"GANI animation '{definition.Key}' references next cycle '{definition.NextCycleKey}', but no matching animation is available."));
            }
        }
 
        var materialized = new List<(Cycle Cycle, AnimationDefinition Definition)>();
 
        foreach (var definition in definitions)
        {
            var cycle = WithDefinitionContext(sourceEntries[definition], baseDirectory,
                () => AnimationDefinitionSerializer.MaterializeCycle(definition));
            materialized.Add((cycle, definition));
        }
 
        foreach (var (cycle, definition) in materialized)
            WithDefinitionContext(sourceEntries[definition], baseDirectory, () =>
            {
                AnimationDefinitionSerializer.ApplyNextCycle(cycle, definition);
                return cycle;
            });
    }
 
    private static void DetachLegacySnapshotScenes(List<SceneStateEntry>? scenes)
    {
        if (scenes is null)
            return;
 
        foreach (var entry in scenes)
        {
            if (entry?.LegacyScene is { } legacyScene)
                Scene._allScenes.Remove(legacyScene);
        }
    }
 
    private static void MergeScenes(
        List<SceneStateEntry>? scenes,
        bool overwriteExisting,
        string? baseDirectory)
    {
        if (scenes is null || scenes.Count == 0)
            return;
 
        var existingIndexById = new Dictionary<string, int>(StringComparer.Ordinal);
        for (int i = 0; i < Scene._allScenes.Count; i++)
        {
            var id = Scene._allScenes[i].ID;
            if (!string.IsNullOrWhiteSpace(id) && !existingIndexById.ContainsKey(id))
                existingIndexById.Add(id, i);
        }
 
        // Avoid duplicating the same incoming ID twice. A duplicate within one
        // snapshot is treated as an overwrite so the last incoming entry wins.
        var seenIncoming = new HashSet<string>(StringComparer.Ordinal);
 
        foreach (var entry in scenes)
        {
            if (entry is null)
                continue;
 
            Scene incoming;
            bool materializedFromDefinition = false;
 
            if (entry.LegacyScene is not null)
            {
                incoming = entry.LegacyScene;
            }
            else if (entry.AssetsFilePath is not null)
            {
                incoming = LoadPacked(entry, baseDirectory, AssetTypes.SceneDefinition, SceneDefinitionSerializer.LoadScene);
                materializedFromDefinition = true;
            }
            else if (!string.IsNullOrWhiteSpace(entry.GscnPath))
            {
                var gscnPath = ResolvePath(entry.GscnPath, baseDirectory);
                incoming = SceneDefinitionSerializer.LoadScene(gscnPath);
                materializedFromDefinition = true;
            }
            else if (entry.Definition is not null)
            {
                incoming = SceneDefinitionSerializer.ToScene(entry.Definition);
                materializedFromDefinition = true;
            }
            else
            {
                throw new InvalidDataException(
                    "Scene state entry does not contain a GSCN path or inline definition.");
            }
 
            // Scene materialization registers runtime scenes immediately. Detach newly
            // materialized definitions so this method remains the single merge owner.
            if (materializedFromDefinition)
                Scene._allScenes.Remove(incoming);
 
            if (string.IsNullOrWhiteSpace(incoming.ID))
                incoming.ID = Guid.NewGuid().ToString();
 
            bool duplicateIncoming = !seenIncoming.Add(incoming.ID);
 
            if (existingIndexById.TryGetValue(incoming.ID, out int existingIndex))
            {
                if (!overwriteExisting && !duplicateIncoming)
                {
                    if (materializedFromDefinition)
                        incoming.Dispose();
 
                    continue;
                }
 
                Scene._allScenes[existingIndex] = incoming;
            }
            else
            {
                existingIndexById[incoming.ID] = Scene._allScenes.Count;
                Scene._allScenes.Add(incoming);
            }
        }
    }
 
    private static void RebindSpriteSceneLayer(Sprite sprite)
    {
        var layerId = sprite.SerializedSceneLayerIdForBinding;
        if (string.IsNullOrWhiteSpace(layerId))
        {
            if (!ReferenceEquals(sprite.SceneLayer, SceneLayer.Empty))
                return;
 
            throw new InvalidDataException(
                $"Sprite '{sprite.Nickname ?? sprite.Id.ToString()}' does not contain a SceneLayer identity.");
        }
 
        SceneLayer? targetLayer = null;
        var sceneId = sprite.SerializedSceneIdForBinding;
 
        if (!string.IsNullOrWhiteSpace(sceneId))
        {
            var scene = Scene._allScenes.FirstOrDefault(
                candidate => string.Equals(candidate.ID, sceneId, StringComparison.Ordinal));
 
            targetLayer = scene?.GetSceneLayerByID(layerId);
        }
        else
        {
            // Older data may have a layer ID but no scene ID. Layer IDs are normally
            // GUIDs; accept a unique match and reject ambiguity.
            var matches = Scene._allScenes
                .SelectMany(scene => scene.SceneLayers)
                .Where(layer => string.Equals(layer.ID, layerId, StringComparison.Ordinal))
                .Take(2)
                .ToList();
 
            if (matches.Count == 1)
                targetLayer = matches[0];
            else if (matches.Count > 1)
                throw new InvalidDataException(
                    $"Sprite '{sprite.Nickname ?? sprite.Id.ToString()}' references ambiguous SceneLayer ID '{layerId}'.");
        }
 
        if (targetLayer is null)
        {
            throw new InvalidDataException(
                $"Sprite '{sprite.Nickname ?? sprite.Id.ToString()}' could not resolve SceneLayer '{layerId}'" +
                (string.IsNullOrWhiteSpace(sceneId) ? "." : $" in Scene '{sceneId}'."));
        }
 
        sprite.RebindSceneLayerAfterDeserialization(targetLayer);
    }
 
    private static void DetachSnapshotSprites(List<Sprite>? sprites)
    {
        if (sprites is null)
            return;
 
        foreach (var sprite in sprites)
        {
            if (sprite is not null)
                SpriteManager.Instance._spriteList.Remove(sprite);
        }
    }
 
    private static void MergeSprites(List<Sprite>? sprites, bool overwriteExisting)
    {
        if (sprites is null || sprites.Count == 0)
            return;
 
        var existingIndexById = new Dictionary<string, int>(StringComparer.Ordinal);
        for (int i = 0; i < SpriteManager.Instance._spriteList.Count; i++)
        {
            var id = SpriteManager.Instance._spriteList[i].Nickname;
            if (!string.IsNullOrWhiteSpace(id) && !existingIndexById.ContainsKey(id))
                existingIndexById.Add(id, i);
        }
 
        var seenIncoming = new HashSet<string>(StringComparer.Ordinal);
 
        foreach (var incoming in sprites)
        {
            if (incoming is null)
                continue;
 
            RebindSpriteSceneLayer(incoming);
 
            if (string.IsNullOrWhiteSpace(incoming.Nickname))
                incoming.Nickname = Guid.NewGuid().ToString();
 
            bool duplicateIncoming = !seenIncoming.Add(incoming.Nickname);
 
            if (existingIndexById.TryGetValue(incoming.Nickname, out int existingIndex))
            {
                if (!overwriteExisting && !duplicateIncoming)
                {
                    incoming.DisposeImmediate();
                    continue;
                }
 
                SpriteManager.Instance._spriteList[existingIndex].DisposeImmediate();
                SpriteManager.Instance._spriteList[existingIndex] = incoming;
            }
            else
            {
                existingIndexById[incoming.Nickname] = SpriteManager.Instance._spriteList.Count;
                SpriteManager.Instance.AddSprite(incoming);
            }
        }
    }
 
    #endregion deserialization helpers
}