matigramirez / Parsec

Serialization library for Shaiya file formats

Parsec

Parsec is a simple .NET parsing library for Shaiya file formats which provides easy to use APIs for serialization and deserialization of the game's file formats, including JSON and CSV support.

Parsec works on any .NET Standard 2.0 compliant platform, including .NET 7.0, .NET Framework 4.6.1+, .NET Core 2.0+, Unity's Mono and Godot.

Supported file formats

• data.sah/saf
• NpcQuest.SData
• KillStatus.SData
• Cash.SData
• SetItem.SData
• DualLayerClothes.SData
• GuildHouse.SData
• Monster.SData
• Item.SData
• Skill.SData
• NpcSkill.SData
• svmap
• WLD
• dg
• ANI
• 3DC
• 3DO
• 3DE
• MLT
• ITM
• SMOD
• EFT
• seff
• zon
• ALT
• VAni
• MAni
• MLX
• MON
• CTL
• dat (Cloth/Emblem)
• DBItemData.SData
• DBItemText.SData
• DBMonsterData.SData
• DBMonsterText.SData
• DBSkillData.SData
• DBSkillText.SData
• DBItemSellData.SData
• DBItemSellText.SData
• DBNpcSkillData.SData
• DBNpcSkillText.SData
• DBDualLayerClothesData.SData
• DBSetItemData.SData
• DBSetItemText.SData
• DBTransformModelData.SData
• DBTransformWeaponModelData.SData

NOTE: These file formats have been tested on Episodes 5, 6 & 8. Other episodes might differ slightly and this library might not work with them.

Features

• Shaiya file formats parsing and serialization (including JSON and CSV support)
• data extraction, building and patching
• SData encryption/decryption

Getting Started

Prerequisites

• .NET 8 SDK (recommended) or any .NET Standard 2.0 compliant platform

Documentation

Reading

From a standalone file

// Read file with default episode (EP5) and encoding (ASCII)
var svmap = ParsecReader.FromFile<Svmap>("0.svmap");

// Read file with a specific episode and default encoding
var svmap = ParsecReader.FromFile<Svmap>("0.svmap", Episode.Ep6);

// Read file with a specific episode and a specific encoding
var windows1252Encoding = CodePagesEncodingProvider.Instance.GetEncoding(1252);
var svmap = ParsecReader.FromFile<Svmap>("0.svmap", Episode.Ep6, windows1252Encoding);

From data.saf

// Load data (sah and saf)
var data = new Data("data.sah", "data.saf");

// Find the file you want to read
var file = data.GetFile("world/0.svmap");

// Read and parse the file's content directly from the saf file
var svmap = ParsecReader.FromBuffer<Svmap>(file.Name, data.GetFileBuffer(file));

From a JSON file

Parsec supports importing a file as JSON, which can be later exported as its original format. The user must make sure that the JSON file is properly formatted to match the JSON standards and contain all the fields present in the chosen format.

// Read JSON file
var svmap = ParsecReader.FromJsonFile<Svmap>("0_svmap.json");

It is advised to first read a file from its original format, export it as JSON, edit it, and import it once again as JSON, so that all the original fields are present in the JSON file.

From a CSV file

Only some pre-Ep8 SData formats support reading as CSV. All of the Episode 8 BinarySData formats have CSV support.

// Read csv file
var item = Item.FromCsv("Item.csv");

Encoding

When reading files, the default encoding is ASCII. If you want to read a file with a different encoding, you can specify it as a parameter when calling the FromFile/Json/Csv methods.

Writing

Writing a standalone file

After modifying the file, you can save it in its original format by calling the Write method. If you specified the episode and encoding when reading the file, you don't need to specify them again when writing it.

// Write file with previously defined episode and encoding (defined when reading the file)
svmap.Write("0_modified.svmap");

// Write file with a specific episode and default encoding
svmap.Write("0_modified.svmap", Episode.Ep6);

// Write file with a specific episode and a specific encoding
var windows1252Encoding = CodePagesEncodingProvider.Instance.GetEncoding(1252);
svmap.Write("0_modified.svmap", Episode.Ep6, windows1252Encoding);

Writing as JSON

Call the WriteJson method

svmap.WriteJson("map0.json");

Writing as CSV

Only some pre-Ep8 SData formats support exporting as CSV. All of the Episode 8 BinarySData formats have CSV support.

// Write as csv
item.WriteCsv("Item.csv")

Encoding

When writing files, the default encoding is ASCII. If you want to write a file with a different encoding, you can specify it as a parameter when calling the Write, WriteJson and WriteCsv methods.

Samples

sah/saf

Read and extract

// Load data (sah and saf)
var data = new Data("data.sah", "data.saf");

// Find the file you want to extract
var file = data.GetFile("world/2.svmap");

// Extract the selected file
data.Extract(file, "extracted");

Data/Patch building

// Create data from directory
DataBuilder.CreateFromDirectory("input", "output");

Patch

// Load target data and patch data
var data = new Data("data.sah", "data.saf");
var update = new Data("update.sah", "update.saf");

// Patch data
using (var dataPatcher = new DataPatcher())
{
    dataPatcher.Patch(data, update);
}

SData

Encryption / Decryption

SData encryption is slightly different for pre-Ep8 and Ep8 SData files. The SDataVersion enum is used to specify which version of SData is being encrypted (it's not necessary when decrypting);

// Encrypt
SData.EncryptFile("NpcQuest.SData", "NpcQuest.encrypted.SData", SDataVersion.Regular);

// Decrypt
SData.DecryptFile("NpcQuest.SData", "NpcQuest.decrypted.SData");

More examples can be found in the samples directory.