Export native map patches and M2O resource manifests

README.md

@@ -39,6 +39,27 @@ The current feature set provides full editing of static meshes and collision dat
 
 The map editor currently supports visualizing district streaming zones, collision, AI navigation, City Crash objects, and switching season.
 
+## Exporting maps for M2O
+
+Use **File → Export for M2O…** after editing the map. The window lists the archives included,
+offers **Save and export** when edits are pending, and reports progress while generating native patches.
+Choose a new output folder; existing exports are preserved. A failed export leaves no partial output folder.
+Archives whose edits were undone are skipped. If every archive is unchanged, no export folder is created.
+
+Copy the exported folder's contents into your server resource, for example `client/maps/`, and include
+`client/maps/**` in `package.json` → `mafiahub.files`. Keep `map_patches.json` beside the exported `sds/`
+folder: its paths reference those patch files. M2O sends them through the existing packed resource download.
+Reconnect clients after changing the map resource.
+
+Only the listed edited archives are exported. Edit summer and winter separately to include both;
+their resource ordinals differ. Check object removals and collision edits together in-game.
+Use **Save** for working copies before export. **Build SDS** modifies the local game archives and clears
+the pending export list; it is not required for M2O export. Patches must target the same base archives as clients.
+
+The isolated `Illusion.exe --probe-m2o-export` check exercises native patch output, manifest paths,
+season and filename collisions, overwrite protection and failure cleanup. It writes its report and a window
+render to `%TEMP%/illusion_m2o_export.txt` and `%TEMP%/illusion_m2o_export.png`.
+
 ## Download
 
 Grab the latest archive from [Releases](https://github.com/hurfy/illusion-toolkit/releases), unpack

src/Illusion.Assets/Sds/M2oMapExporter.cs

@@ -0,0 +1,54 @@
+using System.Text.Json;
+
+namespace Illusion.Assets.Sds;
+
+/// <summary>Publishes native patches and their manifest together in a new M2O map folder.</summary>
+public static class M2oMapExporter
+{
+    /// <summary>The native target path relative to the game's pc directory.</summary>
+    public static string TargetOf(FileInfo archive)
+    {
+        string relative = Path.GetRelativePath(MafiaEnvironment.PcFolder, archive.FullName).Replace('\\', '/');
+        if (!relative.StartsWith("sds/", StringComparison.OrdinalIgnoreCase) || relative.Split('/').Any(part => part is ".." or ".") || !relative.EndsWith(".sds", StringComparison.OrdinalIgnoreCase))
+            throw new InvalidOperationException($"{archive.Name} is not an SDS archive inside the selected game's pc/sds folder.");
+        return "/" + relative.ToLowerInvariant();
+    }
+
+    /// <summary>Exports only the supplied edited archives; season variants must be edited separately.</summary>
+    public static IReadOnlyList<PatchExportResult> Export(IReadOnlyList<FileInfo> archives, string destination, IProgress<string>? progress = null)
+    {
+        ArgumentNullException.ThrowIfNull(archives);
+        ArgumentException.ThrowIfNullOrWhiteSpace(destination);
+        if (archives.Count == 0) throw new InvalidOperationException("No edited archives to export.");
+        string fullDestination = Path.GetFullPath(destination);
+        if (Directory.Exists(fullDestination) || File.Exists(fullDestination)) throw new IOException("That export folder already exists. Choose a new name to keep the previous export intact.");
+        string[] targets = archives.Select(TargetOf).ToArray();
+        if (targets.Distinct(StringComparer.OrdinalIgnoreCase).Count() != targets.Length) throw new InvalidOperationException("The export contains duplicate SDS targets.");
+        string stage = fullDestination + ".tmp-" + Guid.NewGuid().ToString("N");
+        Directory.CreateDirectory(stage);
+        try
+        {
+            var results = new List<PatchExportResult>();
+            var entries = new List<object>();
+            for (int i = 0; i < archives.Count; i++)
+            {
+                progress?.Report($"Exporting {i + 1} of {archives.Count}: {archives[i].Name}");
+                string patch = targets[i].TrimStart('/') + ".patch";
+                PatchExportResult? exported;
+                try { exported = PatchExporter.TryExport(archives[i], Path.Combine(stage, patch)); }
+                catch (Exception ex) { throw new InvalidOperationException($"Could not export {archives[i].Name}: {ex.Message}", ex); }
+                if (exported is not { } result) continue;
+                results.Add(result with { PatchPath = Path.Combine(fullDestination, patch) });
+                entries.Add(new { sds = targets[i], patch });
+            }
+            if (results.Count == 0) return results;
+            File.WriteAllText(Path.Combine(stage, "map_patches.json"), JsonSerializer.Serialize(new { patches = entries }, new JsonSerializerOptions { WriteIndented = true }));
+            Directory.Move(stage, fullDestination);
+            return results;
+        }
+        finally
+        {
+            if (Directory.Exists(stage)) Directory.Delete(stage, true);
+        }
+    }
+}

src/Illusion.Assets/Sds/PatchExporter.cs

@@ -0,0 +1,179 @@
+using Illusion.Formats;
+using Illusion.Formats.Archive;
+
+namespace Illusion.Assets.Sds;
+
+/// <summary>One archive's export: where the patch went, and what it carries.</summary>
+/// <param name="Archive">The game archive the patch applies to.</param>
+/// <param name="PatchPath">The file written.</param>
+/// <param name="Result">What the diff found.</param>
+public readonly record struct PatchExportResult(string Archive, string PatchPath, PatchDiffResult Result);
+
+/// <summary>Diffs saved working copies against read-only game archives and exports native patches.</summary>
+public static class PatchExporter
+{
+    /// <summary>The extension every exported patch carries, matching the game's own convention.</summary>
+    public const string PatchExtension = ".sds.patch";
+
+    /// <summary>
+    /// The other season's copy of a district, or null when there is none.
+    /// </summary>
+    public static FileInfo? SeasonVariantOf(FileInfo sds)
+    {
+        ArgumentNullException.ThrowIfNull(sds);
+
+        string stem = Path.GetFileNameWithoutExtension(sds.Name);
+        string twin = stem.EndsWith("_z", StringComparison.OrdinalIgnoreCase)
+            ? stem[..^2]
+            : stem + "_z";
+
+        var candidate = new FileInfo(Path.Combine(sds.DirectoryName ?? string.Empty, twin + ".sds"));
+        return candidate.Exists ? candidate : null;
+    }
+
+    /// <summary>The name a patch for <paramref name="sds"/> should be given.</summary>
+    public static string SuggestFileName(FileInfo sds)
+    {
+        ArgumentNullException.ThrowIfNull(sds);
+        return Path.GetFileNameWithoutExtension(sds.Name) + PatchExtension;
+    }
+
+    /// <summary>
+    /// Writes a patch for <paramref name="sds"/> to <paramref name="outputPath"/>, expressing every
+    /// edit made to it this session.
+    /// </summary>
+    /// <exception cref="FileNotFoundException">The archive was never extracted, so there is nothing to diff.</exception>
+    /// <exception cref="InvalidOperationException">Nothing changed, so there is no patch to write.</exception>
+    public static PatchExportResult Export(FileInfo sds, string outputPath)
+        => TryExport(sds, outputPath) ?? throw new InvalidOperationException($"{sds.Name} is unchanged; no patch is needed.");
+
+    /// <summary>Exports a changed archive, or returns null without writing a file when unchanged.</summary>
+    public static PatchExportResult? TryExport(FileInfo sds, string outputPath)
+        => TryExport(sds, outputPath, out _, out _);
+
+    private static PatchExportResult? TryExport(FileInfo sds, string outputPath, out SdsArchive original, out SdsArchive edited)
+    {
+        ArgumentNullException.ThrowIfNull(sds);
+        ArgumentException.ThrowIfNullOrWhiteSpace(outputPath);
+
+        if (string.Equals(sds.FullName, Path.GetFullPath(outputPath), StringComparison.OrdinalIgnoreCase))
+            throw new InvalidOperationException("The output patch cannot overwrite its base archive.");
+        string extracted = MafiaEnvironment.ExtractedDir(sds);
+        if (!File.Exists(Path.Combine(extracted, "SDSContent.xml")))
+        {
+            throw new FileNotFoundException(
+                $"Extracted content not found for {sds.Name} — nothing to diff.",
+                Path.Combine(extracted, "SDSContent.xml"));
+        }
+
+        edited = SdsArchive.Pack(extracted, GameProfile.MafiaII);
+        original = SdsArchive.Open(sds.FullName);
+
+        if (SdsPatchDiff.TryBetween(original, edited) is not { } diff) return null;
+        (SdsPatchFile patch, PatchDiffResult result) = diff;
+
+        string? directory = Path.GetDirectoryName(outputPath);
+        if (!string.IsNullOrEmpty(directory))
+        {
+            Directory.CreateDirectory(directory);
+        }
+
+        using (FileStream output = File.Create(outputPath))
+        {
+            patch.Save(output);
+        }
+
+        return new PatchExportResult(sds.FullName, outputPath, result);
+    }
+
+    /// <summary>
+    /// Exports the patch for <paramref name="sds"/> and, when the district ships a season twin, a
+    /// second patch that applies the same removals to it.
+    /// </summary>
+    /// <remarks>
+    /// Only matching frame removals carry across; resource ordinals and other edits are season-specific.
+    /// </remarks>
+    public static IReadOnlyList<PatchExportResult> ExportWithSeasonVariant(FileInfo sds, string outputPath)
+    {
+        ArgumentNullException.ThrowIfNull(sds);
+        ArgumentException.ThrowIfNullOrWhiteSpace(outputPath);
+
+        FileInfo? twin = SeasonVariantOf(sds);
+        string? twinPath = twin is null ? null : Path.Combine(Path.GetDirectoryName(outputPath) ?? string.Empty, SuggestFileName(twin));
+        if (twinPath is not null && string.Equals(Path.GetFullPath(outputPath), Path.GetFullPath(twinPath), StringComparison.OrdinalIgnoreCase))
+            throw new IOException("The chosen filename conflicts with the seasonal patch filename.");
+        PatchExportResult result = TryExport(sds, outputPath, out SdsArchive original, out SdsArchive edited)
+            ?? throw new InvalidOperationException($"{sds.Name} is unchanged; no patch is needed.");
+        var exported = new List<PatchExportResult> { result };
+        if (twin is null)
+        {
+            return exported;
+        }
+
+        var removedNames = ScenePatchAuthor
+            .FrameNamesOf(FrameResourceOf(original))
+            .Except(ScenePatchAuthor.FrameNamesOf(FrameResourceOf(edited)), StringComparer.Ordinal)
+            .ToList();
+
+        if (removedNames.Count == 0)
+        {
+            return exported;
+        }
+
+        var author = new ScenePatchAuthor(SdsArchive.Open(twin.FullName));
+        RemovalResult removal = author.RemoveFrames(removedNames);
+        if (removal.DeletedFrames == 0 && removal.DeletedCollisionInstances == 0) return exported;
+
+        SdsPatchFile twinPatch = author.Build();
+        using (FileStream output = File.Create(twinPath!))
+        {
+            twinPatch.Save(output);
+        }
+
+        exported.Add(new PatchExportResult(
+            twin.FullName,
+            twinPath!,
+            new PatchDiffResult(Changed: twinPatch.Entries.Count, Removed: 0, Added: 0)));
+
+        return exported;
+    }
+
+    private static byte[]? FrameResourceOf(SdsArchive archive)
+    {
+        for (int i = 0; i < archive.Entries.Count; i++)
+        {
+            int typeId = archive.Entries[i].TypeId;
+            if (typeId >= 0 && typeId < archive.ResourceTypes.Count &&
+                string.Equals(archive.ResourceTypes[typeId].Name, "FrameResource", StringComparison.Ordinal))
+            {
+                return archive.Entries[i].Data;
+            }
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// Exports one patch per archive into <paramref name="targetFolder"/>, naming each after its
+    /// archive. Archives that turn out to be unchanged are skipped rather than failing the export.
+    /// </summary>
+    public static IReadOnlyList<PatchExportResult> ExportAll(IEnumerable<FileInfo> archives, string targetFolder)
+    {
+        ArgumentNullException.ThrowIfNull(archives);
+        ArgumentException.ThrowIfNullOrWhiteSpace(targetFolder);
+
+        FileInfo[] sources = archives.ToArray();
+        if (sources.Select(SuggestFileName).Distinct(StringComparer.OrdinalIgnoreCase).Count() != sources.Length)
+            throw new IOException("Several archives would export to the same filename. Export them separately.");
+        var exported = new List<PatchExportResult>();
+        foreach (FileInfo sds in sources)
+        {
+            if (TryExport(sds, Path.Combine(targetFolder, SuggestFileName(sds))) is { } result)
+            {
+                exported.Add(result);
+            }
+        }
+
+        return exported;
+    }
+}