feat: More convenient API

Author: ResurrectedTrader

README.md

@@ -88,6 +88,9 @@ save.Stats.SetStat(StatId.StashGold, 2500000);
 save.Character.Level = 99;
 
 // Write back to file
+File.WriteAllBytes("MyCharacter.d2s", save.ToBytes());
+
+// Or write to a pre-allocated buffer for zero-copy scenarios
 byte[] buffer = new byte[save.EstimateSize()];
 int bytesWritten = save.Write(buffer);
 File.WriteAllBytes("MyCharacter.d2s", buffer.AsSpan(0, bytesWritten).ToArray());
@@ -258,9 +261,7 @@ The library supports converting saves between formats by specifying a target ver
 var save = D2Save.Read(File.ReadAllBytes("old_character.d2s"));
 
 // Write as latest D2R format (version 105)
-byte[] buffer = new byte[save.EstimateSize()];
-int written = save.Write(buffer, targetVersion: 105);
-File.WriteAllBytes("new_character.d2s", buffer.AsSpan(0, written).ToArray());
+File.WriteAllBytes("new_character.d2s", save.ToBytes(targetVersion: 105));
 ```
 
 ### Conversion Details

src/D2SSharp/Model/D2Save.cs

@@ -125,6 +125,19 @@ public static D2Save Read(ReadOnlySpan<byte> data, IExternalData externalData)
         return save;
     }
 
+    /// <summary>
+    /// Writes a save file to a new byte array.
+    /// </summary>
+    /// <param name="externalData">External game data for writing stats/items. Uses built-in data if null.</param>
+    /// <param name="targetVersion">Optional target version for format conversion.</param>
+    /// <returns>The serialized save file bytes.</returns>
+    public byte[] ToBytes(IExternalData? externalData = null, uint? targetVersion = null)
+    {
+        byte[] buffer = new byte[EstimateSize()];
+        int bytesWritten = Write(buffer, externalData ?? TxtFileExternalData.Default, targetVersion);
+        return buffer.AsSpan(0, bytesWritten).ToArray();
+    }
+
     /// <summary>
     /// Writes a save file to a byte span using the default external data.
     /// </summary>
@@ -215,29 +228,26 @@ public int EstimateSize()
         // Skills: 2 + numSkills
         size += 2 + Character.NumSkills;
 
-        // Items: very variable, estimate based on item count including socketed items
-        // Average item is ~50-200 bytes
-        size += 4 + CountItemsRecursive(Items) * 200;
+        // Items
+        size += Items.EstimateSize();
 
         // Corpse: header + corpses with items
         size += 4;
         foreach (var corpse in Corpses)
         {
-            size += 12 + CountItemsRecursive(corpse.Items) * 200;
+            size += 12 + corpse.Items.EstimateSize();
         }
 
         // Expansion sections
         if (IsExpansion(Version))
         {
-            // Merc items
-            size += 4 + CountItemsRecursive(MercItems?.Items) * 200;
+            // Merc items: magic(2) + items section
+            size += 2 + (MercItems?.Items ?? new ItemsSection()).EstimateSize();
 
             // Iron golem
             size += 3;
             if (IronGolem?.GolemItem != null)
-            {
-                size += CountItemsRecursive([IronGolem.GolemItem]) * 200;
-            }
+                size += 200; // Single item estimate
 
             // Demon section
             if (Character.Preview.GameVersion == GameVersion.ReignOfTheWarlock && Demon != null)
@@ -258,23 +268,6 @@ public int EstimateSize()
         return (int)(size * 1.2);
     }
 
-    /// <summary>
-    /// Counts items recursively, including socketed items.
-    /// </summary>
-    private static int CountItemsRecursive(IEnumerable<Item?>? items)
-    {
-        if (items == null) return 0;
-
-        int count = 0;
-        foreach (var item in items)
-        {
-            if (item == null) continue;
-            count++; // Count this item
-            count += CountItemsRecursive(item.Sockets); // Count socketed items
-        }
-        return count;
-    }
-
     /// <summary>
     /// Verifies the checksum of save file data.
     /// </summary>

src/D2SSharp/Model/D2StashSave.cs

@@ -45,6 +45,34 @@ public static D2StashSave Read(ReadOnlySpan<byte> data, IExternalData externalDa
         return Read(ref reader, externalData);
     }
 
+    /// <summary>
+    /// Calculates an estimated buffer size for writing all tabs.
+    /// Returns a conservative estimate that should be large enough.
+    /// </summary>
+    public int EstimateSize()
+    {
+        int size = 0;
+        foreach (var tab in this)
+        {
+            size += tab.EstimateSize();
+        }
+        return size;
+    }
+
+    /// <summary>
+    /// Writes all stash tabs to a new byte array.
+    /// </summary>
+    /// <param name="externalData">External game data for writing items. Uses built-in data if null.</param>
+    /// <param name="targetVersion">Optional target version for format conversion.</param>
+    /// <returns>The serialized stash save bytes.</returns>
+    public byte[] ToBytes(IExternalData? externalData = null, uint? targetVersion = null)
+    {
+        byte[] buffer = new byte[EstimateSize()];
+        var writer = new BitWriter(buffer);
+        Write(ref writer, externalData ?? TxtFileExternalData.Default, targetVersion);
+        return buffer.AsSpan(0, writer.BytesWritten).ToArray();
+    }
+
     /// <summary>
     /// Writes all stash tabs to a BitWriter using the default external data.
     /// </summary>

src/D2SSharp/Model/D2StashTab.cs

@@ -88,6 +88,45 @@ public static D2StashTab Read(ref BitReader reader, IExternalData externalData)
         return tab;
     }
 
+    /// <summary>
+    /// Calculates an estimated buffer size for writing this tab.
+    /// Returns a conservative estimate that should be large enough.
+    /// </summary>
+    public int EstimateSize()
+    {
+        // Header is always 64 bytes
+        int size = (int)HeaderSize;
+
+        if (TabType == StashTabType.Chronicle && Chronicle != null)
+        {
+            // Magic(4) + Version(2) + 3 counts(6) + Reserved(8) + entries(10 each) + trailing
+            size += 4 + 2 + 6 + 8;
+            size += (Chronicle.SetEntries.Count + Chronicle.UniqueEntries.Count + Chronicle.RunewordEntries.Count) * 10;
+            size += Chronicle.TrailingData.Length;
+        }
+        else
+        {
+            size += Items.EstimateSize();
+        }
+
+        // Add 20% buffer for safety
+        return (int)(size * 1.2);
+    }
+
+    /// <summary>
+    /// Writes this stash tab to a new byte array.
+    /// </summary>
+    /// <param name="externalData">External game data for writing items. Uses built-in data if null.</param>
+    /// <param name="targetVersion">Optional target version for format conversion.</param>
+    /// <returns>The serialized stash tab bytes.</returns>
+    public byte[] ToBytes(IExternalData? externalData = null, uint? targetVersion = null)
+    {
+        byte[] buffer = new byte[EstimateSize()];
+        var writer = new BitWriter(buffer);
+        Write(ref writer, externalData ?? TxtFileExternalData.Default, targetVersion);
+        return buffer.AsSpan(0, writer.BytesWritten).ToArray();
+    }
+
     /// <summary>
     /// Writes a stash tab to a BitWriter.
     /// </summary>

src/D2SSharp/Model/ItemsSection.cs

@@ -38,6 +38,27 @@ public static ItemsSection Read(ref BitReader reader, IExternalData externalData
         return section;
     }
 
+    /// <summary>
+    /// Calculates an estimated buffer size for this items section.
+    /// Uses 200 bytes per item (including socketed items) as a conservative estimate.
+    /// </summary>
+    public int EstimateSize()
+    {
+        return 4 + CountRecursive(this) * 200;
+
+        static int CountRecursive(IEnumerable<Item?> items)
+        {
+            int count = 0;
+            foreach (var item in items)
+            {
+                if (item == null) continue;
+                count++;
+                count += CountRecursive(item.Sockets);
+            }
+            return count;
+        }
+    }
+
     /// <summary>
     /// Writes an items section to a BitWriter.
     /// </summary>