BoktaiRecomp — Boktai: The Sun Is in Your Hand, Recompiled

Static recompilation of Boktai: The Sun Is in Your Hand (Game Boy Advance) to native PC, built on the gbarecomp framework.

Boktai's cartridge carried a photodiode: the Gun del Sol charged from real sunlight, and the undead could only be sealed while you had light. That sensor is emulated here and driven by the actual weather where you are — a clear afternoon fills the gauge, a rainy night leaves you fighting in the dark.

Status — playable, early, self-improving

A static-recompilation base + runner, not a finished port. It boots through the real recompiled BIOS into gameplay, saves to EEPROM, and the solar sensor works end to end.

Coverage is not yet fully static. Uncovered code paths run through the interpreter on first hit, then JIT to native and cache to disk, so the game gets faster the more you play. Open items: ISSUES.md.

---

What "static recompilation" means here

The ROM's ARM7TDMI machine code is statically translated to native C — every function the game runs becomes a real generated C function. As across the gbarecomp ecosystem, the GBA BIOS is recompiled and executed too (never HLE'd or stubbed), so boot, IRQ and SWI handling run as real recompiled code. The PPU, APU, DMA, timers, the EEPROM save chip, the S-3511A RTC and the solar sensor are modeled by the runtime.

The ROM is never redistributed. You supply your own legally-dumped copy, and the runner refuses to launch on anything else.

ROM

Target	Game	Region	SHA-1	Debug port
BoktaiRecomp	Boktai: The Sun Is in Your Hand	USA	7164326283df46a3941ec7b6ceca889cbc40e660	19893

Save chip: EEPROM (8 KB). Cartridge extras: S-3511A RTC and the solar sensor, sharing four GPIO pins.

Use a clean dump. Many Boktai ROMs in circulation are intro-patched or sensor-patched, and a sensor patch removes the very hardware reads this project emulates. See baserom.md.

Quick start

git clone --recurse-submodules https://github.com/Shy/BoktaiRecomp.git

1. Supply a GBA BIOS dump and your own ROM — baserom.md.
2. Recompile and build — docs/BUILDING.md.
3. Run it. The launcher opens first: pick your ROM, set your postal code under Settings → Solar sensor, press PLAY.

Prebuilt binaries are not distributed: a recompiled binary embeds translated ROM code, so everyone builds their own. Packaging scripts for macOS, Windows and Steam Deck are in docs/PACKAGING.md.

The solar sensor

Three light sources, in precedence order:

Source	How
Hotkey override	SolarBrighter / SolarDimmer step a manual level; SolarLive releases it. Unbound by default — bind them in the launcher's Hotkeys panel.
Live weather	Postal code → coordinates → current irradiance. Set it in the launcher, or in the in-game menu (Esc).
Nothing configured	The sensor reads dark. No network request is ever made.

Live weather uses global horizontal irradiance (W/m²) — the power a flat upward-facing surface actually receives — mapped onto the gauge's measured response:

Irradiance	Conditions	Gauge
0	night	empty
50–150	heavy overcast	1–3 bars
200–400	light overcast, low sun	4–6 bars
800–1000	clear midday	full

Full sun is adjustable, because clear-sky midday is ~900 W/m² at mid latitudes but much less in winter or at high latitude — a fixed 900 would mean the gauge could never fill on a genuinely sunny day.

Privacy. Nothing leaves the machine unless you set a postal code. When you do, that code goes to api.zippopotam.us to resolve coordinates, and those coordinates go to api.open-meteo.com for the current reading. No account, no API key, nothing else sent. Polling is every 10 minutes, never per frame. Details: docs/SOLAR-SENSOR.md.

Controls

Defaults match the launcher's rebind page, so the two never disagree:

GBA	Keyboard
A / B	X / Z
L / R	C / V
Start / Select	Return / Right Shift
D-pad	Arrow keys

Function	Key
In-game settings menu	Esc
Load / save state (slots 1–9)	F1–F9 / Shift+F1–F9
Fullscreen	Alt+Return
Turbo	Tab

All rebindable — inputs on the launcher's Controls page, hotkeys in its Hotkeys panel. Both write the same keybinds.ini / config.ini the runtime reads.

Layout

Path	What
variants/boktai1_usa/game.toml	ROM identity, save chip, video/audio policy
variants/boktai1_usa/symbols/	recompiler input: entry seeds, data ranges, code copies
variants/boktai1_usa/generated/	translated C — gitignored, regenerate locally
src/solar_weather.*	postal code → coordinates → irradiance → sensor brightness
src/game_ui.*	this game's section of the in-game settings menu
tools/	ROM hash verifier, release packaging
packaging/flatpak/	Steam Deck build

The variants/ layout follows EmeraldRecomp so the JP release and the Boktai sequels can drop in as sibling directories.

Upstream

Bringing this game up produced fixes that belonged in the framework rather than here — PPU bitmap modes 3/4/5, a shared GPIO port so a cart can carry more than one device, save-chip override, the solar sensor itself, game-owned in-game menu items, and self-healing on non-Windows hosts. All merged. See docs/UPSTREAM.md.

License

PolyForm Noncommercial 1.0.0, matching gbarecomp.