MAMEKIT

MAMEKIT is a MAME-source compiler for producing inspectable, browser-native machine exhibits. It is the engineering toolkit behind MAME History.

The project treats MAME source as an archival technical record. It extracts machine facts and executable behavior from selected MAME drivers, preserves source provenance through a knowledge graph and typed intermediate representations, and generates a self-contained web application.

MAMEKIT is deliberately:

• MAME-specific, not a general C++ transpiler;
• source-derived, not a collection of handwritten TypeScript chip ports;
• inspectable, not an opaque native or WebAssembly build of MAME;
• selective, generating verified machines rather than claiming universal driver compatibility;
• ROM-free, requiring users or tests to supply legally obtained dumps.

WHAT GENERATES THE CODE

MAMEKIT is a deterministic compiler. It parses MAME's C++ and its macro and opcode DSLs into ASTs, lowers them to typed IR, and a generic host executes that IR. No language model is in the generation path, and no generated emulation behavior originates in model weights: every generated behavior traces to a MAME source location through the provenance graph, and unsupported source shapes fail visibly through diagnostics rather than being guessed at.

Language models are used to write the compiler, the way any other development tool is used. That is a statement about how this repository's own TypeScript was authored, not about where the emulation comes from.

HOW MACHINES ARE VERIFIED

Looking right counts for nothing here. A machine is graded against MAME itself:

• Behavior — real-ROM acceptance contracts run each machine headless and compare recorded goldens, with frame-by-frame pixel diffs and register checkpoints against a real MAME build of the same release (docs/TESTING.md).
• Against MAME — tools/mame-oracle.ts runs a machine beside that same MAME with the same input and reports differing pixels, RAM and bus accesses frame by frame; each machine's latest result ships with it and is shown on its page.
• Facts — npm run audit:facts diffs every generated machine's year, manufacturer, driver file, screen geometry, CPU clocks and ROM loads against that same MAME's own -listxml output, and fails on disagreement.
• Limits — where the two genuinely model different things, the difference is reported rather than hidden. The Galaxian family is the standing example: MAME renders those screens three times as wide so stars and bullets can sit on sub-character positions, and audit:facts prints that as a known divergence.

A target that diverges is not enabled. This is not bug-for-bug compatibility with MAME, and nothing here claims to be MAME.

SYSTEM MODEL

MAME C++ and macro/opcode DSLs
                |
                v
MAME-specific source-preserving ASTs
                |
                v
machine knowledge graph + source provenance
                |
                v
typed machine / handler / CPU / device / video / audio IR
                |
                v
generated JSON + TypeScript/JavaScript in dist
                |
                v
generic browser host: canvas, Web Audio, input, files, scheduling

The original program code from the supplied ROM executes in generated CPU definitions. MAME machine configuration, address maps, callbacks, graphics, video, sound, and device behavior are lowered from MAME source. Checked-in runtime code provides generic IR execution and browser services only.

There is no Emscripten emulation build and no checked-in TypeScript copy of MAME hardware.

QUICK START

Requirements:

• Node.js 23.6 or newer;
• this repository;
• a MAME source checkout at ../mame, or an explicit --mame-src / MAME_SRC path;
• local ROMs only for acceptance or browser testing.

npm ci
npm run gen:all
npm run test:unit
npm run audit:generated
npm run dev

npm run gen:all always deletes dist before generation. The current branch auto-discovers every supported-game contract. Generation uses a bounded worker pool sized to available CPU parallelism; override it with npm run gen:all -- --jobs 12 when needed. The shared hardware closure and app are built once after the target workers finish.

npm run dev compiles the browser application, serves it at http://localhost:8280/app/, and recompiles when files under src/ or bin/ change. Use npm run dev -- 9000 to select a different port.

npm run serve is the no-compile option: it serves whatever dist already holds and starts immediately, warning if the app shell is older than the files under src/runtime, src/ir or src/hardware. npm run serve:build recompiles the app shell from the working tree first, which is what you want after editing runtime source without a full gen:all.

To add a target, start with npm run game:init -- <shortname> and follow the candidate workflow. A candidate is published labelled EXPERIMENTAL and stays out of real-ROM acceptance until it is promoted.

REPOSITORY MAP

