mirror/gen1recomp
1
0
Fork 0
mirror of https://github.com/bryanthaboi/gen1recomp synced 2026-09-30 07:22:37 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs update

Browse Source
This commit is contained in:
bryanthaboi
2026-09-29 10:52:49 -04:00
parent 9fb3c529e7
commit febc6c6fd4
13 changed files with 391 additions and 347 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+67 -347
View File
@@ -1,4 +1,4 @@
# Gen1Recomp
# G1R Deluxe aka Gen1Recomp
A native LÖVE2D recreation of Poke Red, Blue, Yellow, Gold, Silver, Crystal, FireRed, and LeafGreen.
The engine and map behavior are hand-written Lua; game data and graphics are
@@ -53,37 +53,46 @@ And before you say, "that's not a recomp", you're wrong. Recomp is an acronym. *
### Watch the latest update video
[![Watch the latest update video](https://img.youtube.com/vi/0hgtLDNGpdo/maxresdefault.jpg)](https://youtu.be/0hgtLDNGpdo)
<a href="https://youtu.be/Q87iK8u_52o">
<img src="https://img.youtube.com/vi/Q87iK8u_52o/maxresdefault.jpg" width="320" alt="Watch the latest update video">
</a>
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, Crystal, FireRed, or LeafGreen 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. All eight supported games can 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.
## What this is
G1R Deluxe aka Gen1Recomp is a native LÖVE2D recreation of Pokemon Red, Blue, Yellow, Gold,
Silver, Crystal, FireRed, and LeafGreen. The engine and map behavior are
hand-written Lua, ported from the [pret](https://github.com/pret)
disassemblies & C. Game data, graphics, and audio programs are decoded on first
launch from a ROM you supply.
The project does not include a ROM, emulate the Game Boy, transpile assembly,
or download a disassembly. Your ROM is verified, used during import, and
released from memory. It is never copied into the cache, and later launches
load the private generated cache without asking for it again. Music, sound
effects, and cries are synthesized while the game runs. All eight games can be
imported side by side. Gen 2 support is still under construction.
## Quick Start
Open the desktop app. On first boot, choose your legally obtained `.gb` /
`.gbc` / `.gba` file or drop it onto the window. Import takes a few seconds and the
game starts automatically.
1. Download the build for your platform from the
[latest release](https://github.com/bryanthaboi/gen1recomp/releases/latest).
2. Launch it. The packaged app contains no ROM and no game data, so the
launcher will ask for one.
3. Choose your legally obtained `.gb` / `.gbc` / `.gba` file, or drop it onto
the window. Import takes a few seconds and the game starts automatically.
4. Repeat for any other game you own. Each one gets its own tab in the launcher.
### Supported games and ROM hashes
Only the canonical US English ROMs below are accepted. The importer verifies
Only the canonical US English ROMs below are accepted. The importer checks the
SHA-1 before creating any game data. FireRed and LeafGreen support is in beta.
| Game | Revision | ROM size | SHA-1 |
| --- | --- | --- | --- |
| Red | — | 1 MiB | `ea9bcae617fdf159b045185467ae58b2e4a48b9a` |
| Blue | — | 1 MiB | `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2` |
| Yellow | — | 1 MiB | `cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1` |
| Gold | — | 2 MiB | `d8b8a3600a465308c9953dfa04f0081c05bdcb94` |
| Silver | — | 2 MiB | `49b163f7e57702bc939d642a18f591de55d92dae` |
| Red | - | 1 MiB | `ea9bcae617fdf159b045185467ae58b2e4a48b9a` |
| Blue | - | 1 MiB | `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2` |
| Yellow | - | 1 MiB | `cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1` |
| Gold | - | 2 MiB | `d8b8a3600a465308c9953dfa04f0081c05bdcb94` |
| Silver | - | 2 MiB | `49b163f7e57702bc939d642a18f591de55d92dae` |
| Crystal | 1.0 | 2 MiB | `f4cd194bdee0d04ca4eac29e09b8e4e9d818c133` |
| Crystal | 1.1 | 2 MiB | `f2f52230b536214ef7c9924f483392993e226cfb` |
| FireRed | 1.0 | 16 MiB | `41cb23d8dccc8ebd7c649cd8fbb58eeace6e2fdc` |
@@ -91,26 +100,20 @@ SHA-1 before creating any game data. FireRed and LeafGreen support is in beta.
| LeafGreen | 1.0 | 16 MiB | `574fa542ffebb14be69902d1d36f1ec0a4afd71e` |
| LeafGreen | 1.1 | 16 MiB | `7862c67bdecbe21d1d69ce082ce34327e1c6ed5e` |
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.
**Platform notes:** [Linux](docs/platforms/linux.md),
[iOS](docs/platforms/ios.md), [Xbox Dev Mode](docs/platforms/xbox.md),
[handhelds](docs/platforms/handhelds.md), and
[Nintendo Switch](docs/platforms/switch.md) each have their own install steps.
### 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.
**Windows Defender:** it sometimes flags the Windows build with a generic
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,
and Defender distrusts unsigned executables with appended data. Every release
publishes `sha256sums.txt` so you can verify your download, and you can check
a flagged file on [VirusTotal](https://www.virustotal.com).
## Controls
| Action | Keyboard | Controller |
| ------ | ----------------- | ------------------ |
| Move | Arrow keys / WASD | D-pad / left stick |
@@ -119,315 +122,40 @@ Microsoft as they come up.
| Start | Escape | Start |
| Select | Tab / Shift | Back / Select |
Rebind any of these in-game under **OPTIONS > CONTROLS**.
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) |
| 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 |
| `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
**Low-end devices:** **OPTIONS > PERFORMANCE** scales the optional extras for
weaker hardware (HIGH, BALANCED, LOW, or AUTO, the default). It only changes
presentation; game logic is identical on every tier. Details in
[docs/new-features.md](docs/new-features.md#performance-tier-low-end-devices).
### Rulesets
## Documentation
**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.
Everything else lives in the [docs folder](docs/README.md) or on the
[project wiki](https://github.com/bryanthaboi/gen1recomp/wiki), which has the
modding book, link play, save editor, and developer setup guides:
`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.
- The kept-ROM copy (`roms/`), import inboxes (`imports/`), `baseroms/`,
`shaders/`, `prints/`, touch skins, and the shader error log also live in
that folder. The auto-update payload cache (`updates/`) stays in the OS save
directory on purpose, as does the temporary shader download archive.
- If `portable.txt` is present but rejected (folder not writable, or the
folder cannot be mounted), the launcher log says why and cache writes fail
with a message instead of silently landing in the OS save directory.
- 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) |
| `--update-mods` | run the MODS tab's Update all (mods and custom carts) without the confirm, then boot; stays on the launcher if an update fails (`POKEPORT_LAUNCH_UPDATE_MODS=1`; `--updatemods` 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 the launcher so you can pick a copy rather than booting
over one.
Android and iOS also accept the same launch request as a URL:
```text
gen1recomp++://launch?game=red
```
The URL parameters correspond to the desktop options:
| URL | Effect |
| --- | --- |
| `gen1recomp++://launch?game=red` | boot Red directly |
| `gen1recomp++://launch?game=red&cart=my_cart` | boot the installed custom cart `my_cart` |
| `gen1recomp++://launch?game=red&slot=2` | boot Red and select save slot 2 |
| `gen1recomp++://launch?game=red&launcher=1` | open the launcher on Red instead |
| `gen1recomp++://launch?game=red&sync=0` | skip save sync |
| `gen1recomp++://launch?game=red&update=1` | check for an update before booting |
| `gen1recomp++://launch?game=red&update_mods=1` | update mods and carts before booting |
The `game` value accepts the same full names and aliases as `--game`. Boolean
parameters accept `1`/`0`, `true`/`false`, `yes`/`no`, and `on`/`off`. Percent-encode
values that contain characters reserved by URLs; the app decodes query values
before applying them. `cart` is the installed cart id shown in the Custom Carts
screen. Unknown parameters are ignored, and an invalid game or cart falls back
to the launcher.
To test a link on Android, use the installed application package:
```bash
adb shell am start -a android.intent.action.VIEW \
-d 'gen1recomp++://launch?game=red' \
com.theboisclub.pokemonred
```
To test a link in the iOS Simulator:
```bash
xcrun simctl openurl booted 'gen1recomp++://launch?game=red'
```
On a physical iPhone or iPad, open the URL from another app that can hand off
custom URLs, such as Notes, Messages, or Safari.
## Linux desktop (AppImage / Flatpak)
Releases ship raw AppImages (no zip wrapper) plus an optional Flatpak bundle:
- `gen1recomp-*-linux-x86_64.AppImage`
- `gen1recomp-*-linux-arm64.AppImage` (Raspberry Pi 4/5, Armbian, arm64 VMs)
- `gen1recomp-*-linux.flatpak` (see [docs/linux-flatpak.md](docs/linux-flatpak.md))
```sh
chmod +x gen1recomp-*-linux-x86_64.AppImage
./gen1recomp-*-linux-x86_64.AppImage
```
```sh
chmod +x gen1recomp-*-linux-arm64.AppImage
./gen1recomp-*-linux-arm64.AppImage
```
Shared troubleshooting (FUSE, curl, portable mode): [docs/linux-appimage.md](docs/linux-appimage.md).
LÖVE publishes no aarch64 binary of any kind, so the arm64 artifact compiles the
engine — and SDL2, OpenAL and the codecs — from source inside a Debian
bullseye arm64 container. It needs only glibc 2.29+, libstdc++, freetype and
zlib on the host; OpenGL, X11, Wayland, KMSDRM, ALSA and PulseAudio are all
dlopened, so the same image runs on a full desktop, a Wayland-only session or
a KMSDRM handheld with no X server. Build instructions and the reasoning are
in [docs/linux-arm64-build.md](docs/linux-arm64-build.md).
## iOS
Every release ships `gen1recomp++-*-ios.ipa`. Sideload it with AltStore
(Windows or Mac) — see [docs/ios-sideload.md](docs/ios-sideload.md). To
build and install from source on a Mac instead, see
[docs/ios-install.md](docs/ios-install.md).
On iOS, long-press an imported game cartridge in the launcher and choose the
Home Screen action. For custom carts, open Custom Carts and use Home Screen on
the cart row you want. iOS opens a configuration profile in Safari; approve it
from Settings when prompted. The generated entry keeps the game's or cart's
artwork and launches through the same `gen1recomp++://launch` URL format.
<div>
<a href="https://intradeus.github.io/http-protocol-redirector?r=sidestore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/sidestore-badge.png" alt="Add to SideStore" height="60"></a>
&nbsp;
<a href="https://intradeus.github.io/http-protocol-redirector?r=feather://source/https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/feather-badge.png" alt="Add to Feather" height="60"></a>
&nbsp;
<a href="https://intradeus.github.io/http-protocol-redirector?r=altstore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/altstore-badge.png" alt="Add to AltStore" height="60"></a>
&nbsp;
<a href="https://github.com/bryanthaboi/gen1recomp/releases/latest"><img src="./.github/resources/github-badge.png" alt="Download from GitHub" height="60"></a>
</div>
## Xbox Dev Mode
Every release ships `gen1recomp-*-xbox-uwp.zip` for Xbox One and Xbox Series
consoles in Developer Mode. It cannot be installed in retail mode.
Extract the archive, then use Xbox Device Portal to install the `.msix` and
the x64 package under `Dependencies`.
### External setup
1. Put your legally obtained Red, Blue, or Yellow ROMs on an external drive.
Mod ZIPs can go on the same drive.
2. Connect the drive to the Xbox and open Gen1Recomp.
3. Select **Import ROM** or **Import Mod**, then choose the file with the Xbox
file picker.
4. Repeat the ROM import for each version you want to use.
### Internal setup
1. Create a folder named `baseroms` on your PC and place your legally obtained
Red, Blue, or Yellow ROMs inside it.
2. ZIP the folder, keeping `baseroms` at the top level of the archive.
3. Launch Gen1Recomp once, then close it.
4. Open Xbox Device Portal and upload the ZIP to
`Gen1Recomp/LocalState/pokemon-love2d/`.
5. Choose **Yes** when Device Portal asks whether to extract the archive.
6. Open Gen1Recomp. The launcher checks baseroms once at startup. When it finds a compatible ROM, that game’s tab shows ROM FOUND and an Import detected ROM button.
ROMs, generated game data, saves, and mods remain in LocalState and are not
included in the app.
Source builds and package details are covered in
[the Xbox UWP build notes](ports/uwp/BUILD.md).
## Handhelds
A PortMaster-style port for the **Anbernic RG34XXSP** on Stock OS 64-bit MOD
ships with every release as `gen1recomp-*-rg34xxsp-stockos64-mod.zip`.
Install steps, controls, and troubleshooting live in
[docs/anbernic-rg34xxsp.md](docs/anbernic-rg34xxsp.md).
## Nintendo Switch
Releases ship an SD-ready `gen1recomp-*-switch.zip`. Runtime target is pinned
[love-nx](https://github.com/retronx-team/love-nx) `11.5-nx1`. Requires a
console that can run Switch homebrew.
- Players: [docs/switch-install.md](docs/switch-install.md). Download the
zip, extract at the microSD root (install or update), title-override
launch, import your own legal ROM, Joy-Con controls and shortcuts.
- Builders: [docs/switch-build.md](docs/switch-build.md). `--fetch` /
`--loose` / `--fused`, toolchain, Docker fallback, and CI vs release
(path-gated ubuntu selftest, fused PR artifact on the main repo, release
hard-fail).
- File transfer (MTP / SD / FTP): [docs/switch-transfer.md](docs/switch-transfer.md).
## Modding
The game ships a native mod platform: content registries, events and hooks,
per-mod saves and options, and an in-game manager. The full modding book —
getting started, a twelve-rung tutorial ladder, a cookbook, and the generated
reference — lives on the
[project wiki](https://github.com/bryanthaboi/gen1recomp/wiki).
Shipped example mods, one per kind of author, live in `[mods/](mods/)`.
Maps can be edited in our own build of [Tiled](https://www.mapeditor.org),
[bryanthaboi/tiled_gen1recomp](https://github.com/bryanthaboi/tiled_gen1recomp/releases),
and exported back out as a mod; see
[docs/tiled-map-editing.md](docs/tiled-map-editing.md).
- [Rulesets](docs/guides/rulesets.md): faithful Gen 1 quirks or modern cleanups
- [Online play](docs/guides/online-play.md): lobby, battles, tournaments, trading
- [Launch options](docs/guides/launch-options.md): one-click shortcuts and URLs
- [Portable mode](docs/guides/portable-mode.md): run from a USB drive
- [Running from source](docs/guides/running-from-source.md)
- [Modding](docs/modding-overview.md): mod platform, example mods, Tiled map editing
- [Architecture](docs/architecture.md)
## Bugs
@@ -438,17 +166,9 @@ original game.
Attach a screenshot if you can. It saves a lot of back and forth, and if you
can't get one, the form asks you to describe what you saw instead.
## More
- [Link play](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Link-Play)
— START > LINK connects two copies directly over UDP.
- [Save editor](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Save-Editor)
— edit party, boxes, items, events, and Pokédex flags outside the game.
- `docs/architecture.md` — runtime details;
`docs/behavior-porting-notes.md` — formula provenance;
`docs/link-security.md` — what link play defends against, and what it doesn't.
## License
See [LICENSE.MD](LICENSE.MD).
## Special Thanks
docs/README.md
+31
View File
@@ -0,0 +1,31 @@
# Documentation
These docs cover the port itself. Guides for modding, link play, the save
editor, and developer setup live on the
[project wiki](https://github.com/bryanthaboi/gen1recomp/wiki).
## Guides
- [Rulesets](guides/rulesets.md): gen1_faithful vs modern_clean battle rules
- [Online play](guides/online-play.md): lobby, battles, tournaments, trading
- [Launch options](guides/launch-options.md): CLI flags and `gen1recomp++://` URLs
- [Portable mode](guides/portable-mode.md): keep saves and cache next to the game
- [Running from source](guides/running-from-source.md)
- [New features](new-features.md): what this port adds over the originals
## Platforms
- [Linux (AppImage / Flatpak)](platforms/linux.md)
- [iOS](platforms/ios.md)
- [Xbox Dev Mode](platforms/xbox.md)
- [Handhelds](platforms/handhelds.md)
- [Nintendo Switch](platforms/switch.md)
## Modding
- [Modding overview](modding-overview.md)
## Internals
- [Architecture](architecture.md)
- [Link security](link-security.md)
docs/guides/launch-options.md
+63
View File
@@ -0,0 +1,63 @@
# 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) |
| `--update-mods` | run the MODS tab's Update all (mods and custom carts) without the confirm, then boot; stays on the launcher if an update fails (`POKEPORT_LAUNCH_UPDATE_MODS=1`; `--updatemods` works too) |
If this device is linked for save sync, a shortcut 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 the launcher so you can pick a copy rather than booting over
one.
## URL launch (Android and iOS)
Android and iOS accept the same launch request as a URL:
```text
gen1recomp++://launch?game=red
```
| URL | Effect |
| --- | --- |
| `gen1recomp++://launch?game=red` | boot Red directly |
| `gen1recomp++://launch?game=red&cart=my_cart` | boot the installed custom cart `my_cart` |
| `gen1recomp++://launch?game=red&slot=2` | boot Red and select save slot 2 |
| `gen1recomp++://launch?game=red&launcher=1` | open the launcher on Red instead |
| `gen1recomp++://launch?game=red&sync=0` | skip save sync |
| `gen1recomp++://launch?game=red&update=1` | check for an update before booting |
| `gen1recomp++://launch?game=red&update_mods=1` | update mods and carts before booting |
The `game` value accepts the same full names and aliases as `--game`. Boolean
parameters accept `1`/`0`, `true`/`false`, `yes`/`no`, and `on`/`off`.
Percent-encode values that contain characters reserved by URLs; the app
decodes query values before applying them. `cart` is the installed cart id
shown in the Custom Carts screen. Unknown parameters are ignored, and an
invalid game or cart falls back to the launcher.
To test a link on Android, use the installed application package:
```sh
adb shell am start -a android.intent.action.VIEW \
-d 'gen1recomp++://launch?game=red' \
com.theboisclub.pokemonred
```
To test a link in the iOS Simulator:
```sh
xcrun simctl openurl booted 'gen1recomp++://launch?game=red'
```
On a physical iPhone or iPad, open the URL from another app that can hand off
custom URLs, such as Notes, Messages, or Safari.
docs/guides/online-play.md
+22
View File
@@ -0,0 +1,22 @@
# 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.
- 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 local network only.
## More
- [Link play guide](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Link-Play): START > LINK connects two copies directly over UDP.
- [Link security](../link-security.md): what link play defends against, and what it doesn't.
- [Rulesets](rulesets.md)
docs/guides/portable-mode.md
+32
View File
@@ -0,0 +1,32 @@
# 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. Portable mode keeps
everything next to the game instead, which is handy for a USB stick or
portable drive you carry between computers.
To turn it on, 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.
- The kept-ROM copy (`roms/`), import inboxes (`imports/`), `baseroms/`,
`shaders/`, `prints/`, touch skins, and the shader error log also live in
that folder. The auto-update payload cache (`updates/`) stays in the OS save
directory on purpose, as does the temporary shader download archive.
- If `portable.txt` is present but rejected (folder not writable, or the
folder cannot be mounted), the launcher log says why and cache writes fail
with a message instead of silently landing in the OS save directory.
- 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.
docs/guides/rulesets.md
+34
View File
@@ -0,0 +1,34 @@
# 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
The default. 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 |
docs/guides/running-from-source.md
+16
View File
@@ -0,0 +1,16 @@
# Running from source
Requires LÖVE 11.x. Place a ROM in the project folder and double-click
`Play-Mac.command` or `Play-Windows.bat`, or run:
```sh
scripts/setup.sh --rom "/path/to/Pokemon Red.gb"
scripts/run.sh
```
then `love .` for later launches.
Windows PowerShell scripts, the optional developer data build, test suites,
and cache management are covered in the
[Developer Setup guide](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Developer-Setup).
Runtime internals are in [architecture.md](../architecture.md).
docs/modding-overview.md
+16
View File
@@ -0,0 +1,16 @@
# Modding overview
The game ships a native mod platform: content registries, events and hooks,
per-mod saves and options, and an in-game manager (F10). The full modding
book (getting started, a twelve-rung tutorial ladder, a cookbook, and the
generated reference) lives on the
[project wiki](https://github.com/bryanthaboi/gen1recomp/wiki).
- Shipped example mods, one per kind of author: [mods/](../mods/)
- In-repo SDK docs: [modding.md](modding.md), [CONTRIBUTING-mods.md](../CONTRIBUTING-mods.md)
- Map editing: maps can be edited in our own build of
[Tiled](https://www.mapeditor.org),
[bryanthaboi/tiled_gen1recomp](https://github.com/bryanthaboi/tiled_gen1recomp/releases),
and exported back out as a mod; see [tiled-map-editing.md](tiled-map-editing.md).
- Other tools: [Save editor](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Save-Editor)
edits party, boxes, items, events, and Pokedex flags outside the game.
docs/platforms/handhelds.md
+9
View File
@@ -0,0 +1,9 @@
# Handhelds
A PortMaster-style port for the **Anbernic RG34XXSP** on Stock OS 64-bit MOD
ships with every release as `gen1recomp-*-rg34xxsp-stockos64-mod.zip`.
Install steps, controls, and troubleshooting live in
[anbernic-rg34xxsp.md](../anbernic-rg34xxsp.md).
Other ARM Linux handhelds and single-board computers:
[linux-arm-sbc.md](../linux-arm-sbc.md).
docs/platforms/ios.md
+24
View File
@@ -0,0 +1,24 @@
# iOS
Every release ships `gen1recomp++-*-ios.ipa`. Sideload it with AltStore,
SideStore, or Feather using the badges below. To build and install from source
on a Mac instead, see [ios-install.md](../ios-install.md).
<div>
<a href="https://intradeus.github.io/http-protocol-redirector?r=sidestore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="../../.github/resources/sidestore-badge.png" alt="Add to SideStore" height="60"></a>
&nbsp;
<a href="https://intradeus.github.io/http-protocol-redirector?r=feather://source/https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="../../.github/resources/feather-badge.png" alt="Add to Feather" height="60"></a>
&nbsp;
<a href="https://intradeus.github.io/http-protocol-redirector?r=altstore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="../../.github/resources/altstore-badge.png" alt="Add to AltStore" height="60"></a>
&nbsp;
<a href="https://github.com/bryanthaboi/gen1recomp/releases/latest"><img src="../../.github/resources/github-badge.png" alt="Download from GitHub" height="60"></a>
</div>
## Home Screen shortcuts
Long-press an imported game cartridge in the launcher and choose the Home
Screen action. For custom carts, open Custom Carts and use Home Screen on the
cart row you want. iOS opens a configuration profile in Safari; approve it
from Settings when prompted. The generated entry keeps the game's or cart's
artwork and launches through the same `gen1recomp++://launch` URL format; see
[launch options](../guides/launch-options.md).
docs/platforms/linux.md
+29
View File
@@ -0,0 +1,29 @@
# Linux desktop (AppImage / Flatpak)
Releases ship raw AppImages (no zip wrapper) plus an optional Flatpak bundle:
- `gen1recomp-*-linux-x86_64.AppImage`
- `gen1recomp-*-linux-arm64.AppImage` (Raspberry Pi 4/5, Armbian, arm64 VMs)
- `gen1recomp-*-linux.flatpak` (see [linux-flatpak.md](../linux-flatpak.md))
```sh
chmod +x gen1recomp-*-linux-x86_64.AppImage
./gen1recomp-*-linux-x86_64.AppImage
```
```sh
chmod +x gen1recomp-*-linux-arm64.AppImage
./gen1recomp-*-linux-arm64.AppImage
```
Shared troubleshooting (FUSE, curl, portable mode):
[linux-appimage.md](../linux-appimage.md).
LÖVE publishes no aarch64 binary of any kind, so the arm64 artifact compiles
the engine, and SDL2, OpenAL and the codecs, from source inside a Debian
bullseye arm64 container. It needs only glibc 2.29+, libstdc++, freetype and
zlib on the host; OpenGL, X11, Wayland, KMSDRM, ALSA and PulseAudio are all
dlopened, so the same image runs on a full desktop, a Wayland-only session or
a KMSDRM handheld with no X server. Build instructions and the reasoning are
in [linux-arm64-build.md](../linux-arm64-build.md). Other ARM boards:
[linux-arm-sbc.md](../linux-arm-sbc.md).
docs/platforms/switch.md
+13
View File
@@ -0,0 +1,13 @@
# Nintendo Switch
Releases ship an SD-ready `gen1recomp-*-switch.zip`. Runtime target is pinned
[love-nx](https://github.com/retronx-team/love-nx) `11.5-nx1`. Requires a
console that can run Switch homebrew.
- Players: [switch-install.md](../switch-install.md). Download the zip,
extract at the microSD root (install or update), title-override launch,
import your own legal ROM, Joy-Con controls and shortcuts.
- Builders: [switch-build.md](../switch-build.md). `--fetch` / `--loose` /
`--fused`, toolchain, Docker fallback, and CI vs release (path-gated ubuntu
selftest, fused PR artifact on the main repo, release hard-fail).
- File transfer (MTP / SD / FTP): [switch-transfer.md](../switch-transfer.md).
docs/platforms/xbox.md
+35
View File
@@ -0,0 +1,35 @@
# Xbox Dev Mode
Every release ships `gen1recomp-*-xbox-uwp.zip` for Xbox One and Xbox Series
consoles in Developer Mode. It cannot be installed in retail mode.
Extract the archive, then use Xbox Device Portal to install the `.msix` and
the x64 package under `Dependencies`.
## External setup
1. Put your legally obtained ROMs on an external drive. Mod ZIPs can go on the
same drive.
2. Connect the drive to the Xbox and open Gen1Recomp.
3. Select **Import ROM** or **Import Mod**, then choose the file with the Xbox
file picker.
4. Repeat the ROM import for each version you want to use.
## Internal setup
1. Create a folder named `baseroms` on your PC and place your legally obtained
ROMs inside it.
2. ZIP the folder, keeping `baseroms` at the top level of the archive.
3. Launch Gen1Recomp once, then close it.
4. Open Xbox Device Portal and upload the ZIP to
`Gen1Recomp/LocalState/pokemon-love2d/`.
5. Choose **Yes** when Device Portal asks whether to extract the archive.
6. Open Gen1Recomp. The launcher checks baseroms once at startup. When it
finds a compatible ROM, that game's tab shows ROM FOUND and an Import
detected ROM button.
ROMs, generated game data, saves, and mods remain in LocalState and are not
included in the app.
Source builds and package details are in the
[Xbox UWP build notes](../../ports/uwp/BUILD.md).