A standalone proof of concept for loading a local N64 ROM and running KMC-compatible GCC 2.7.2 → GNU assembler 2.6 → GNU linker 2.46 → byte comparison entirely in the browser.
The compiler runs in a Web Worker. No compilation service, native subprocess, local decompdecomp installation, API key or AI calls are required. The development server only serves static assets. The ROM is read through the browser file picker and is saved locally in IndexedDB (never uploaded).
Node 22.12+ (Node 24 recommended):
npm ci
npm run devOpen http://127.0.0.1:4179. dev stages the pinned WASM modules automatically. For production, npm run build, then serve dist/ over HTTP(S). Do not open index.html via file://. Static asset paths currently assume hosting at the origin root.
- Choose your local V-Rally ROM (
.z64,.v64, or.n64, uncompressed). Other N64 ROMs can also be inspected. - Start with the original, self-contained Return zero, Add, or Clamp C examples, or enter a candidate and its declarations. Set the function identifier and actual link VRAM.
- Compile. The tool output lists each actual WASM compiler/assembler/linker invocation. The generated ELF can be downloaded.
- Compare at a known ROM offset, or search for instruction-aligned exact byte occurrences. The selected function's ELF symbol size is used; assembler section padding is excluded.
- Export a candidate proposal for future host-side rechecking. This downloads JSON locally; it does not submit anything.
A byte occurrence is not a function identity. Tiny return stubs repeat throughout games; matching eight bytes does not establish a unique function or prove the surrounding function boundaries. The ROM entry point is only an initial link-address suggestion, not an automatic ROM-to-VRAM mapping. Set the correct VRAM and ROM offset for a real task.
On Chromium on macOS, the browser-produced bytes matched the installed native KMC-compatible compiler/assembler for five original test functions: return-zero (8 bytes), addition (8), clamp (36), memory loads (16), and a conditional branch (20).
A local V-Rally PAL ROM loaded successfully, and the independently compiled eight-byte return-zero sequence had 16 exact occurrences. This validates local ROM loading and byte comparison, not 16 newly decompiled functions. No ROM bytes or extracted game source are in this repository.
The production browser test uses a homemade ROM fixture, verifies exact linked bytes, external call relocation, syntax/link failures, source-bound proposal export, mobile layout and the absence of uploads. These checks run without any commercial game.
npm test
npm run build
npx playwright install chromium
npm run test:browserFor an existing local Chromium, set BROWSER_EXECUTABLE=/path/to/chrome. PLAYWRIGHT_MODULE may point to an existing Playwright module for local QA.
The pinned romdev packages contain WebAssembly ports of the decompals KMC-compatible compiler and binutils assembler. Their generated glue targets Node's file APIs. scripts/stage-tools.mjs adds a host binding to that glue; src/host.js supplies an in-memory filesystem and a deliberately narrow host facade inside the browser worker. It cannot spawn native processes or access the real filesystem. The WASM binaries themselves are copied without modification.
The browser runs explicit preprocessing, cc1, assembler, linker and objcopy passes. It does not run GCC's native driver or require its process-spawn hook. docs/toolchain-lock.json records module SHA-256 hashes. Source pins, upstream patches and rebuild references are in THIRD_PARTY.md.
This is a KMC-compatible open-source compiler build, not a redistributed proprietary Nintendo SDK. GCC's emitted MIPS code is the compatibility target. Browser and native hosts can expose differences on inputs beyond the tested corpus; every real candidate still needs its own target-byte check.
- Freestanding C, one translation unit, MIPS III, big endian, 32-bit GPR/FPR;
-O0through-O3,-G0or-G8. No C++ frontend, SDK headers, libraries, include-tree importer, decompiler, function discovery or full-game rebuild yet. - No standard headers or implicit runtime libraries. Supply declarations in the editor and explicit linker symbols when needed. Undefined references are errors.
- Bytes are extracted for one defined ELF function. This is not a rodata/data/relocation-aware whole-function semantic judge; string tables, jump tables and surrounding dependencies need a fuller task format and host recheck.
- Explicit preprocessor macros approximate this freestanding setup; this is not a full emulation of every GCC driver flag/spec or environment. Branches dependent on other predefined macros need explicit handling.
- ROMs persist locally in IndexedDB; use Forget saved ROM to remove them. Source edits and the worker filesystem are still temporary: download proposals before closing. Stop terminates the worker.
- The memory-only host adapter is intentionally limited; it is not Node.js in the browser. The worker's filesystem is not a system filesystem.
- An optional, explicitly paired desktop bridge supports manual KMC ROM tasks and source submission for independent host checking. See the bridge protocol. No automatic room joining or work claims.
App code: GPL-3.0-or-later. Individual third-party tools retain their upstream licenses; see THIRD_PARTY.md. No ROMs, SDK headers, extracted functions or user credentials are distributed.
Requires the matching browser-worker bridge update in decompdecomp. The older app does not expose these routes.
- In desktop Settings → Pair a browser worker, select a local KMC ROM project, set the exact browser origin shown by this page (normally
http://127.0.0.1:4179), and create a code. - In this page’s Connect to decompdecomp, enter the desktop loopback URL (normally
http://127.0.0.1:6464) and the code. Press Pair. Browser localhost permission may be requested. - Load your own matching ROM, choose an open function and press Fetch task. The ROM and target-range hashes must match.
- Edit the function body, Compile, then Submit compiled candidate. The desktop app recompiles the saved source snapshot with its own toolchain and unchanged judge.
- Fetch a fresh task after submission. Tasks expire after five minutes and do not reserve a function; if another agent claims or changes it, submission is rejected.
The token is saved in localStorage to reconnect after a browser restart and is scoped to one origin/project for one hour. Revoke project browser access in desktop Settings immediately invalidates capabilities, including results still compiling. Restarting the desktop app also invalidates them. Disconnect ends the current tab’s connection. Forget saved connection removes the saved token without ending the active connection; neither action revokes other browsers.
The initial bridge accepts plain C (no source preprocessor directives, assembly or attributes), self-contained host declarations, and an allowlisted KMC flag set including debug levels. Native imports, other toolchains and unrestricted files/commands are unavailable. The browser can still compile standalone examples without pairing.
Linker symbol addresses are passed through the generated linker script, avoiding oversized WASM command-line argument stacks for full project symbol tables.
The instruction diff runs pinned GNU objdump WASM locally over the selected ROM range and linked candidate bytes. Instruction words determine equality; colored rows show operand changes, changed instructions, and moved-word hints. Long identical runs can be expanded. This view does not replace the desktop host’s authoritative match score.
Assembly and the candidate side of the instruction diff display # C:line source comments when the selected compiler flags emit GCC line information. Comments use the compiled source snapshot, excluding host context lines. Optimized code may combine/reorder source statements; this is compiler attribution, not a one-to-one causal mapping. Missing debug information leaves instructions unannotated, without changing compiler flags or inventing target source.
The compiler selector above Compile & check uses host-offered variations from the task packet. The active host profile is selected initially; changing it invalidates the old compiled result. Older desktop versions that do not send variations show only the current profile. Host verification receives the selected variation ID and may publish exact function-local settings after independently checking them.
src/data/mips-instructions.json is the editable reference for N64 CPU / MIPS III mnemonics and common GNU assembler aliases. It includes brief descriptions, categories, branch delay-slot behavior and source links to the NEC VR4300 manual and GNU binutils documentation. Hover over an underlined mnemonic in assembly/diff views for a description; gutter difference popups also explain the target and compiled instructions. The separate RSP vector instruction set is outside this CPU compiler workflow. Unknown mnemonics receive no invented explanation.
Operand-specific explanations live in src/data/operand-hints.json. Gutter popups distinguish register allocation hints (including v0/v1), fixed-purpose registers, stack offsets, data/global-pointer offsets, branch destinations and constants. Observed operand differences are stated separately from common causes and suggested checks; the popup does not infer the original source or prove semantic equivalence.