NdsForge.NET 1.0.1
Read, validate, edit, compare, and build Nintendo DS and DSi images from .NET
Loading...
Searching...
No Matches
NdsForge.NET

NdsForge: a dual-screen mark joined by a forge spark

NdsForge.NET

Warning
Created with substantial help from GPT-5.6-Sol Ultra and tested against my own use cases. Please do not treat this project as a measure of my abilities as a developer, for better or worse.

CI Documentation NuGet .NET 10 [License: MIT](LICENSE)

Get NdsForge on NuGet · Browse the API documentation →

Getting started · Formats and safety · CLI reference · Corpus testing

NdsForge is a pure C# library for inspecting, validating, extracting, editing, comparing, and building Nintendo DS and DSi software images. Its object-oriented API supports path, stream, and in-memory workflows without shelling out to native tools.

Quick start

Install the library:

dotnet add package NdsForge
using NdsForge;
await using NdsImage image = await NdsImage.OpenAsync("game.nds");
Console.WriteLine($"{image.Header.Title} [{image.Header.GameCode}]");
Console.WriteLine($"{image.FileSystem.Files.Count} NitroFS files");
NdsValidationResult validation = image.Validate();
foreach (NdsDiagnostic diagnostic in validation.Diagnostics)
{
Console.WriteLine($"{diagnostic.Severity}: {diagnostic.Code}: {diagnostic.Message}");
}
NdsForge.NdsImage
Provides structured, random-access inspection of a Nintendo DS-family image.
Definition NdsImage.cs:5
NdsForge.NdsImage.OpenAsync
static async ValueTask< NdsImage > OpenAsync(string path, NdsReadOptions? options=null, CancellationToken cancellationToken=default)
Opens an image from a filesystem path without loading the entire file into memory.
Definition NdsImage.cs:57
NdsForge.NdsValidationResult
Contains all diagnostics produced by a validation pass.
Definition NdsValidationResult.cs:5
NdsForge.NdsValidationResult.Diagnostics
IReadOnlyList< NdsDiagnostic > Diagnostics
Retains stable validation order so command-line output, tests, and build logs remain reproducible.
Definition NdsValidationResult.cs:14

Parsing creates a navigable image model without modifying the source. Validation is explicit and reports structured findings instead of printing tool-specific text.

Highlights

  • Typed DS, DSi-enhanced, and DSi-exclusive headers
  • NitroFS directories, files, IDs, allocations, overlays, programs, banners, and SDK footers
  • Bounded parsing and structured integrity diagnostics for untrusted images
  • Safe selective extraction with traversal, collision, and reparse-point defenses
  • Preservation-oriented edits with reviewable plans and atomic path writes
  • Deterministic DS and DSi image construction from binary or supported ELF inputs
  • Stable JSON manifests and semantic image comparison
  • Caller-supplied KEY1, DSi digest, HMAC, modcrypt, and RSA operations
  • An optional Ndstool1503 build profile for verified interoperability cases
  • A cross-platform ndsforge .NET command-line tool over the same library

Edit an image

using NdsImage source = NdsImage.Open("game.nds");
NdsImageEditor edit = source.Edit();
edit.Header.Title = "MY MOD";
edit.ReplaceFile("/data/config.bin", File.ReadAllBytes("config.bin"));
edit.RepairHeaderCrc().RepairBannerCrcs();
NdsSaveResult result = await edit.SaveAsync(
"mod.nds",
new NdsWriteOptions { VerifyOutput = true });
NdsForge.NdsImageEditor
Collects explicit image changes and saves them without mutating the source.
Definition NdsImageEditor.cs:7
NdsForge.NdsImageEditor.ReplaceFile
NdsImageEditor ReplaceFile(string path, ReadOnlySpan< byte > contents)
Replaces a named NitroFS file.
Definition NdsImageEditor.cs:43
NdsForge.NdsImageEditor.SaveAsync
async ValueTask< NdsSaveResult > SaveAsync(string path, NdsWriteOptions? options=null, CancellationToken cancellationToken=default)
Saves to a new or atomically replaced filesystem path.
Definition NdsImageEditor.cs:147
NdsForge.NdsImageEditor.RepairBannerCrcs
NdsImageEditor RepairBannerCrcs()
Replaces the current banner with a copy whose version-defined CRC slots are repaired in place.
Definition NdsImageEditor.cs:112
NdsForge.NdsImageEditor.RepairHeaderCrc
NdsImageEditor RepairHeaderCrc()
Selects only the common header checksum for repair; other damaged checksums remain untouched.
Definition NdsImageEditor.cs:95
NdsForge.NdsImage.Open
static NdsImage Open(Stream stream, bool leaveOpen=false, NdsReadOptions? options=null)
Opens an image from a caller-supplied readable, seekable stream.
Definition NdsImage.cs:68
NdsForge.NdsWriteOptions
Controls preservation-oriented image saves.
Definition NdsWriteOptions.cs:5

An unchanged preservation edit is byte-identical. Structural file-system changes use NdsImageBuilder.FromImageAsync, keeping local patching and full rebuilding as separate, explicit workflows.

Command line

dotnet tool install --global NdsForge.Cli
ndsforge inspect game.nds
ndsforge validate game.nds
ndsforge list game.nds --long
ndsforge extract game.nds workspace
ndsforge manifest game.nds game.manifest.json
ndsforge diff game.nds rebuilt.nds

See the CLI reference for commands, options, and exit codes.

Compatibility and scope

NdsForge targets .NET 10 and has no runtime NuGet dependencies. It handles Nintendo DS image/container structures; it is not an emulator, disassembler, save editor, or game-specific archive library. PNG/GIF authoring and proprietary game compression belong in separate adapters.

No ROMs, firmware, keys, certificates, or proprietary logo data are included. Cryptographic operations require caller-owned key material. Some authenticity checks cannot be completed from public image data alone, and validation distinguishes missing trust inputs from invalid content.

The compatibility suite uses synthetic fixtures and hash-bound expectations for legally dumped private images. Where an ndstool comparison is meaningful and deterministic, NdsForge records byte-level or semantic parity. Read formats, compatibility, and safety before handling unknown images or performing authenticated DSi builds.

Contributions should follow CONTRIBUTING.md, security reports follow SECURITY.md, and releases follow RELEASING.md. Licensed under the [MIT License](LICENSE).

NdsForge.NET is maintained by Julius Jacobsohn. It is not affiliated with or endorsed by Nintendo, devkitPro, or the maintainers of ndstool.