src/mame/       MAME ASTs, opcode DSL parsing, typed lowering and hardware closure
src/kg/         knowledge-graph construction, schema, Cypher and viewer
src/gen/        machine/config emitters, app build, reports and generated audits
src/games/      small supported-game QA tokens, source specs and shared acceptance
src/runtime/    browser host and generic typed-IR execution
bin/            CLI entry point
scripts/        deployment automation
tools/          engineering diagnostics
e2e/            browser QA: every accepted machine played through the app
docs/           current architecture, contribution, engineering and QA references
dist/           disposable generated distribution

GENERATED DISTRIBUTION

dist/
├── app/                         app entry, registry and static game routes
├── runtime/
│   ├── core/                    compiled generic runtime
│   └── generated/               MAME-derived hardware, IR and audio modules
├── games/
│   ├── arcade/<game>/           arcade graph, machine, metadata and dossier
│   ├── consoles/<system>/       console graph, machine, metadata and dossier
│   └── computers/<system>/      computer graph, machine, dossier and software shelves
├── games.json                   generated catalog
└── index.html                   redirect to app/

The output is canonical and self-contained:

• app files are not duplicated under game directories;
• game modules are not duplicated under app;
• generated data is stored as JSON, not embedded in JavaScript strings;
• generated behavior imports canonical JSON and shared runtime modules;
• browser modules never import src or files outside dist.

dist is disposable. Never diagnose or preserve a mixed build: clean and regenerate it.

ENGINEERING DOCUMENTATION

There is one README and four current engineering documents:

• SYSTEM ARCHITECTURE: system design, compiler stages, knowledge graph, typed IR, generated runtime, browser execution, provenance, and hard boundaries.
• CONTRIBUTING: contribution contract, adding a machine (the candidate workflow from game:init to game:promote), fixing generation gaps, acceptance evidence, and review requirements.
• ENGINEERING GUIDE: commands, extending a target, debugging generation gaps, tests, browser verification, deployment, and maintenance rules.
• TESTING: QA levels, supported-game tokens, deterministic real-ROM contracts, CI, golden review, and failure triage.

NON-NEGOTIABLE INVARIANTS

1. MAME hardware behavior is generated from MAME source.
2. src/runtime contains no handwritten MAME CPU, device, audio, video, or board implementations.
3. The knowledge graph is an executable dependency and provenance model, not only a visualization format.
4. JSON stores data; TypeScript/JavaScript stores behavior.
5. dist is cleaned before complete generation.
6. Generated output is self-contained and has one canonical copy of each artifact.
7. ROMs are never served, committed, or deployed. A visitor's own dump may be kept only in their own browser, by their own choice, and forgotten from the page.
8. Unsupported source shapes fail visibly through diagnostics and reports.
9. No language model is in the generation path; generated behavior traces to a MAME source location.
10. Attribution comes from driver headers and MAMEDEV release notes. Commit history is reported as activity and never as authorship.

ATTRIBUTION

Credit for a MAME driver comes from the two records that state it:

1. the driver header's copyright-holders line, which is MAME's own statement of who wrote the file and the only record reaching back before the release-notes era;
2. MAMEDEV's published release notes, which credit contributors per release (src/gen/release-notes.ts, fetched by tools/fetch-release-notes.ts).

Commit history is deliberately not one of them. git log --follow does not reliably track code moved between files, counts a typo fix like a rewrite, records work landed on someone's behalf against the committer, and cannot reconcile inconsistent spellings of a name. Pac-Man is the standing example: its top committers are the people who refactored the whole tree, while its header credits Nicola Salmoria. Commit counts are still shown, labelled as commit activity on the driver file, and never as authorship.

None of this is a complete record of who worked on MAME, and it is not offered as one.

LEGAL AND PROJECT SCOPE

MAMEKIT does not contain or distribute ROMs. Artwork and historical material remain the property of their rights holders. MAMEKIT is independent from and not endorsed by MAMEDEV.

Generated output is a mechanical derivative work of the MAME source it was compiled from. Each generated machine carries the licence and copyright holders of the driver it came from (license and copyrightHolders in its meta.json, shown on the machine's page and browsable in the archive), so the terms travel with the artifact rather than being asserted once in prose.

MAMEDEV's release notes are fetched into the gitignored asset tree and are never committed or served: they are MAMEDEV's material, used here to attribute their own contributors, not ours to redistribute.

Current implementation work is tracked in GitHub issue 21.