# Additional NumPlay games

This imports the 31 standalone games missing from NumGames, plus a catalog entry
for Retro-Go. Existing NumGames ports and their published releases are preserved.
The full upstream inventory is pinned in `upstream.json`; `source.json` records
the commit, archive checksum, version and imported IDs. English and French copy
is authored in `copy.json`. `app-names.json` records the actual ELF app names for
recognition and account-gated relinking after installation. `prepare.py` generates the marked catalog blocks,
`026_numplay_games.sql` and the upload manifest. Do not edit those outputs by hand.

## Source and licenses

Upstream: <https://github.com/Mason363/NumPlay/tree/19f358c571944d5b853bc3dee648cf8346a8531e>.
Download the complete source, including its original licenses, fonts, artwork,
asset generators and build scripts:

<https://github.com/Mason363/NumPlay/archive/19f358c571944d5b853bc3dee648cf8346a8531e.tar.gz>

The code is GPL-3.0, with third-party code retaining the licenses in the upstream
game directories and `LICENSES/`. Names, artwork and music retain their upstream
attributions and are not relicensed by the code license. Original credits remain
in the games. The site links each game's pinned source and credits.

Our game changes are `branding.patch` (include and call the Num Games startup
card, and track that header in the Makefile) and the generated
`numgames_brand.h` from `games/common/`. The generated header uses the Handjet
font under `brand/fonts/OFL.txt` (also published here as `Handjet-OFL.txt`). These
changes were made on 2026-10-23. No gameplay, save or rendering code was changed.
`automatic-install.patch` also marks Box2D's coordinate vector constructor
`constexpr`: the constant zero vector is initialized at compile time, avoiding a
C++ `.init_array` section the browser linker deliberately rejects. The vector's
values and runtime constructor behavior are unchanged.
The website publishes these changes and instructions at `/sources/numplay/`.

To rebuild independently, extract the pinned source, apply `patch -p1 < branding.patch`
at its root, apply `patch -p1 < automatic-install.patch`, copy `numgames_brand.h`
into `games/common/`, then run `make -C games/<id>
build check`. Requirements: GNU Arm Embedded GCC, GNU Make, Python 3 and
`nwlink@1.0.0` (set `NWLINK` to its executable or let the Makefiles use npx).
The initial builds used xPack GCC 15.2.1-1.1 for macOS arm64 and nwlink 1.0.0.

## NumGames preparation

From the NumGames checkout, with that toolchain on PATH:

```sh
# Inspect source.json and verify the downloaded archive's SHA-256 first.
NWLINK=/path/to/nwlink python3 games/numplay-import/prepare.py \
  --source /path/to/extracted/NumPlay --build --write
python3 games/numplay-import/prepare.py
node db/numgames/tools/prepare-builds.mjs --committed
```

The first command applies the patch, copies the branding header, builds and
installer-link-checks each standalone app, copies its real artwork and `.nwa`,
then generates catalog text, translations, SQL and manifest. Check-only mode
uses committed files, with no network or compiler requirement.

All new model statuses remain **untested**. A successful compiler/linker check
does not mean a game was played on hardware. Playability and save behavior still
need real-device tests. Retro-Go has no fixed file or file size: its catalog
button sends an onboarded user to NumPlay Studio to build with their own ROMs.
No ROMs are imported or distributed.

NumVisuals is a clock/background utility, not a game. Super Mario 64 and Super
Mario Bros. are links to separate repositories in the upstream README, not games
in this repository's inventory. They are not part of this import.

## Production handoff

No remote SQL, upload or deployment is performed by preparation. Before applying
`db/numgames/026_numplay_games.sql` remotely, show that exact file and obtain an
explicit yes. It inserts only NumGames catalog/release/build/support rows in
`numgames`, and does not touch `public` or `auth`. Register it through the existing
NumGames migration workflow. Apply it after the preceding migrations.

Then use the existing `db/numgames/tools/upload-builds.mjs` dry run and authorized
upload to the private `numgames-builds` bucket, and deploy the site through the
normal authorized workflow. Keep the account/onboarding gate and bucket private.
Do not regenerate or reapply the historical `011_builds.sql` for these games.