Merge pull request #4 from Sichii/master

Colorized SPF, comments, ControlFiles

Author: baughj

DALib/Abstractions/ISavable.cs

@@ -2,9 +2,20 @@
 
 namespace DALib.Abstractions;
 
+/// <summary>
+///     Defines the pattern for an object that can be saved to a file or stream
+/// </summary>
 public interface ISavable
 {
+    /// <summary>
+    ///     Saves the object to the specified path
+    /// </summary>
+    /// <param name="path">The path to save the object to</param>
     void Save(string path);
 
+    /// <summary>
+    ///     Writes the object to the specified stream
+    /// </summary>
+    /// <param name="stream">The stream to write the object to</param>
     void Save(Stream stream);
 }

DALib/Cryptography/CRC16.cs

@@ -1,9 +1,12 @@
 namespace DALib.Cryptography;
 
+/// <summary>
+///     Provides methods for calculating 16 bit cyclic redundancy checks
+/// </summary>
 public static class CRC16
 {
     private static readonly ushort[] CRC16_TABLE =
-    {
+    [
         0x0000,
         0x1021,
         0x2042,
@@ -260,10 +263,20 @@ public static class CRC16
         0x3EB2,
         0x0ED1,
         0x1EF0
-    };
+    ];
 
+    /// <summary>
+    ///     Calculates the 16bit checksum of the specified buffer
+    /// </summary>
+    /// <param name="buffer">The buffer to calculate the checksum of</param>
     public static ushort Calculate(byte[] buffer) => Calculate(buffer, 0, buffer.Length);
 
+    /// <summary>
+    ///     Calculates the 16bit checksum of the specified buffer
+    /// </summary>
+    /// <param name="buffer">The buffer to calculate the checksum of</param>
+    /// <param name="offset">The offset within the buffer to start at</param>
+    /// <param name="count">The number of bytes within the buffer to calculate for</param>
     public static ushort Calculate(byte[] buffer, int offset, int count)
     {
         ushort result = 0;

DALib/Cryptography/CRC32.cs

@@ -1,5 +1,8 @@
 namespace DALib.Cryptography;
 
+/// <summary>
+///     Provides methods for calculating 32 bit cyclic redundancy checks
+/// </summary>
 public static class CRC32
 {
     private static readonly uint[] CRC32_TABLE =
@@ -262,8 +265,18 @@ public static class CRC32
         0x2D02EF8D
     };
 
+    /// <summary>
+    ///     Calculates the 32bit checksum of the specified buffer
+    /// </summary>
+    /// <param name="buffer">The buffer to calculate the checksum of</param>
     public static uint Calculate(byte[] buffer) => Calculate(buffer, 0, buffer.Length);
 
+    /// <summary>
+    ///     Calculates the 32bit checksum of the specified buffer
+    /// </summary>
+    /// <param name="buffer">The buffer to calculate the checksum of</param>
+    /// <param name="offset">The offset within the buffer to start at</param>
+    /// <param name="count">The number of bytes within the buffer to calculate for</param>
     public static uint Calculate(byte[] buffer, int offset, int count)
     {
         var result = 0xFFFFFFFF;

DALib/Cryptography/PacketCryptoProvider.cs

@@ -4,6 +4,9 @@
 
 namespace DALib.Cryptography;
 
+/// <summary>
+///     Provides cryptographic services for packets.
+/// </summary>
 public class PacketCryptoProvider
 {
     private const int MAXIMUM_SEED = 9;
@@ -20,10 +23,16 @@ public class PacketCryptoProvider
     private byte[] _keystream1;
     private byte[] _keystream2Table;
     private uint _randState;
-    private byte[] _salt;
+    private byte[] _salt = null!;
 
     private byte _seed;
 
+    /// <summary>
+    ///     Gets or sets the Keystream property, which represents the keystream as a string.
+    /// </summary>
+    /// <value>The keystream as a string.</value>
+    /// <exception cref="ArgumentNullException">Thrown if the value is null.</exception>
+    /// <exception cref="Exception">Thrown if the value length is not equal to KEYSTREAM_LENGTH.</exception>
     public string Keystream
     {
         get => Encoding.ASCII.GetString(_keystream1);
@@ -41,6 +50,15 @@ public string Keystream
         }
     }
 
+    /// <summary>
+    ///     Gets or sets the seed value.
+    /// </summary>
+    /// <value>
+    ///     The value of the seed.
+    /// </value>
+    /// <remarks>
+    ///     Setting a new seed value will regenerate the salt using the new seed value.
+    /// </remarks>
     public byte Seed
     {
         get => _seed;
@@ -55,13 +73,24 @@ public byte Seed
         }
     }
 
+    /// <summary>
+    ///     Initializes a new instance of the <see cref="PacketCryptoProvider" /> class.
+    ///     Uses the default seed and keystream values.
+    /// </summary>
     public PacketCryptoProvider()
         : this(DEFAULT_SEED, DEFAULT_KEYSTREAM)
     {
         _keystream1[3] = 0xE5; // The default keystream is supposed to be UrkcnItnI,
         _keystream1[7] = 0xA3; // however Kru somehow managed to fuck that up. :-)
     }
 
+    /// <summary>
+    ///     Represents a packet crypto provider that encrypts and decrypts packets using a seed and a keystream.
+    /// </summary>
+    /// <remarks>
+    ///     The PacketCryptoProvider uses a seed value and a keystream to generate a salt and performs packet encryption and
+    ///     decryption operations.
+    /// </remarks>
     public PacketCryptoProvider(byte seed, string keystream)
     {
         if (seed > MAXIMUM_SEED)
@@ -85,6 +114,16 @@ public PacketCryptoProvider(byte seed, string keystream)
         _buffer = new byte[BUFFER_LENGTH];
     }
 
+    /// <summary>
+    ///     Decrypts client data using the specified parameters.
+    /// </summary>
+    /// <param name="data">The byte array containing the encrypted client data.</param>
+    /// <param name="offset">The starting index within the byte array.</param>
+    /// <param name="count">The number of bytes to be decrypted.</param>
+    /// <param name="useKeystream2">Specifies whether to use keystream 2 for decryption.</param>
+    /// <returns>
+    ///     The decrypted client data as a byte array.
+    /// </returns>
     public byte[] DecryptClientData(
         byte[] data,
         int offset,
@@ -142,6 +181,14 @@ public byte[] DecryptClientData(
         return result;
     }
 
+    /// <summary>
+    ///     Decrypts server data.
+    /// </summary>
+    /// <param name="data">The data to decrypt.</param>
+    /// <param name="offset">The starting offset in the data.</param>
+    /// <param name="count">The number of bytes to decrypt.</param>
+    /// <param name="useKeystream2">Flag to indicate if keystream2 should be used for transformation.</param>
+    /// <returns>The decrypted server data as a byte array.</returns>
     public byte[] DecryptServerData(
         byte[] data,
         int offset,
@@ -190,6 +237,15 @@ public byte[] DecryptServerData(
         return result;
     }
 
+    /// <summary>
+    ///     Encrypts the provided client data using the specified parameters.
+    /// </summary>
+    /// <param name="data">The data to encrypt.</param>
+    /// <param name="offset">The starting index in the data array from which to begin encryption.</param>
+    /// <param name="count">The number of bytes to encrypt.</param>
+    /// <param name="sequence">The sequence value to use during encryption.</param>
+    /// <param name="useKeystream2">Determines whether to use Keystream2 during encryption.</param>
+    /// <returns>The encrypted client data.</returns>
     public byte[] EncryptClientData(
         byte[] data,
         int offset,
@@ -260,6 +316,15 @@ public byte[] EncryptClientData(
         return result;
     }
 
+    /// <summary>
+    ///     Encrypts server data using the specified parameters.
+    /// </summary>
+    /// <param name="data">The data to be encrypted.</param>
+    /// <param name="offset">The starting offset within the data array.</param>
+    /// <param name="count">The number of bytes to be encrypted.</param>
+    /// <param name="sequence">The sequence number used for encryption.</param>
+    /// <param name="useKeystream2">Determines whether to use the second keystream for encryption.</param>
+    /// <returns>The encrypted server data as a byte array.</returns>
     public byte[] EncryptServerData(
         byte[] data,
         int offset,
@@ -325,6 +390,10 @@ private void GenerateKeystream2(ushort a, byte b)
             _keystream2[i] = _keystream2Table[(i * (KEYSTREAM_LENGTH * i + b * b) + a) % KEYSTREAM2_TABLE_LENGTH];
     }
 
+    /// <summary>
+    ///     Generates a keystream table based on the given name.
+    /// </summary>
+    /// <param name="name">The name to generate the keystream table from.</param>
     public void GenerateKeystream2Table(string name)
     {
         var table = GetMd5String(GetMd5String(name));
@@ -403,7 +472,9 @@ private string GetMd5String(string value)
         var valueBytes = Encoding.ASCII.GetBytes(value);
         var hashBytes = _md5.ComputeHash(valueBytes);
 
-        return BitConverter.ToString(hashBytes).Replace("-", string.Empty).ToLower();
+        return BitConverter.ToString(hashBytes)
+                           .Replace("-", string.Empty)
+                           .ToLower();
     }
 
     private uint NextRandState(ref uint state)

DALib/DALib.csproj

@@ -1,5 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
+        <!--suppress MsbuildTargetFrameworkTagInspection -->
         <TargetFrameworks>net8.0</TargetFrameworks>
         <PackageId>DALib</PackageId>
         <PackageVersion>0.1.0</PackageVersion>
@@ -19,13 +20,14 @@
         <Description>A library for processing DOOMVAS v1 client data (such as Dark Ages MPF/EPF/SPF/DAT formats)</Description>
         <IsPackable>true</IsPackable>
         <Nullable>enable</Nullable>
-        <GenerateAssemblyInfo>false</GenerateAssemblyInfo>   
+        <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
     </PropertyGroup>
     <ItemGroup>
-        <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="" />
+        <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath=""/>
     </ItemGroup>
     <ItemGroup>
-        <None Include="hybrasyl-512x512.png" Pack="true" PackagePath="" />
+        <None Include="hybrasyl-512x512.png" Pack="true" PackagePath=""/>
     </ItemGroup>
     <ItemGroup>
         <PackageReference Include="KGySoft.Drawing.SkiaSharp" Version="7.2.0"/>
@@ -36,4 +38,4 @@
         <SupportedPlatform Include="macOS"/>
         <SupportedPlatform Include="Windows"/>
     </ItemGroup>
-</Project>
+</Project>

DALib/Data/DataArchive.cs

@@ -10,6 +10,9 @@
 
 namespace DALib.Data;
 
+/// <summary>
+///     Represents a DarkAges data archive that can be used for storing and manipulating data entries.
+/// </summary>
 public sealed class DataArchive() : KeyedCollection<string, DataArchiveEntry>(StringComparer.OrdinalIgnoreCase), ISavable, IDisposable
 {
     private bool IsDisposed;
@@ -55,6 +58,12 @@ private DataArchive(Stream stream, bool newFormat = false)
         }
     }
 
+    /// <summary>
+    ///     Returns a collection of data archive entries that match the given pattern and extension.
+    /// </summary>
+    /// <param name="pattern">The pattern to match the entry name against.</param>
+    /// <param name="extension">The extension to match the entry name against.</param>
+    /// <returns>A collection of <see cref="DataArchiveEntry" /> objects that match the pattern and extension.</returns>
     public IEnumerable<DataArchiveEntry> GetEntries(string pattern, string extension)
     {
         foreach (var entry in this)
@@ -69,6 +78,14 @@ public IEnumerable<DataArchiveEntry> GetEntries(string pattern, string extension
         }
     }
 
+    /// <summary>
+    ///     Retrieves all entries with a specified extension.
+    /// </summary>
+    /// <param name="extension">The extension to filter the entries with.</param>
+    /// <returns>
+    ///     An <see cref="IEnumerable{T}" /> of <see cref="DataArchiveEntry" /> containing all entries with the specified
+    ///     extension.
+    /// </returns>
     public IEnumerable<DataArchiveEntry> GetEntries(string extension)
     {
         foreach (var entry in this)
@@ -85,6 +102,13 @@ public IEnumerable<DataArchiveEntry> GetEntries(string extension)
     protected override string GetKeyForItem(DataArchiveEntry item) => item.EntryName;
     #endregion
 
+    /// <summary>
+    ///     Patches the DataArchive by appending a new entry that replaces an existing entry with the same name, or adds a new
+    ///     entry if no existing entry has the same name.
+    /// </summary>
+    /// <param name="entryName">The name of the entry to be patched.</param>
+    /// <param name="item">The item to be patched.</param>
+    /// <exception cref="InvalidOperationException">Thrown if the DataArchive is not in memory.</exception>
     public void Patch(string entryName, ISavable item)
     {
         ThrowIfDisposed();
@@ -116,6 +140,11 @@ public void Patch(string entryName, ISavable item)
     }
 
     #region SaveTo
+    /// <inheritdoc />
+    /// <exception cref="ObjectDisposedException">Thrown if the object is already disposed.</exception>
+    /// <exception cref="ArgumentNullException">Thrown if the path is null.</exception>
+    /// <exception cref="ArgumentException">Thrown if the path is empty or contains invalid characters.</exception>
+    /// <exception cref="PathTooLongException">Thrown if the path exceeds the maximum length allowed.</exception>
     public void Save(string path)
     {
         ThrowIfDisposed();
@@ -134,6 +163,9 @@ public void Save(string path)
         Save(stream);
     }
 
+    /// <inheritdoc />
+    /// <exception cref="ObjectDisposedException">Thrown if the object has been disposed.</exception>
+    /// <exception cref="InvalidOperationException">Thrown if an entry name is too long (must be 13 characters or less).</exception>
     public void Save(Stream stream)
     {
         ThrowIfDisposed();
@@ -182,6 +214,11 @@ public void Save(Stream stream)
         }
     }
 
+    /// <summary>
+    ///     Extracts the contents of the current archive to the specified directory.
+    /// </summary>
+    /// <param name="dir">The directory to which the contents will be extracted.</param>
+    /// <exception cref="InvalidOperationException">Thrown when the archive is already disposed.</exception>
     public void ExtractTo(string dir)
     {
         ThrowIfDisposed();
@@ -199,6 +236,11 @@ public void ExtractTo(string dir)
     #endregion
 
     #region LoadFrom
+    /// <summary>
+    ///     Loads a DataArchive from a directory that contains already extracted entries
+    /// </summary>
+    /// <param name="dir">The directory path.</param>
+    /// <returns>A new DataArchive object.</returns>
     public static DataArchive FromDirectory(string dir)
     {
         //create a new in-memory archive
@@ -241,6 +283,16 @@ public static DataArchive FromDirectory(string dir)
         return archive;
     }
 
+    /// <summary>
+    ///     Loads a DataArchive from the specified path
+    /// </summary>
+    /// <param name="path">The path to the file to create the DataArchive from.</param>
+    /// <param name="cacheArchive">
+    ///     Indicates whether to cache the archive in memory or read from file using pointers. Default
+    ///     is false.
+    /// </param>
+    /// <param name="newformat">Indicates whether to use the new format when reading the archive. Default is false.</param>
+    /// <returns>A new instance of the DataArchive class.</returns>
     public static DataArchive FromFile(string path, bool cacheArchive = false, bool newformat = false)
     {
         //if we don't want to cache the archive