TomoForge

Nintendo DS ROM Toolkit
Inspect, validate, extract, rebuild, and patch Nintendo DS-family ROMs.

---

TomoForge is a Windows-first desktop workspace for the Nintendo DS .nds format. It works at the ROM-container level across retail games and homebrew instead of assuming every game uses the same text, graphics, script, or compression formats.

TomoForge ships no commercial game ROMs. Use legally obtained dumps and share patches rather than copyrighted game images.

Download (Windows)

⬇ Download the latest release — no Python or setup required.

1. On the Releases page, download TomoForge-windows.zip under Assets.
2. Right-click the zip → Extract All.
3. Open the extracted folder and double-click TomoForge.exe.

First-launch note: because the app is not code-signed yet, Windows may show "Windows protected your PC". Click More info → Run anyway. This is expected for indie apps; the download is the build produced by this repo's GitHub Actions.

Not the green "Code → Download ZIP" button. That gives you the source code, which needs Python to run (see Run from source). For a ready-to-run app, always use Releases.

macOS builds are experimental and not yet published; build from source for now.

What it does

• ROM Lab: reads NTR and TWL headers, streams MD5/SHA-256/CRC32 hashes, verifies Nintendo header/logo CRC16 values, and checks executable, FNT, FAT, and overlay ranges.
• NitroFS workspace: searches every embedded file, exports files by ID/path, stages replacements, and shows size changes before a build.
• Verified rebuilding: rebuilds standard Nintendo DS (NTR) ROMs to a new file, preserves the source, writes atomically, and reopens the output for structural checks.
• Patch tools: applies xdelta, IPS, UPS, and BPS patches with automatic format detection, input validation, atomic output, and post-patch ROM verification; creates xdelta patches for any ROM and IPS patches up to the format's 16 MB limit.
• Profile extensions: enables tested game-specific editors only when a matching game profile is installed. The bundled Tomodachi Collection profile retains its one-click English patch and control-code-aware translation studio.
• Friendly failures: backend exceptions become stable error codes, plain-language remedies, and diagnostic details instead of raw crashes in the UI.

Systems and formats

Software image	Inspect	Extract NitroFS	Replace/rebuild	Patch
Standard Nintendo DS / DS Lite .nds (NTR)	Yes	Yes	Yes	Yes
DSi-enhanced .nds (TWL)	Yes	Yes	Read-only	Yes
DSi-exclusive .nds (TWL)	Yes	Yes	Read-only	Yes
DS/DSi-mode ROM used on any 2DS/3DS/New model	Yes	Yes	Based on NTR/TWL row	Yes
Native Nintendo 3DS .3ds / .cia	No	No	No	No

Patch format	Apply	Create
xdelta / VCDIFF	Yes	Yes
IPS	Yes	Yes (ROMs up to 16 MB)
UPS	Yes (CRC-verified)	No
BPS	Yes (CRC-verified)	No

DSi-aware NitroFS rebuilding is deliberately disabled. Generic repacking can invalidate DSi-specific signed regions that the current backend does not safely regenerate.

Native 3DS software is not an NDS ROM even though 3DS-family systems can run many Nintendo DS games through backward compatibility.

TomoForge explicitly reports guidance for Nintendo DS, DS Lite, DSi, DSi XL, 3DS, 3DS XL, 2DS, New 3DS, New 3DS XL, and New 2DS XL. See docs/COMPATIBILITY.md for the complete NTR/TWL matrix, common model aliases, Slot-2 exceptions, and launcher-dependent limits.

Game compatibility

The general ROM tools are format-based and do not need a game profile. Game-specific text, graphics, scripts, archives, compression, checksums, and anti-tamper behavior vary, so TomoForge does not pretend one editor can safely understand all of them.

Specialized editing is profile-driven. Unsupported games still receive ROM validation, hashing, NitroFS browsing/export, safe NTR replacement/rebuilding, and xdelta tooling.

Safety model

• The selected source ROM is never overwritten.
• Rebuild and patch outputs use temporary files and atomic replacement.
• Every generated .nds is structurally parsed again before success is reported.
• File IDs and ranges are bounds-checked.
• DSi-aware images are read-only for direct repacking.
• Hashes are streamed instead of loading an entire ROM just to identify it.

No tool can guarantee that an arbitrary replacement file obeys a game's private runtime format. Keep backups and test modified builds in an emulator before hardware.

Run from source

pip install -e .
python -m tomoforge.app

For a browser-only design preview:

cd src/tomoforge/web
python -m http.server 8765

Then open http://127.0.0.1:8765/.

Develop and test

pip install -e ".[dev]"
python -m pytest
python tools/fetch_fonts.py

The test suite covers header parsing, CRC validation, malformed section and FAT ranges, NitroFS rebuild verification, source-overwrite protection, DSi write blocking, hardware model reporting, BMG round trips and control codes, projects, and real xdelta round trips when the bundled binary is available.

Build for Windows

pip install pywebview ndspy pillow pyinstaller
python tools/fetch_fonts.py
pyinstaller packaging/tomoforge.spec --noconfirm

GitHub Actions builds TomoForge-windows.zip on every push (as a workflow artifact). Pushing a version tag (vX.Y.Z) additionally publishes a GitHub Release with the zip attached automatically, so cutting a release is just a tag push. macOS remains experimental and is available only through manual workflow dispatch.

Architecture

web UI -> service/api.py (facade) -> service/
                                  |- session.py     one RomSession shared by every view
                                  |- workspace.py   NitroFS list/export/stage/build
                                  |- studio.py      profile-driven text editing
                                  |- patching.py    patch flows
                                  |- settings.py    recent ROMs, theme
                                  |- dialogs.py     native file dialogs
                                  `- events.py      progress events to the UI
                                  -> core/
                                  |- romfile.py      header, hashes, structural validation
                                  |- nitrofs.py      file inventory, export, safe rebuild
                                  |- banner.py       icon + localized titles (read-only)
                                  |- patch.py        atomic patch apply/create + dispatch
                                  |- patchformats.py pure-python IPS/UPS/BPS
                                  |- profiles.py     JSON game profiles (resources/profiles/)
                                  |- codecs.py       text codec registry (bmg, ...)
                                  |- bmg.py          Tomodachi profile text codec
                                  `- project.py      saved edits without storing a ROM

Adding a game later means dropping a JSON descriptor into resources/profiles/ and, only if its text format is new, registering one codec in core/codecs.py.

Legal and credits

TomoForge is an independent, non-commercial project and is not affiliated with Nintendo. Nintendo DS, DSi, 3DS, and game names are trademarks of their respective owners.

The Tomodachi profile builds on jjjewel's Rev 0.80 translation. TomoForge uses ndspy by Roppy Chop Studios and xdelta3 by Joshua MacDonald. See THIRD_PARTY_NOTICES.md and docs/AUDIT.md for distribution obligations and residual risks.