KiraPatch DS

KiraPatch DS is my Gen 4 follow-up to KiraPatch.

I am building this workspace to support Nintendo DS Pokemon ROM inspection first, then legality-preserving shiny-odds patching once I lock onto one clean ROM at a time.

Naming Style

In this README, I talk about games as:

• Pokemon - Diamond (EU)
• Pokemon - Diamond (NA)

I do that to keep the wording clean and avoid making it sound like I am distributing anything. Internally, the tool still fingerprints the exact dumped revision before I patch anything.

Current Status

The project currently includes:

• a Python CLI for inspecting .nds and .srl files
• header parsing for Nintendo DS ROMs
• CRC32 and SHA-1 fingerprinting
• FAT and overlay table parsing
• folder scanning for incoming ROM dumps
• JSON catalog export for ROM triage
• ARM9 and overlay extraction for reverse engineering
• heuristic ARM/Thumb analysis for candidate shiny-related code regions
• a live per-ROM profile for Pokemon - Diamond (EU) Rev 5
• an experimental internal-cave ARM9 patch path for the exact fingerprint of Pokemon - Diamond (EU) Rev 5

Right now, patch support is limited to that one exact Diamond EU Rev 5 fingerprint. Other Gen 4 dumps can still be inspected, cataloged, extracted, and analyzed, but I do not claim patch support for them yet.

What is still in progress:

• shiny-rate validation on the new internal-cave Diamond builds
• broader encounter-path validation beyond the currently confirmed starter and wild paths
• support for Pokemon - Pearl (EU), Pokemon - Platinum (EU), and HGSS

First Target

My first active research target is Pokemon - Diamond (EU).

More specifically, I am currently tracing the EU Rev 5 Diamond dump in .nds/, because it is smaller than the later 128 MB games and gives me the cleanest first pass at the Gen 4 shiny-generation flow.

What I Have Confirmed

For Pokemon - Diamond (EU) Rev 5, I have already confirmed:

• an exact shiny XOR compare inside ARM9
• the specific create-mon wrapper, callsite, and core path I am currently targeting
• a reusable shiny-check predicate helper in ARM9
• a validated internal ARM9 code cave at 0xF5CBC with 0x58 bytes available for the hook
• a Python patch pipeline that can patch the exact supported Diamond EU Rev 5 dump without growing ARM9 and still update the DS header CRC16
• MelonDS smoke-test success for starter selection, completing the opening battle, and basic wild encounters on the internal-cave builds

What I have not confirmed yet is the actual observed shiny frequency on the new working internal-cave builds, so I am still treating the odds side as active validation work.

The detailed reverse-engineering notes live in notes/diamond_eu_rev5.md.

Why I Start Here

Gen 4 is a larger target than Gen 3:

• ROMs are DS containers instead of flat GBA images
• the executable layout includes ARM9, ARM7, and overlays
• per-version support needs tighter fingerprinting before I patch anything

My first milestone is to make incoming dumps easy to inspect, catalog, extract, and analyze so reverse-engineering stays organized.

Workspace Layout

• kirapatch_ds.py: simple launcher
• src/kirapatch_ds/cli.py: CLI entrypoint
• src/kirapatch_ds/nds.py: DS ROM parsing, FAT parsing, and overlay parsing
• src/kirapatch_ds/extract.py: extraction helpers for ARM binaries and overlay payloads
• src/kirapatch_ds/analysis.py: heuristic and exact ARM/Thumb analysis helpers
• src/kirapatch_ds/catalog.py: scan and export helpers
• src/kirapatch_ds/profiles.py: per-ROM patch registry
• src/kirapatch_ds/patcher.py: experimental patch pipeline
• notes/diamond_eu_rev5.md: current reverse-engineering notes for the first target
• tests/test_nds.py: unit tests
• tests/test_catalog.py: unit tests
• tests/test_extract.py: unit tests
• tests/test_analysis.py: unit tests
• tests/test_patcher.py: unit tests

Usage

Inspect one ROM:

python kirapatch_ds.py inspect ".nds\\Pokemon - Diamond (EU) Rev 5.nds"

Scan the dumps folder:

python kirapatch_ds.py scan

Write a JSON catalog:

python kirapatch_ds.py catalog

Extract ARM9, ARM7, and overlays for one ROM:

python kirapatch_ds.py extract ".nds\\Pokemon - Diamond (EU) Rev 5.nds"

Run the analysis pass for the current target:

python kirapatch_ds.py analyze

Build an experimental test ROM for the currently supported Diamond dump:

python kirapatch_ds.py patch ".nds\\Pokemon - Diamond (EU) Rev 5.nds" --odds 16

Inspect as JSON:

python kirapatch_ds.py inspect ".nds\\Pokemon - Diamond (EU) Rev 5.nds" --json

At the moment, patch is only expected to succeed on the exact fingerprinted Pokemon - Diamond (EU) Rev 5 target. If I point it at another dump, the tool should refuse to patch it instead of guessing.

Expected Workflow

1. Drop dumped Gen 4 ROMs into .nds/.
2. Run python kirapatch_ds.py scan to verify the files are readable.
3. Run python kirapatch_ds.py catalog to write manifests/rom_catalog.json.
4. Extract the chosen target with python kirapatch_ds.py extract.
5. Run python kirapatch_ds.py analyze to rank and confirm the code regions I care about.
6. Add a dedicated patch profile for that exact fingerprint.
7. Build and test a ROM-specific hook before I expand support.

Development Testing

For development, I am treating 1/16 and 1/64 as practical test builds.

I am not treating 1/4096 as a manual validation build, because brute-force resets at that rate are not realistic during active hook development.

Next Build Step

My next technical milestone is:

• keep Pokemon - Diamond (EU) as the first traced target
• confirm actual shiny generation frequency on the working internal-cave Diamond hook
• map which gift, static, and other encounter paths still need explicit coverage
• only then expand the support surface to Pokemon - Pearl (EU), Pokemon - Platinum (EU), and HGSS