gen1recomp

# Gen1Recomp A native LÖVE2D recreation of Poke Red, Blue, Gold, Silver, and Crystal. The engine and map behavior are hand-written Lua; game data and graphics are decoded from a ROM supplied by the player. And before you say, "that's not a recomp", you're wrong. Recomp is an acronym. ***Reverse Engineering Causes Obsessive Mental Problems*** [Click Here for the AI Use Disclosure!](AIDisclosure.md) > [!CAUTION] > **We are NOT affiliated with the website `gen1recomp[.]com`** That website is not run by this project, was not authorized by us, and we have no idea who operates it. It is impersonating this project; do not download anything from it, and treat anything it hosts or claims as untrustworthy. Even if the site currently links back to this repository, the people behind it can change its content at any time, so nothing on it should ever be trusted. This GitHub repository, the Discord, and https://gen1re.com are the only official sources for this project. Also, as I assumed would eventually happen, the idiot that made that website now pumped it full of adware. Please stay away from that website.

# [SUPPORT / ANNOUNCEMENTS / MODS ALL FOUND ON THE DISCORD](https://bois.icu)

### Watch the latest update video This project does not include a ROM, emulate the Game Boy, transpile assembly, or download a disassembly. A canonical US Poke Red, Blue, Yellow, Gold, Silver, or Crystal 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. Red, Blue, Yellow, Gold, Silver, and Crystal can all be imported side by side. Gold, Silver, and Crystal are Gen 2 Phase 1 (import + launcher; see `docs/gold-phase1.md`): the Gen 2 engine is still under construction. ## 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 and the game starts automatically. Only the canonical US Red, Blue, Yellow (1 MiB), Gold, Silver, and Crystal (2 MiB) ROMs are accepted. The importer verifies SHA-1 before creating any game data: - Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a` - Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2` - Yellow: `cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1` - Gold: `d8b8a3600a465308c9953dfa04f0081c05bdcb94` - Silver: `49b163f7e57702bc939d642a18f591de55d92dae` - Crystal (1.0): `f4cd194bdee0d04ca4eac29e09b8e4e9d818c133` - Crystal (1.1): `f2f52230b536214ef7c9924f483392993e226cfb` 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 the Windows build with a generic machine-learning detection such as `Trojan:Win32/Wacatac!ml` (#621). 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. Every release publishes SHA-256 checksums (`sha256sums.txt`) so you can verify your download, and you can confirm a flagged file yourself on [VirusTotal](https://www.virustotal.com), where these builds come back clean on every engine except Defender's heuristic. False positives are reported to Microsoft as they come up. ## 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) | | `1` | Cycle GAME SPEED up (controller: R2 faster, L2 slower) | | `2` | Cycle COLORS | | `3` | Cycle TILT (free-roam overworld) | | `4` | Cycle ZOOM through every level (free-roam overworld) | | `F1` | Save | | `F2` | Load | | `F10` | Open / close the mod manager | COLORS, TILT, ZOOM, SHADER FX, GAME SPEED, 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), **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 preferences without forgetting them. Details in [docs/new-features.md](docs/new-features.md#performance-tier-low-end-devices). ### Rulesets **OPTIONS → RULESET** picks which set of Gen 1 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. `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 | ## Online play The launcher has an **ONLINE** tab. Connect once and you get a lobby of who else is around, with what game and what rules: host a battle or join one, watch any live match or tournament as a spectator, run a bracket where everyone not playing watches the match that is on, or trade Pokemon between save files, yours or someone else's. Picking a battle opens the game straight into it, no intro and no overworld, and drops you back in the tab when it ends. Every room names exactly what it runs, so both sides are on the same engine, the same version and the same ruleset: vanilla, or a sealed custom cart that both players have installed. The in-game LINK menu is still there and is still local network only. ## Running From Source Requires LÖVE 11.x. Place a Red, Blue, or Yellow ROM in the project folder and double-click `Play-Mac.command` or `Play-Windows.bat`, or run: ```sh scripts/setup.sh --rom "/path/to/Poke Red.gb" # or Blue.gb / Yellow.gbc scripts/run.sh ``` then `love .` for later launches. Windows PowerShell scripts, the optional developer data build, test suites, and cache management are covered in [Developer Setup](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Developer-Setup). ## 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 `gen1recomp.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. ## Launch Options By default the app opens the launcher so you can pick a game. Launch options skip it and start one game directly, which is what you want for a one-click entry: a desktop shortcut per game, a Steam entry, or a handheld frontend. | Option | Effect | | --- | --- | | `--game=red` | boot Red, skipping the launcher (`blue`, `yellow`, `gold`, `silver` and `crystal` too, or just `r` / `b` / `y` / `g` / `s` / `c`) | | `--cart=id` | boot the installed custom cart with that id | | `--slot=2` | load that save slot; takes a slot number or a slot id | | `--launcher` | open the launcher anyway, so you can edit a shortcut you already made | | `--no-sync` | skip the save sync a linked device otherwise runs before the game boots (`POKEPORT_LAUNCH_SYNC=0`) | | `--update` | check for a release first, and restart once into it if one is ready (`POKEPORT_LAUNCH_UPDATE=1`; `-update` works too) | If this device is linked for save sync, a shortcut now syncs before it boots so CONTINUE never loads a save another device has already moved past. The screen shows what it is doing and any button skips straight into the game; a sync conflict opens