diff --git a/README.md b/README.md index ae860fea..68bca5b1 100644 --- a/README.md +++ b/README.md @@ -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) + + 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, 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. - -
- Add to SideStore -   - Add to Feather -   - Add to AltStore -   - Download from GitHub -
- -## 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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..b8a49b2d --- /dev/null +++ b/docs/README.md @@ -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) diff --git a/docs/guides/launch-options.md b/docs/guides/launch-options.md new file mode 100644 index 00000000..007b8235 --- /dev/null +++ b/docs/guides/launch-options.md @@ -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. diff --git a/docs/guides/online-play.md b/docs/guides/online-play.md new file mode 100644 index 00000000..b44622ff --- /dev/null +++ b/docs/guides/online-play.md @@ -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) diff --git a/docs/guides/portable-mode.md b/docs/guides/portable-mode.md new file mode 100644 index 00000000..69de17ca --- /dev/null +++ b/docs/guides/portable-mode.md @@ -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. diff --git a/docs/guides/rulesets.md b/docs/guides/rulesets.md new file mode 100644 index 00000000..dd3b751a --- /dev/null +++ b/docs/guides/rulesets.md @@ -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 | diff --git a/docs/guides/running-from-source.md b/docs/guides/running-from-source.md new file mode 100644 index 00000000..b0159b39 --- /dev/null +++ b/docs/guides/running-from-source.md @@ -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). diff --git a/docs/modding-overview.md b/docs/modding-overview.md new file mode 100644 index 00000000..502caff2 --- /dev/null +++ b/docs/modding-overview.md @@ -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. diff --git a/docs/platforms/handhelds.md b/docs/platforms/handhelds.md new file mode 100644 index 00000000..d9f2c0b7 --- /dev/null +++ b/docs/platforms/handhelds.md @@ -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). diff --git a/docs/platforms/ios.md b/docs/platforms/ios.md new file mode 100644 index 00000000..16df02af --- /dev/null +++ b/docs/platforms/ios.md @@ -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). + +
+ Add to SideStore +   + Add to Feather +   + Add to AltStore +   + Download from GitHub +
+ +## 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). diff --git a/docs/platforms/linux.md b/docs/platforms/linux.md new file mode 100644 index 00000000..49d26d04 --- /dev/null +++ b/docs/platforms/linux.md @@ -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). diff --git a/docs/platforms/switch.md b/docs/platforms/switch.md new file mode 100644 index 00000000..f383209e --- /dev/null +++ b/docs/platforms/switch.md @@ -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). diff --git a/docs/platforms/xbox.md b/docs/platforms/xbox.md new file mode 100644 index 00000000..0fc85551 --- /dev/null +++ b/docs/platforms/xbox.md @@ -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).