D2SSharp 0.0.4

D2SSharp

A C# library for reading and writing Diablo 2 save files (.d2s character saves and .d2i shared stash files). Supports both the original Diablo 2: Lord of Destruction format (1.10+) and Diablo 2 Resurrected.

Features

• Full round-tripping support - produces identical outputs, as verified by tests.
• Supports providing external .txt files for loading characters that have been saved by mods.
• Full read/write support for character save files (.d2s)
• Shared stash file support (.d2i)
• Supports D2 LOD (version 96) and D2R (version 97+) formats
• Complete item parsing including stats, sockets, runewords, and set bonuses
• Zero external dependencies beyond .NET

Acknowledgments

This project was vibe coded with Claude.

Installation

dotnet add package D2SSharp

Or clone and build from source:

git clone https://github.com/ResurrectedTrader/D2SSharp.git
cd D2SSharp
dotnet build

Usage

Reading a Character Save

using D2SSharp.Data;
using D2SSharp.Model;

// Load game data (uses embedded txt files)
var gameData = new TxtFileExternalData();

// Read save file
byte[] saveBytes = File.ReadAllBytes("MyCharacter.d2s");
D2Save save = D2Save.Read(saveBytes, gameData);

// Access character info
Console.WriteLine($"Character: {save.Character.Preview.Name}");
Console.WriteLine($"Level: {save.Stats.Level}");
Console.WriteLine($"Class: {save.Character.Class}");

// Iterate items
foreach (var item in save.Items)
{
    Console.WriteLine($"Item: {item.ItemCodeString} (Quality: {item.Quality})");
}

Modifying and Saving

// Modify stats
save.Stats.Strength = 200;
save.Stats.GoldInStash = 2500000;

// Write back to file
byte[] buffer = new byte[save.EstimateSize()];
int bytesWritten = save.Write(buffer, gameData);
File.WriteAllBytes("MyCharacter.d2s", buffer.AsSpan(0, bytesWritten).ToArray());

Reading Shared Stash

byte[] stashBytes = File.ReadAllBytes("SharedStashSoftCoreV2.d2i");
var reader = new BitReader(stashBytes);
D2StashSave stash = D2StashSave.Read(ref reader, gameData, saveVersion: 97);

foreach (var tab in stash)
{
    Console.WriteLine($"Tab: {tab.Name}, Items: {tab.Items.Count}");
}

External Data

The library requires game data tables to correctly parse items:

• TxtFileExternalData: Loads from D2 .txt data files. Uses embedded data by default for versions 96, 97, and 99.

// Use embedded data (default) - supports all standard versions
var gameData = new TxtFileExternalData();

// Or load from a directory containing version subdirectories
// Directory structure should be:
//   MyTxtFiles/
//     96/
//       armor.txt, itemstatcost.txt, itemtypes.txt, misc.txt, weapons.txt
//     99/
//       armor.txt, itemstatcost.txt, itemtypes.txt, misc.txt, weapons.txt
var gameData = new TxtFileExternalData(@"C:\path\to\MyTxtFiles");

The library selects version data based on exact match with the save file's version. If the required version is not available, an exception is thrown listing the available versions.

Save Format Versions

Version Conversion

The library supports converting saves between D2 LOD (1.14) and D2R formats by specifying a target version when writing:

// Use embedded data (contains 96, 97 and 99 versions)
var gameData = new TxtFileExternalData();

// Read a 1.14 save (version 96)
var save = D2Save.Read(File.ReadAllBytes("old_character.d2s"), gameData);

// Write as D2R format (version 99)
byte[] buffer = new byte[save.EstimateSize()];
int written = save.Write(buffer, gameData, targetVersion: 99);
File.WriteAllBytes("new_character.d2s", buffer.AsSpan(0, written).ToArray());

Conversion Details

The library handles the following format differences automatically:

1.14 → D2R

D2R → 1.14

Binary Differences

When comparing converted saves to saves created by the game:

These differences do not affect gameplay - the converted saves are fully functional.

Mod Compatibility

The library provides limited support for modded save files:

Supported

• Custom item data: Use TxtFileExternalData with a directory containing version subdirectories with mod-specific .txt files:

  // Directory structure: ModData/99/armor.txt, ModData/99/itemstatcost.txt, etc.
  var modData = new TxtFileExternalData(@"C:\path\to\ModData");
  var save = D2Save.Read(File.ReadAllBytes("modded_character.d2s"), modData);
  

• Trailing data: Any bytes after the standard sections are preserved in D2Save.TrailingData and written back during round-trip

Not Supported

• Missing sections: Save files must contain all required sections. Files with missing or malformed sections (e.g., Expansion flag set but no MercItems/IronGolem sections) will fail to parse
• Modified section formats: The library expects standard D2/D2R section layouts

Building

dotnet build D2SSharp.sln
dotnet test

License

MIT