# Game Boy port (`/play/gameboy`)

A Game Boy / Game Boy Color emulator compiled to WebAssembly, driven by a small TypeScript loader
(`app/play/gameboy/GameBoyPort.tsx`). Nothing here loads until the player presses Play.

## Engine: binjgb

- Upstream: https://github.com/binji/binjgb
- Commit: `16621111ed0ee73bcc45c912a823bcebedcffc0f` (2026-09-25)
- Licence: MIT, Copyright (c) 2016 Ben Smith. See `licenses/binjgb-LICENSE.txt`.
- Files: `binjgb.js` (emscripten glue, `MODULARIZE` factory named `Binjgb`) and `binjgb.wasm`,
  copied unmodified from that commit's `docs/` directory (the prebuilt emscripten build upstream ships for its demo).

### What was written here

The upstream demo (`docs/simple.js`) was not used. The loader in `GameBoyPort.tsx` calls binjgb's exported C API directly:
`emulator_new_simple`, `emulator_run_until_f64` with a ticks-per-frame budget (4194304 Hz × rAF delta, capped at 5 frames),
`get_frame_buffer_ptr` → a 160×144 canvas scaled with `image-rendering: pixelated`, `get_audio_buffer_ptr` → WebAudio,
`set_joyp_*` from keyboard / gamepad / touch, and `ext_ram_file_data_new` + `emulator_read_ext_ram` / `emulator_write_ext_ram`
for battery saves, which are kept in `localStorage` under `gameboy:sram:<rom>` (base64), written at most once a second and on pause.

### Rebuilding the engine

```
git clone https://github.com/binji/binjgb && cd binjgb && git checkout 16621111ed0ee73bcc45c912a823bcebedcffc0f
# with emsdk activated:
ln -s $PATH_TO_EMSCRIPTEN emscripten && make wasm   # upstream README, "Building WebAssembly"
```

Or copy `docs/binjgb.js` and `docs/binjgb.wasm` from that commit, as was done here.

## ROMs (`roms/`)

All three are open-source homebrew whose licences allow redistribution.

| File | Game | Author | Source | Licence |
| --- | --- | --- | --- | --- |
| `tobu.gb` | Tobu Tobu Girl | Tangram Games | Binary from the gbdev Homebrew Hub database, commit `16230d7bbc923e4738d3531524709d42c727ef95`, `entries/tobutobugirl/tobu.gb`. Source: https://github.com/SimonLarsen/tobutobugirl (`048a22c2d7ebbe25811322e8692803fa86bb643a`). | Code MIT (`licenses/tobutobugirl-LICENSE.txt`); assets (graphics, text, sound, music) CC BY 4.0, https://creativecommons.org/licenses/by/4.0/ |
| `ucity.gbc` | µCity v1.3 | Antonio Niño Díaz (AntonioND) | https://github.com/AntonioND/ucity/releases/download/v1.3/ucity.gbc. Source: https://github.com/AntonioND/ucity (tag v1.3; also https://codeberg.org/SkyLyrac/ucity). | GPL-3.0-or-later (`licenses/ucity-gpl-3.0.txt`); GBT Player BSD-2-Clause; media CC BY-SA 4.0. Complete source is at the links above. |
| `adjustris.gb` | Adjustris v1.00 | Dave VanEe (tbsp) | gbdev Homebrew Hub database, same commit, `entries/adjustris/adjustris.gb`. Source: https://github.com/tbsp/Adjustris (`d899e2f539c07ac49fd42c055605bf778a2df09d`). | CC0 1.0 (`licenses/adjustris-LICENSE.md`) |

SHA-1: tobu.gb `8a8f3c1f21f903ea5a7df8fc8b0a6aa5a602e150`, ucity.gbc `5f026649611c9606ce0bf70dc1552e054e7df5bc`,
adjustris.gb `61c0d3ab874786110b152e4ae183961bcf760744`. None were modified.

## Controls

Arrows = D-pad, X = A, Z = B, Enter = Start, Shift / Backspace = Select.
Gamepad: D-pad / left stick, A = A, B = B, Start, Back = Select. Touch devices get on-screen buttons.