Nescartdb

Converted nescartdb database in JSON format, used to identify NES/Famicom cartridge PCBs by the content of their PRG/CHR dumps.

This folder is the single source of cartridge-identification data for every Breaknes consumer: the native core (BreaksCore), the managed application (Breaknes), the SDL port, and the tools (PPUPlayer, APUPlayer).

1. Why this folder exists

The old Mappers component identifies cartridges by the iNES header and the iNES mapper number. That is a poor fit for a functional simulator:

• The same iNES mapper number covers many electrically different boards.
• The header does not say what chips are on the board or how they are connected.
• Unlicensed/Famiclone boards often cannot be expressed with iNES at all.

The solution (issue #508) is to identify cartridges by board type using the nescartdb database, which describes the actual PCB of every dumped cartridge (components, sizes, CRCs, mirroring).

The native code has no XML engine, so the nescartdb XML is converted to JSON once, stored here, and consumed by everyone.

2. Data source

The export is a static snapshot (2017-08-21). The conversion is deterministic: the same XML always produces the same JSON, so the JSON can be regenerated at any time.

3. Files in this folder

Nescartdb/
  Readme.md          <- this file
  nescarts.json      <- the full converted database (generated, committed)
  index.json         <- flattened lookup index: prg_crc/chr_crc -> board type (generated, committed)
  boards/            <- board definitions (authored, not generated) + the family index

• nescarts.json — the full database, faithful to the XML: game → cartridge → board nesting, with all attributes (see §5).
• index.json — a flat array of lookup records (prg_crc, chr_crc, board.type, board.pcb, mapper, system), generated from nescarts.json. The runtime loads this small file to answer “which board types match these PRG/CHR CRCs?” without walking the whole database.
• boards/ — the board JSON definitions (nrom.json, unrom.json, aorom.json, sgrom.json, plus cnrom.json/shrom.json for the iNES fallback) and index.json, the family mapping board type → definition file (see §6.1).

The generated files are committed to the repository so that no network access is needed at build or run time.

4. Conversion pipeline

Tools/NescartdbConvert/convert.py
   XML (tepples export)  --->  nescarts.json  --->  index.json

• The converter is a small Python script (like Tools/DumpRegdump/DumpRegdump.py), kept in Tools/NescartdbConvert/.
• It is run manually (or in CI) when the source XML is updated; its output is committed.
• The converter normalizes data for native consumption:
  • sizes: "256k" → bytes (262144), "8k" → 8192, etc.;
  • booleans: battery → true/false, prototype → true/false;
  • attribute names are preserved 1:1 where possible (see the mapping table in §5).

5. JSON schema (nescarts.json)

Direct mapping of the XML structure:

{
  "source": {
    "name": "NesCartDB",
    "agent": "NesCartDB",
    "author": "BootGod",
    "export": "forum.nesdev.org - tepples/NesCarts (2017-08-21).utf8.xml",
    "converted_at": "2026-09-01T00:00:00Z",
    "converter": "Tools/NescartdbConvert/convert.py"
  },
  "games": [
    {
      "name": "10-Yard Fight",
      "altname": "１０ヤードファイト",
      "class": "Licensed",
      "subclass": "3rd-Party",
      "catalog": "IF-02",
      "publisher": "Irem",
      "developer": "Irem",
      "portdeveloper": null,
      "region": "Japan",
      "players": 2,
      "date": "1985-08-30",
      "cartridges": [
        {
          "system": "Famicom",
          "revision": null,
          "crc": "836C4FA7",
          "dump": "ok",
          "dumper": "bootgod",
          "datedumped": "2007-05-06",
          "prototype": false,
          "board": {
            "type": "IREM-NROM-128",
            "pcb": "IREM-01-V",
            "mapper": 0,
            "prg":  { "name": null, "id": null, "size": 16384, "crc": "D3D248C9" },
            "chr":  { "name": null, "id": null, "size": 8192,  "crc": "9C124A53" },
            "wram": null,
            "vram": null,
            "chips": [],
            "cic":   [],
            "pad":   { "h": 0, "v": 1 },
            "peripherals": []
          }
        }
      ]
    }
  ]
}

5.1 XML → JSON mapping

5.2 Lookup index (index.json)

[
  {
    "prg_crc": "D3D248C9",
    "chr_crc": "9C124A53",
    "system": "Famicom",
    "type": "IREM-NROM-128",
    "pcb": "IREM-01-V",
    "mapper": 0
  }
]

• One record per cartridge with a known PRG/CHR CRC pair.
• Identification is by PRG CRC32 + CHR CRC32 only (SHA1 is not used): the runtime computes CRC32 of the PRG and CHR dumps and looks up prg_crc + chr_crc.
• Multiple records may share the same CRCs (same ROMs on different PCBs) — all matches are returned; the caller picks the fit (see CartPcb/Readme.md §8).
• Records may carry the mirroring solder pads as "h"/"v" (informational). The pads use the iNES mirroring terms — the inverse of the PCB scroll term (issue #525): v=1 (iNES “vertical mirroring”) means the cartridge’s scroll jumper is set to H Scroll (VRAM_A10 = PA10), h=1 means V Scroll (VRAM_A10 = PA11). The runtime does not use the pads to override the .nes header; the scroll of scroll-jumper boards always follows the header.

6. Consumers

Deployment: the Nescartdb/ files (including boards/*.json) are copied to the output directory on build (Breaknes.csproj and BreaknesSDL.vcxproj copy them next to the executable). Native code locates them relative to the executable: the managed app passes its base directory via SetNescartdbDir; the SDL port uses the Nescartdb folder next to the executable (override with the NESCARDB_DIR environment variable). Custom boards go to the user board directory (CustomBoards/ next to the executable by default in the managed app, configurable via SetUserBoardsDir).

6.1 Board definitions (boards/)

The boards/ folder contains the board JSONs that PcbLoader resolves a board type to:

• index.json — the family mapping: board type → board definition file (e.g. all *-NROM-* types map to nrom.json). The Namco NAMCOT-3305 board (The Tower of Druaga, Pac-Land) is electrically an NROM-256 (2x16K PRG + 8K CHR, no mapper logic, hardwired H-scroll) and maps to nrom.json too (issue #527).
• nrom.json, unrom.json, aorom.json, sgrom.json — the built-in board definitions for the NROM/UxROM/AxROM/MMC1 families (the UNROM and AOROM definitions include the real 74LS161/74LS32 glue logic, see CartPcb/Readme.md §5.3).
• cnrom.json, shrom.json — boards added for the iNES fallback of “wild” dumps (issue #514): mapper 3 (CNROM, latch-based CHR bank switch) and mapper 1 with CHR-RAM (SHROM-style MMC1 wiring).

Board definitions are authored (not generated from the XML): nescartdb describes the component inventory, CartPcb adds the wiring (circuit). New board types referenced by the converter output or by the iNES fallback must be added here by hand.

7. Versioning & regeneration policy

• nescarts.json and index.json are generated artifacts, but they are committed (no network at run time, diffable history).
• When the source XML is updated: re-run Tools/NescartdbConvert/convert.py, commit the regenerated JSON, bump the source.converted_at timestamp.
• The JSON schema is versioned via source.version; breaking changes to the schema bump the version and are coordinated with CartPcb’s loader.

8. Licensing & attribution

• The data is the nescartdb database by bootgod (site run by bootgod and brizzo), mirrored at MetaFight/NesCartDB.
• The upstream mirror ships no explicit license, so the data must be treated as all-rights-reserved: keep the attribution (source block in the JSON and the Nescartdb/Readme.md), and verify redistribution terms before any release packaging.
• The XML export itself originates from a forum.nesdev.org post by tepples (2017-08-21); credit is kept in source.export.

9. Relationship to CartPcb and JSONES

• Nescartdb/ provides identification (which PCB is this dump?) — see CartPcb/Readme.md §8.
• CartPcb provides simulation of the identified PCB — the board JSON format is defined in CartPcb/Readme.md §5.
• “Wild” dumps (issue #514): when the PRG/CHR CRCs of a dump are not in index.json (homebrew, undocumented dumps), CartPcb::InesTranslator falls back to the iNES header (mapper number + PRG/CHR sizes) and maps it to one of the board types above; the dump then runs through the same board path. This is a translation, not an identification: the header is rigid and lossy, so the fallback only covers the common simple mappers.
• JSONES (issue #189) is a subset of the CartPcb board format: a single-cartridge JSON with game → cartridge → board nesting, usable as a custom board definition in addition to the built-in nescartdb data (CartPcb/Readme.md §6.5).