Nescartdb

Конвертированная в JSON база nescartdb — определяет тип картриджной PCB по CRC32 дампов PRG/CHR

База nescartdb, конвертированная в формат JSON, используется для определения типа PCB картриджей NES/Famicom по содержимому их дампов PRG/CHR.

Эта папка — единственный источник данных об идентификации картриджей для всех потребителей Breaknes: нативного ядра (BreaksCore), управляемого приложения (Breaknes), SDL-порта и инструментов (PPUPlayer, APUPlayer).

1. Зачем нужна эта папка

Старый компонент Mappers определяет картриджи по заголовку iNES и номеру маппера iNES. Для функционального симулятора это плохо подходит:

Решение (issue #508) — определять картриджи по типу платы, используя базу nescartdb, которая описывает фактическую PCB каждого дампированного картриджа (компоненты, размеры, CRC, зеркалирование).

В нативном коде нет XML-движка, поэтому XML nescartdb один раз конвертируется в JSON, хранится здесь и используется всеми.

2. Источник данных
База данныхnescartdb (bootgod / brizzo)
Используемый экспортforum.nesdev.org - tepples/NesCarts (2017-08-21).utf8.xml из зеркала MetaFight/NesCartDB
Содержимое~3179 записей картриджей, 273 различных типа плат, для всех регионов (NES-NTSC, NES-PAL, Famicom, Dendy, ...)

Экспорт — это статический снимок (2017-08-21). Конвертация детерминирована: один и тот же XML всегда даёт один и тот же JSON, поэтому JSON можно в любой момент перегенерировать.

3. Файлы в этой папке

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

Сгенерированные файлы коммитятся в репозиторий, чтобы ни при сборке, ни во время выполнения не требовался доступ к сети.

4. Конвейер конвертации

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

5. JSON-схема (nescarts.json)

Прямое отображение структуры XML:

{
  "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

XMLJSONПримечания
<database>sourceversion, conformance, agent, author, timestamp свёрнуты в source; конвертер добавляет export, converted_at, converter
<game>games[]name, altname, class, subclass, catalog, publisher, developer, portdeveloper, region, players, date
<cartridge>games[].cartridges[]system, revision, crc, dump, dumper, datedumped, prototype (sha1 намеренно опущен — идентификация только по CRC)
<board>...boardtype (тип платы), pcb (ревизия платы), mapper (номер маппера iNES — только для информации, не используется для идентификации)
<prg> / <chr>board.prg / board.chrname, id, size (байты), crc (sha1 намеренно опущен)
<wram> / <vram>board.wram / board.vramsize, battery, id
<chip>board.chips[]type (например, MMC1A, MMC3B), battery
<cic>board.cic[]type (например, 3193A, 6113)
<pad>board.padh, v (зеркалирование)
<peripherals>/<device>/<pin>board.peripherals[]сквозная передача сырых данных о пинах

5.2 Поисковый индекс (index.json)

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

6. Потребители

ПотребительКак использует эту папку
BreaksCore (native)CartPcb::NesCartDb загружает index.json для поиска «CRC → тип платы».
CartPcb (native)Board JSON, на которые ссылается индекс (встроенные определения + пользовательские переопределения).
Управляемое приложение BreaknesИщет JSON рядом с исполняемым файлом (копируется при сборке) и может разбирать его напрямую для нужд UI (тип платы показывается пользователю).
SDL-портТот же нативный путь, что и у BreaksCore.
PPUPlayer / APUPlayerИспользуют те же данные Nescartdb через нативное ядро или собственную копию.

Развёртывание: файлы из Nescartdb/ (включая boards/*.json) при сборке копируются в выходной каталог (Breaknes.csproj и BreaknesSDL.vcxproj копируют их рядом с исполняемым файлом). Нативный код ищет их относительно исполняемого файла: управляемое приложение передаёт свой базовый каталог через SetNescartdbDir; SDL-порт использует папку Nescartdb рядом с исполняемым файлом (можно переопределить переменной окружения NESCARDB_DIR). Пользовательские платы попадают в пользовательский каталог плат (по умолчанию в управляемом приложении это CustomBoards/ рядом с исполняемым файлом, настраивается через SetUserBoardsDir).

6.1 Определения плат (boards/)

Папка boards/ содержит board JSON, в которые PcbLoader преобразует тип платы:

Определения плат пишутся вручную (не генерируются из XML): nescartdb описывает перечень компонентов, а CartPcb добавляет разводку (circuit). Новые типы плат, на которые ссылаются вывод конвертера или iNES-фолбэк, нужно добавлять здесь вручную.

7. Политика версионирования и регенерации

8. Лицензирование и атрибуция

9. Связь с CartPcb и JSONES