/Yarhl

Framework for the implementation of format converters like game assets or media files

Primary LanguageC#MIT LicenseMIT

Yarhl, A format ResearcH Library awesomeness

Yarhl Logo

Stable version   GitHub commits since latest release (by SemVer)   Build and release   CII Best Practices   MIT License  

Yarhl is a set of libraries that helps to implement and convert file formats. It provides a virtual file system, format conversion APIs, full featured binary IO and plugin support to support common formats. It's built in C# / .NET and works in any OS that supports the .NET runtime.

  • 📚 Format implementation architecture and guidelines
  • ♻️ Format conversion API
  • 📂 Virtual file system with format transformations
  • 🔢 Enhanced binary IO API
    • Custom Stream with sub-stream supports (memory and disk efficient!)
    • Full feature binary and text readers and writers
    • Simple binary (de)serializer by attributes in the model.
  • 📃 Standard text formats
    • Industry-standard localization format: GNU gettext PO
    • Table text replacements
    • Common encodings: euc-jp, token-escaped encoding
    • API for simple encoding implementations
  • 🔌Plugin API to load and find types in .NET assemblies.

Get started

Check out the documentation site to start learning the power of Yarhl.

Feel free to ask any question in the project discussions.

Usage

This project provides the following libraries as NuGet packages (via nuget.org). The libraries support the latest version of .NET and its LTS.

  • Yarhl: core, format conversion, file system and binary reading / writing (IO).
  • Yarhl.Media.Text: text formats (Po) and encodings.
  • Yarhl.Plugins: discover formats and converters from .NET assemblies.

Preview releases can be found in this Azure DevOps package repository. To use a preview release, create a file nuget.config in the same directory of your solution file (.sln) with the following content:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear/>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="SceneGate-Preview" value="https://pkgs.dev.azure.com/SceneGate/SceneGate/_packaging/SceneGate-Preview/nuget/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="SceneGate-Preview">
      <package pattern="Yarhl*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Then restore / install as usual via Visual Studio, Rider or command-line. You may need to restart Visual Studio for the changes to apply.

Showcase

Some cool projects built with Yarhl:

  • Texim: experimental API for image file formats.
  • Ekona: support Nintendo DS file formats.
  • Lemon: support Nintendo 3DS file formats.
  • LayTea: modding tools for Professor Layton games.
  • Attack of Friday Monsters tools: modding tools for Attack of the Friday Monsters game.
  • Metatron: translation framework for Shin Megami Tensei saga games.

Contributing

The repository requires to build .NET 8.0 SDK.

To build, test and generate artifacts run:

# Build and run tests
dotnet run --project build/orchestrator

# (Optional) Create bundles (nuget, zips, docs)
dotnet run --project build/orchestrator -- --target=Bundle

Additionally you can use Visual Studio or JetBrains Rider as any other .NET project.

To contribute follow the contributing guidelines.

How to release

Create a new GitHub release with a tag name v{Version} (e.g. v2.4) and that's it! This triggers a pipeline that builds and deploy the project.

License

The software is licensed under the terms of the MIT license.