Native ports: play N64 recompilations (Zelda64Recomp etc.) as one-game standalone launchers

[cubman3134]

Asked from use: "I saw there was a recomp launcher that used recomps. Can we do that on our system?"

What exists out there

N64 static recompilations — N64Recomp turns a ROM into a native PC
executable; the port ships as a normal GitHub Release and the user supplies their own ROM. Fourteen are
playable today (Majora's Mask, Mario Kart 64, Star Fox 64, Banjo-Kazooie, Goemon, Harvest Moon 64, Dr. Mario
64, Quest 64, Snowboard Kids 2, Bomberman 64/Hero, Duke Nukem ZH, Dinosaur Planet, Extreme-G) per
readonlymemo's list and
Held Games.

The launcher the user saw is SirDiabo/GithubLauncher
(formerly "N64Recomp Launcher", renamed at the N64Recomp developers' request), MIT. It is generic: an
apps.json of {name, repository, folderName, appIconUrl} entries, each pointing at a GitHub repo whose
latest Release it downloads and updates. It does nothing about ROMs — the user handles that per port.

Why this fits EB almost entirely with what already exists

A recomp port is, structurally, a standalone emulator that can run exactly one game. EB's standalone tier
(EmulatorRegistry::ExternalEmulator) already has every mechanism the launcher has, and more:

• resolution from api.github.com/repos/<o>/<r>/releases/latest (updateJsonUrl) — the same thing the
  launcher does
• per-OS artifact patterns and binaries (winArtifact/linuxArtifact/macArtifact, winBinaries…)
• auto-install into emulators/<id>/, argsTemplate, fullscreen args, a homepage fallback
• a load-bearing systems binding that makes an entry selectable for a system, and a per-game /
  global emulator picker in both settings builders (this is how ares became a selectable N64 emulator)

What it does not have is the one new concept a port needs: binding to a game, not a system. ares
can run every N64 game; Zelda64Recomp can run one. Offering it on every N64 row would be wrong.

Proposed behaviour

1. A port catalog as data, not code — native/ports/n64recomp.json shipped in-tree, overridable from
   <data>/ports/*.json exactly as <data>/systems/*.json overrides systems (Data-driven system catalog: grow toward ES-DE's system coverage without recompiling #92). Per entry: display
   name, GitHub owner/repo, per-OS asset patterns, executable name, the game it runs (No-Intro title
   • accepted region/revision + known-good hash where published), how it takes the ROM, portable-mode
     flag, license, homepage. Data because the catalog rots: readonlymemo's Mario Kart link 404s today,
     the upstream is not on GitHub under that name, and asset naming differs per port
     (Zelda64Recompiled-v1.2.2-Windows.zip vs MarioKart64Recompiled-0.9.2-anylinux-x86_64.AppImage).
2. A "Native port" verb on the matching game's row only — surfaced beside the existing backend/emulator
   choice for that one N64 title, never on the system. Matching is by identity: the game's catalog key
   and, where the user has a No-Intro DAT loaded, HashVerify against the port's accepted dump. Without a
   DAT, fall back to the title match and let the port's own check speak (Zelda64Recomp refuses a wrong
   ROM itself).
3. Install = the existing standalone-emulator install, pointed at the port's release. Tolerate
   releases/latest 404 (prerelease-only projects) by falling back to the newest release in the list.
4. ROM provisioning per port's declared mode. Zelda64Recomp asks for the ROM in its own main menu and
   auto-converts formats; some ports want the file beside the exe; some take a CLI path. The catalog entry
   declares which; EB does the placing/pointing where it can and otherwise opens the port and tells the
   user what to pick. Never modify the user's ROM.
5. Saves stay the port's (%LOCALAPPDATA%\<Port>\saves etc.), with portable.txt honoured where a
   port supports it so a per-profile layout is possible later. Not in scope now: importing/syncing them.

Not in scope

Building recomps from source; non-N64 decomps (Ship of Harkinian, sm64 PC port — different tooling, a
follow-up if wanted); modding/mod-manager integration each port offers; anything that ships a ROM.

Risks stated up front

• Catalog maintenance is the real cost. Fourteen upstreams, several under individual accounts,
  renames and 404s already observed. Data + user override keeps that off the build.
• Naming. The N64Recomp developers asked a third party to stop using their name in a launcher. EB
  should call these "native ports" and credit each upstream by its own name; do not brand anything
  "N64Recomp".
• Defender. Every port is an unsigned exe downloaded from GitHub and will hit the same
  Bearfoos.A!ml-class ML heuristic that took EB's own build this week. Expect it; surface it as a
  message rather than a silent failure.

[cubman3134]

Update: the launcher the maintainer meant is RetComM, and its catalog should replace ours

The maintainer clarified they meant the launcher that builds recomps locally, per system: RetComM Launcher ("Retro Compilation Manager"), C++ + SDL3/ImGui, with a CLI (retcomm list | catalog update | scan | install <title> | launch <title>), MIT. Its catalog lives in retcomm-catalog as a GitHub Release asset (catalog.zip → index.json + titles/<id>.json).

What was verified

• Catalog today: 15 titles, all PlayStation (Tomba, FF7, Legend of Mana, SFA3, MvC, Metal Slug X, Klonoa, Twisted Metal 4, MK4, …). generate.engine enum is snesrecomp | psxrecomp | gbarecomp — there is no N64 engine.
• The schema is better than the one Native ports: play N64 recompilations (Zelda64Recomp etc.) as one-game standalone launchers #233 proposed and should be adopted instead of invented: rom_identity{crc32,md5,sha1,sha256,disc_serials,sizes,track_counts,require_cue,discs}, bios_identity{…}, release.github, launch{windows,linux,macos}, install_dir_name, saves, build{enabled,source.github,source.ref,toolchain.id,generate.engine,cmake.*}, netplay, romm. It already encodes exactly the game-identity binding this issue needs, with hashes HashVerify can check.
• "Build from the ground up" is real only where a generic recompiler exists — PSX, SNES, GBA. N64Recomp is explicitly not that: it requires a per-game ELF with symbols plus a hand-written TOML, i.e. a decompilation project behind it; graphics/audio come from a separate runtime. It is a port-developer tool. So N64 can only ever be "download the ~14 finished ports" — which is what increment 1 already does.
• Local builds need a native toolchain (MSVC/MinGW or clang, CMake, Ninja, Python; psxrecomp bundles no portable pack). This machine has cmake but no cl, ninja or clang on PATH. End users overwhelmingly have none of it. This is a developer-machine feature and must be presented as opt-in with toolchain detection, never the default.
• Licensing: psxrecomp is PolyForm Noncommercial 1.0.0; RetComM is MIT. EB (GPLv3) can invoke either as an external process exactly as it invokes standalone emulators; it must not bundle or link psxrecomp. RetComM's stated rationale for local builds — "shipping pre-generated recomp C from commercial ROMs is a legal grey area" — applies to EB equally: never distribute generated sources.

Revised plan

• Increment 1 (running): unchanged in scope, but the catalog file adopts retcomm-catalog's per-title schema so a later increment can consume the real feed directly.
• Increment 2: consume retcomm-catalog's published catalog.zip as a second catalog source (N64 ports stay in EB's own file since that catalog has none), and gate "Native port" on rom_identity via HashVerify where the user has a DAT or the entry carries hashes.
• Increment 3 (opt-in, toolchain-gated): "Build locally" — drive RetComM's CLI (install/launch) or psxrecomp directly as an external process with EB's existing long-process shape (DiscCompose off-thread + cancel is the precedent), surfacing the queue and progress. Only offered when a toolchain is detected; PSX/SNES/GBA only.

[cubman3134]

Increment 1 done (PR #235, merging once its main-conflict resolution gates green)

Majora's Mask reached gameplay through Zelda64Recomp v1.2.2, live, twice — from the game's row, verb present on Majora's Mask and absent on Ocarina beside it, install of the real release asset, launch, ROM supplied in the port's own menu, Clock Town. Defender did not flag the downloaded port (the card keeps its warning regardless).

The catalogue is written in RetComM's per-title schema (rom_identity, release.github, launch{windows,linux,macos}, install_dir_name, …) plus one documented extension of ours, rom_delivery, since their schema does not say how a port takes its ROM. build is omitted from N64 entries — there is no N64 recompiler.

A real build bug was found and fixed on the way: resources/ports.qrc in qt_add_executable's initial source list produced no rcc output, so the exe shipped without the catalogue and the verb appeared on nothing. Explicit qt_add_resources now, and probe_ports byte-compares the embedded resource against the source so it cannot recur silently.

What remains

• Increment 2: consume retcomm-catalog's published catalog.zip as a second source; gate the verb on rom_identity via HashVerify.
• cli_path delivery is blocked on A standalone emulator's argsTemplate cannot express a literal argument containing a space #237 — the launch template cannot carry a literal argument with a space.
• Two verb surfaces the romhack verb has are not yet wired: the themed detail ActionRow and the classic detail button (the three named surfaces are).
• install_dir_name is carried but not honoured (installs land under emulators/<id>/); allow_prerelease only covers prerelease-only repos, not "prefer a newer prerelease".
• Increment 3 (opt-in, toolchain-gated): build locally via RetComM's CLI as an external process — PSX/SNES/GBA only; psxrecomp is PolyForm Noncommercial, so invoke, never bundle.

[cubman3134]

#237 is fixed on main (cae150b): an args template can now carry a quoted literal argument with a space, so the cli_path delivery mode is unblocked for increment 2.

[cubman3134]

The remaining increments here (RetComM feed + HashVerify gating, cli_path delivery, install_dir_name, allow_prerelease) are absorbed by #248, which adds the Recomps section under Games and the self-compile tier. This issue stays the record of the pre-built tier and closes when those land under #248.