gen2recomp

Gen2Recomp Discord!

by UNDERdecodedHD
a fork of Gen1Recomp by bryanthaboi and BOIS CLUB GAMES

A native LÖVE2D recreation of Poke Gold, Silver and Crystal, built on Gen1Recomp's Red/Blue/Yellow engine. The engine, script VM, and map behavior are hand-written Lua; game data and graphics are decoded from a ROM supplied by the player.

gen2recomp keeps everything the upstream project does for Generation I and adds the Generation II half: the Gen2 script VM and its command table, the Johto and Kanto world, day/night, breeding and the Day-Care, the Pokegear, shinies, held items, and the Gold/Silver title sequence.

Caution

Neither this project nor Gen1Recomp is affiliated with the website gen1recomp[.]com. That site is not run by either project and was not authorized by anyone involved. Do not download anything from it, and treat anything it hosts or claims as untrustworthy. Even if it links back to a real repository, the people behind it can change its content at any time. This GitHub repository is the only official source for gen2recomp.

This project does not include a ROM, emulate the Game Boy, transpile assembly, or download a disassembly. A canonical US Poke Gold, Silver, Red, Blue, or Yellow ROM is the only game content input.

The ROM is verified, used during import, and then released from memory. It is not copied into the cache. Later launches load the private generated cache and do not ask for the ROM again. Every version can be imported and played side by side.

Quick Start

Open the desktop app. On first boot, choose your legally obtained .gb / .gbc file or drop it onto the window. Import takes a few seconds for Gen 1 and a couple of minutes for Gen 2, then the game starts automatically.

On a console or handheld there is no file picker to open: you copy the dump into a folder the launcher scans instead. See Downloads for the exact path per device.

Only the canonical US ROMs are accepted. The importer verifies SHA-1 before creating any game data:

Version	Size	SHA-1
Gold	2 MiB	d8b8a3600a465308c9953dfa04f0081c05bdcb94
Silver	2 MiB	49b163f7e57702bc939d642a18f591de55d92dae
Crystal (Rev 1)	2 MiB	f2f52230b536214ef7c9924f483392993e226cfb
Crystal (Rev 0)	2 MiB	f4cd194bdee0d04ca4eac29e09b8e4e9d818c133
Red	1 MiB	ea9bcae617fdf159b045185467ae58b2e4a48b9a
Blue	1 MiB	d7037c83e1ae5b39bde3c30787637ba1d4c48ce2
Yellow	1 MiB	cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1

The packaged app contains neither a ROM nor pre-extracted game data. Music, sound effects, and cries are synthesized while the game runs from compact audio channel programs copied out of the verified ROM.

A note on Windows Defender warnings

Windows Defender sometimes flags LÖVE builds with a generic machine-learning detection such as Trojan:Win32/Wacatac!ml. This is a known false positive: the exe is the official LÖVE runtime with the game archive appended (the standard way LÖVE games ship), and Defender's heuristics distrust unsigned executables with appended data. Releases publish SHA-256 checksums (sha256sums.txt) so you can verify your download, and you can confirm a flagged file yourself on VirusTotal, where these builds come back clean on every engine except Defender's heuristic.

Downloads — which file do I want?

Every release publishes one archive per platform, all built from the same payload in the same run. Grab the row that matches your device.

Device	File	Then
Windows	Gen2Recomped-<ver>-windows.zip	Unzip, run the .exe
Windows (Store-style install)	Gen2Recomped-<ver>-windows.msix + the .cer	See MSIX below — the .cer is required
macOS	Gen2Recomped-<ver>-macos.zip	Unzip, drag to Applications
Linux (x86-64)	Gen2Recomped-<ver>-linux.zip	Unzip, run the AppImage inside
Linux (ARM64 / Raspberry Pi / SBC)	Gen2Recomped-<ver>-linux-arm64.AppImage	chmod +x, run it
Steam Deck	Gen2Recomped-<ver>-linux.zip	The x86-64 one — the Deck is x86
Android	Gen2Recomped-<ver>-android.apk	Allow unknown sources, install
Nintendo Switch	Gen2Recomped-<ver>-switch.zip	See Switch below
Xbox (Dev Mode)	Gen2Recomped-<ver>-xbox-uwp.zip	See Xbox below
Anbernic RG34XXSP	Gen2Recomped-<ver>-rg34xxsp-stockos64-mod.zip	See Handhelds below
iOS	Gen2Recomped-<ver>-ios.ipa	Sideload — see iOS below
Already have LÖVE 11.5	Gen2Recomped-<ver>.love	love Gen2Recomped-<ver>.love

