SoulsFormatsNEXT

A community-driven continuation of TKGP's .NET library for reading and writing various FromSoftware file formats, targeting .NET Framework 4.8 and .NET Standard 2.1. This library primarily supports:

• Dark Souls
• Demon's Souls
• Dark Souls II
• Dark Souls III
• Bloodborne
• Sekiro
• Elden Ring
• Armored Core VI

Other From games may be supported to varying degrees.
A brief description of each supported format can be found in FORMATS.md, with further documentation for some formats.

Usage

Objects for most formats can be created with the static method Read, which accepts either a byte array or a file path. Using a path is preferable as it will be read with a stream, reducing memory consumption.

BND3 bnd = BND3.Read(@"C:\your\path\here.chrbnd");

// or

byte[] bytes = File.ReadAllBytes(@"C:\your\path\here.chrbnd");
BND3 bnd = BND3.Read(bytes);

The Write method can be used to create a new file from an object. If given a path it will be written to that location with a stream, otherwise a byte array will be returned.

bnd.Write(@"C:\your\path\here.chrbnd");

// or

byte[] bytes = bnd.Write();
File.WriteAllBytes(@"C:\your\path\here.chrbnd", bytes);

DCX (compressed files) will be decompressed automatically and the compression type will be remembered and reapplied when writing the file.

BND3 bnd = BND3.Read(@"C:\your\path\here.chrbnd.dcx");
bnd.Write(@"C:\your\path\here.chrbnd.dcx");

The compression type can be changed by either setting the Compression field of the object, or specifying one when calling Write.

BND3 bnd = BND3.Read(@"C:\your\path\here.chrbnd.dcx");
bnd.Write(@"C:\your\path\here.chrbnd", DCX.Type.None);

// or

BND3 bnd = BND3.Read(@"C:\your\path\here.chrbnd.dcx");
bnd.Compression = DCX.Type.None;
bnd.Write(@"C:\your\path\here.chrbnd");

Finally, DCX files can be generically read and written with static methods if necessary. DCX holds no important metadata so they read/write directly to/from byte arrays instead of creating an object.

byte[] bndBytes = DCX.Decompress(@"C:\your\path\here.chrbnd.dcx");
BND3 bnd = BND3.Read(bndBytes);

// or

byte[] dcxBytes = File.ReadAllBytes(@"C:\your\path\here.chrbnd.dcx");
byte[] bndBytes = DCX.Decompress(dcxBytes);
BND3 bnd = BND3.Read(bndBytes);

Writing a new DCX requires a DCX.Type parameter indicating which game it is for. DCX.Decompress has an optional out parameter indicating the detected type which should usually be used instead of specifying your own.

byte[] bndBytes = DCX.Decompress(@"C:\your\path\here.chrbnd.dcx", out DCX.Type type);
DCX.Compress(bndBytes, type, @"C:\your\path\here.chrbnd.dcx");

// or

byte[] bndBytes = DCX.Decompress(@"C:\your\path\here.chrbnd.dcx", out DCX.Type type);
byte[] dcxBytes = DCX.Compress(bndBytes, type);
File.WriteAllBytes(@"C:\your\path\here.chrbnd.dcx", dcxBytes);

Community Maintenance

SoulsFormats is a project originally developed by TKGP. This repository is a community-maintained continuation, which compiles commonly needed changes and improvements to the formats, based on insights that have been gained since its original creation.

Due to the nature of community contributions, there are no claims made to perfect accuracy of all output. If working with games older than Sekiro, you may prefer to use the original library.

Credits

• TKGP - Original implementation of SoulsFormats
• katalash - FsParam
• Nordgaren - Armored Core VI additions, Oodle DLL location
• Meowmaritus - FXR, TAE
• NamelessHoodie - FXR
• CCCode - FXR
• ClayAmore - ZSTD Decompression
• NatsuDragneelTheFireDragon - Maintainer, legacy Armored Core formats
• The12thAvenger - Maintainer
• Shadowth117 - Maintainer
• ividyon - Maintainer

TKGP's Special Thanks

To everyone below, for either creating tools that I learned from, or helping decipher these formats one way or another. Please yell at me on Discord if I missed you.

• albeartron
• Atvaark
• B3LYP
• horkrux
• HotPocketRemix
• katalash
• Lance
• Meowmaritus
• Nyxojaele
• Pav
• SeanP
• thefifthmatt
• Wulf2k
• Yoshimitsu