sha256sums.txt covers every asset in the release. The .love is also what the in-app updater downloads, so it is the smallest file if you are updating by hand.

No download contains a ROM or any game data. Every platform asks for your own cartridge dump on first launch.

Some assets are missing from a release only when that platform's build job failed; the release notes say so explicitly rather than silently omitting it.

Windows (MSIX)

Download both the .msix and the .cer. Windows refuses to install a package it cannot verify, and the certificate is what makes it verifiable. Once per machine, in an elevated PowerShell:

Import-Certificate -FilePath .\Gen2Recomped-<ver>-windows.cer `
  -CertStoreLocation Cert:\LocalMachine\TrustedPeople

Add-AppxPackage .\Gen2Recomped-<ver>-windows.msix

LocalMachine, not CurrentUser — App Installer only reads the machine store, and a certificate in the user store produces error 0x800B010A, which looks exactly like having imported nothing. Later releases then install with just Add-AppxPackage. Details and the signing setup are in docs/msix-signing.md.

If you would rather not deal with certificates at all, take the plain -windows.zip instead — it is the same game.

Nintendo Switch

Needs a homebrew-capable console (Atmosphère + hbmenu). Extract Gen2Recomped-<ver>-switch.zip at the root of your microSD, merging folders when asked. You get:

switch/gen2recomp/gen2recomp.nro          the launcher
switch/gen2recomp/Gen2Recomp/imports/     put your cartridge dump here
switch/gen2recomp/Gen2Recomp/exports/     battery saves come back out here

Then:

1. Copy a legal .gb / .gbc into switch/gen2recomp/Gen2Recomp/imports/. Dumps are matched by SHA-1, so the filename does not matter.
2. Launch through hbmenu with a title override (hold R on HOME and open any installed game).
3. Press Import in the launcher — it scans that folder.

Launcher controls: left stick or D-pad moves the pointer, A clicks, L/R change tabs, +/− play or import on the current tab.

Updating: re-extract the zip and keep the Gen2Recomp/ folder — that is where your saves, imported ROMs, mods and options live. The bundled OTA launcher can also fetch new releases from the console itself.

Xbox (Dev Mode)

Needs Developer Mode on the console — a retail Xbox cannot install this. Gen2Recomped-<ver>-xbox-uwp.zip is a UWP app package; upload it through the Xbox Device Portal in your browser, or Add-AppxPackage it from a paired PC. Build notes are in ports/uwp/BUILD.md.

Handhelds

Gen2Recomped-<ver>-rg34xxsp-stockos64-mod.zip targets the Anbernic RG34XXSP on Stock OS 64-bit MOD with PortMaster, and bundles its own LÖVE runtime, so no separate runtime download is needed. Unzip into the card's roms/PORTS/ folder so Gen2recomp.sh and gen2recomp/ sit side by side, drop your dump into gen2recomp/lovegame/, then launch it from Ports. Install steps, controls and troubleshooting are in docs/anbernic-rg34xxsp.md.

Other ARM64 handhelds and single-board computers can use the generic -linux-arm64.AppImage instead.

Android

Install the APK and pick your dump with the system file picker on first launch. If your device has no document picker, copy the .gb / .gbc into the app's own folder — the launcher shows the exact path. Build steps and the packaging layout are in mobile/ANDROID.md.

iOS

There is no App Store build; sideload the .ipa with AltStore from Windows or a Mac — see docs/ios-sideload.md. To build and install from source on a Mac, see docs/ios-install.md.

Updating

Desktop and mobile builds check GitHub Releases and can update themselves. Console builds tell you a release exists but will not replace themselves — a packaged console app cannot rewrite its own files — so update those the same way you installed them. The Switch is the exception: its OTA launcher replaces both NROs in place. See docs/updater.md.

Controls

Action	Keyboard	Controller
Move	Arrow keys / WASD	D-pad / left stick
A	Z / Enter / Space	A
B	X / Backspace	B
Start	Escape	Start
Select	Tab / Shift	Back / Select

Rebind any of these in-game under OPTIONS → CONTROLS. Controllers are supported out of the box.

Hotkeys

Key	What it does
- / =	Zoom out / in (overworld; also mouse wheel)
2	Cycle COLORS
3	Cycle TILT (free-roam overworld)
4	Cycle ZOOM through every level (free-roam overworld)
5	Cycle GBC FX
F1	Save
F2	Load
F10	Open / close the mod manager

COLORS, TILT, ZOOM, GBC FX, and VOID FILL are also in the Options menu and persist in options.lua.

Low-end devices

OPTIONS → PERFORMANCE scales the port's optional extras for weaker hardware: HIGH (everything on), BALANCED (no 3D tilt or GBC FX), LOW (also no survey zoom, FPS capped), or AUTO — the default, which picks a tier from your device (ARM handhelds → LOW, phones → BALANCED, normal desktops → HIGH, unchanged). It only scales presentation; the fixed-step game logic is identical on every tier, and a lower tier hides your tilt/zoom/GBC-FX preferences without forgetting them. Details in docs/new-features.md.

Rulesets

OPTIONS → RULESET picks which set of Generation I battle behaviors to run. Both rulesets share the same damage formulas; they differ only in whether the original's quirks are kept. The setting persists in options.lua, and mods can register their own. Gold and Silver always run their own Gen 2 rules.

gen1_faithful is the default and reproduces the original cartridge, famous bugs included:

Rule	Behavior
oneIn256Miss	A 100%-accurate move still misses on a roll of 255
critUsesBaseSpeed	Crit rate reads base speed, not the current stat
critIgnoresStages	Crit rate ignores stat stages
focusEnergyBug	FOCUS ENERGY quarters the crit rate instead of x4
enemyUnlimitedPP	Enemies never spend PP, so they never Struggle
hyperBeamSkipRechargeOnKO	HYPER BEAM skips its recharge when the target faints
randMin / randMax	Damage random factor 217-255

modern_clean keeps the formulas but removes the notorious quirks:

Rule	Behavior
oneIn256Miss	Off: a 100%-accurate move always hits
critUsesBaseSpeed	Unchanged: crit rate still reads base speed
critIgnoresStages	Off: stat stages count toward the crit rate
focusEnergyBug	Off: FOCUS ENERGY raises the crit rate as intended
enemyUnlimitedPP	Off: enemies deplete PP and Struggle when empty
hyperBeamSkipRechargeOnKO	Off: HYPER BEAM always recharges, like Gen 2+
randMin / randMax	Damage random factor 217-255, same as faithful

Running From Source

Requires LÖVE 11.x. Place a Gold or Silver ROM in the project folder and double-click Play-Mac.command or Play-Windows.bat, or run:

scripts/setup.sh --rom "/path/to/Poke Gold.gbc"   # or Silver.gbc / Red.gb / ...
scripts/run.sh

On Windows, scripts\setup.ps1 and scripts\run.ps1 do the same thing — see below. After the first import, love . is enough.

Windows

The easiest path is to double-click Play-Windows.bat. It runs scripts\bootstrap.ps1, which checks for the two things the port needs, offers to install whichever is missing through winget, imports your ROM, and starts the game. Later runs skip straight to launching.

To install the prerequisites yourself:

winget install --exact --id Python.Python.3.12
winget install --exact --id Love2d.Love2d

LÖVE can equally come from love2d.org — the scripts look for it on PATH and in the usual Program Files\LOVE locations. Python 3 must be on PATH; the setup script builds its own .venv for the importer's dependencies, so nothing is installed system-wide.

Then, from the project folder:

powershell -ExecutionPolicy Bypass -File scripts\setup.ps1 -Rom C:\path\to\Gold.gbc
powershell -ExecutionPolicy Bypass -File scripts\run.ps1

scripts\play.ps1 does both steps in one go. Drop the -Rom argument and setup picks up the first .gb / .gbc in the project folder. After the first import, love . is enough.

-ExecutionPolicy Bypass is what keeps PowerShell from refusing to run the scripts under its default policy; it applies only to that one invocation and changes nothing system-wide. run.ps1 prefers lovec.exe over love.exe when it can find it, because love.exe is a GUI-subsystem binary that swallows print output — worth knowing if you are debugging.

Saves, options, and the generated data cache live in %APPDATA%\LOVE\pokemon-love2d\ (Gold and Silver keep theirs in the gold\ and silver\ subfolders) unless you enable Portable Mode. Controllers work through SDL2 and need no driver setup. If Defender objects to a packaged build, see the note above.

Linux

scripts/setup.sh and scripts/run.sh are the Linux path too. They need LÖVE 11.x and Python 3 (with venv) on PATH; the setup script only auto-installs LÖVE on macOS, so install it first with your package manager:

# Debian / Ubuntu
sudo apt install love python3 python3-venv

# Fedora
sudo dnf install love python3

# Arch
sudo pacman -S love python

# Any distro (Flatpak)
flatpak install flathub org.love2d.love2d

Then, from the project folder:

chmod +x scripts/*.sh                              # first time only
scripts/setup.sh --rom "/path/to/Poke Gold.gbc"
scripts/run.sh

scripts/play.sh does both steps in one go. After the first import, love . is enough — or flatpak run org.love2d.love2d . if you installed the Flatpak. If you use the official AppImage from love2d.org, make it executable (chmod +x love-11.5-x86_64.AppImage) and either put it on PATH as love or run ./love-11.5-x86_64.AppImage . directly.

Saves, options, and the generated data cache live in ~/.local/share/love/pokemon-love2d/ (Gold and Silver keep theirs in the gold/ and silver/ subfolders) unless you enable Portable Mode. Controllers work through SDL2; if yours is not detected, check that your user is in the input group or that udev rules for the pad are installed. On Wayland with older LÖVE builds, launching with SDL_VIDEODRIVER=x11 through XWayland avoids most window and input quirks.

The Gen 2 importer reads the symbol files under tools/vendor/symbols/ (pokegold.sym / pokesilver.sym); scripts/setup_gen2_symbols.ps1 fetches them. The regression suite lives in tests/drivers/; each driver runs with POKEPORT_VERSION=gold POKEPORT_DRIVER=tests/drivers/<name>.lua love ..

Portable Mode

By default the game keeps your save, options, and the private ROM-derived data cache in your OS's normal per-user app data folder. To keep everything next to the game instead (handy for a USB stick or portable drive you carry between computers), drop an empty file named portable.txt next to the app (next to the .app/.exe, or next to main.lua/conf.lua when running from source), then launch the game. Portable mode is desktop-only (Windows, Linux, macOS); it has no effect on Android or iOS, where the app runs from a read-only package.

With portable.txt present:

• save.lua, save.lua.bak, and options.lua are read from and written to that same folder instead of the OS save directory.
• A ROM import writes the generated data/generated and assets/generated cache straight into that folder too (nothing is left in the OS save directory), so a later launch reuses it without asking for the ROM again even on a different computer, as long as the same folder comes along.
• Deleting portable.txt switches back to the normal OS save directory; nothing already written to either location is touched automatically, so copy files over yourself if you want to carry existing progress across the switch.

Modding

The game ships a native mod platform: content registries, events and hooks, per-mod saves and options, and an in-game manager. Start with docs/modding.md and CONTRIBUTING-mods.md.

Shipped example mods, one per kind of author, live in mods/ — including DRAMATIC_SHAPE, the voxel renderer, extended by UNDERdecodedHD for Generation II support.

Maps can be edited in Tiled and exported back out as a mod; see docs/tiled-map-editing.md.

Bugs and Ideas

Found a bug? A warp dropping you somewhere it shouldn't, a battle doing math that looks wrong, text in the wrong box, anything that does not match the original game — open an issue and attach a screenshot if you can. It saves a lot of back and forth, and if you can't get one, describe what you saw instead.

Same for features: say what you want, why it is worth doing, and how you picture it working. A request with real detail is one that can actually get built.

Docs

• docs/architecture.md — runtime details
• docs/gen2-migration-roadmap.md — what is done and what is left in the Gen 2 port
• docs/gen2-script-engine.md — the Gen 2 script VM
• docs/behavior-porting-notes.md — formula provenance
• docs/known-differences.md — where the port still diverges from the cartridge
• START > LINK connects two copies directly over UDP.

Credits

gen2recomp is by UNDERdecodedHD, forked from Gen1Recomp by bryanthaboi and BOIS CLUB GAMES, LLC. The Generation I engine, mod platform, renderer, and tooling are theirs; the Generation II import, script VM, world, and battle work are this fork's. See LICENSE.MD for the full copyright split.

Licence in one paragraph

Two parts. Everything inherited from Gen1Recomp, and every shared engine file since, stays MIT under its original authors' copyright — that is the default, and it is most of the repository. The Generation II components written for this fork are source-available rather than open source (© 2026 UNDERdecodedHD): read them, run them, change your own copy, and write and even sell mods against them — but don't redistribute or fork them. A file is only in that second group if it is named in the list in LICENSE; everything else is MIT.

Special Thanks

This project would not be possible without pret — the pret band of decompiling maniacs — and their pokered, pokegold, pokeyellow, and pokecrystal disassemblies.

The ADVANCED / "RED++" colour mode uses the SuperPalettes, per-species palette map, and true overworld GBC colouring from pokered-gbc by FroggestSpirit, Drenn, and Danny-E, baked into data/palettes_gbc.lua. Neither pokered-gbc nor the pret disassemblies ship a licence file, so the palette tables in data/ are reproduced with attribution rather than under this project's MIT grant, and will be removed on request from their authors.