mirror of
https://github.com/bryanthaboi/gen1recomp.git
synced 2026-08-12 08:21:02 +02:00
bryanthaboi
144 lines
4.7 KiB
Markdown
144 lines
4.7 KiB
Markdown
# Pokemon Gen 1 Recompilation Project
|
|
|
|
A native LÖVE2D recreation of Pokemon Red. The engine and map behavior are
|
|
hand-written Lua; game data and graphics are decoded from a ROM supplied by
|
|
the player.
|
|
|
|
SUPPORT AND ANNOUNCEMENTS: [Discord](https://bois.icu)
|
|
|
|
This project does not include a ROM, emulate the Game Boy, transpile assembly,
|
|
or download a disassembly. A canonical US Pokemon Red ROM is the only game
|
|
content input.
|
|
|
|
```text
|
|
first boot
|
|
Pokemon Red ROM -> in-app Lua importer -> private LÖVE save directory
|
|
-> generated Lua data and PNGs
|
|
-> compact audio channel programs
|
|
-> LÖVE2D engine
|
|
```
|
|
|
|
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.
|
|
|
|
## Packaged App
|
|
|
|
Open the desktop app. On first boot, choose your legally obtained `.gb` file
|
|
or drop it onto the window. Import takes a few seconds and the game starts
|
|
automatically.
|
|
|
|
Only the canonical 1 MiB US Red ROM is accepted. The importer verifies SHA-1
|
|
`ea9bcae617fdf159b045185467ae58b2e4a48b9a` before creating any game data.
|
|
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 Game Boy audio channel programs copied out of the verified ROM. No
|
|
WAV or OGG library is bundled or generated.
|
|
|
|
## Source Checkout
|
|
|
|
The source launchers retain an optional Python workflow for developers. Place
|
|
the 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
|
|
```
|
|
|
|
Windows PowerShell:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1 -Rom C:\path\red.gb
|
|
powershell -ExecutionPolicy Bypass -File scripts\run.ps1
|
|
```
|
|
|
|
The setup scripts also accept `ROM_PATH`. With no argument, they use the first
|
|
`.gb` file in the project root.
|
|
|
|
## Developer Data Build
|
|
|
|
Requirements: Python 3.10+ and Pillow.
|
|
|
|
```sh
|
|
python3 -m pip install pillow
|
|
python3 tools/build_data.py --rom "/path/to/Pokemon Red.gb" --clean
|
|
```
|
|
|
|
This command produces the data modules and 495 PNGs in the source tree for
|
|
development and parity checks. It is not used by the packaged app.
|
|
|
|
## Running
|
|
|
|
Requires LÖVE 11.x:
|
|
|
|
```sh
|
|
love .
|
|
```
|
|
|
|
Controls: arrow keys or WASD move; Z, Enter, or Space is A; X or Backspace is
|
|
B; Escape opens START. F1 saves and F2 loads. Controllers are supported.
|
|
|
|
## Link Play
|
|
|
|
START > LINK connects two copies directly over UDP. The host chooses HOST A
|
|
GAME and shares the shown address; the other player chooses JOIN A GAME.
|
|
The default port is 7777 and can be overridden with `POKEPORT_LINK_PORT`.
|
|
|
|
## Save Editor
|
|
|
|
Edit party, boxes, items, events, map location, and Pokédex flags without
|
|
playing through the game. Close the game first, then from the repo root:
|
|
|
|
```sh
|
|
love . --editor
|
|
# or
|
|
POKEPORT_EDITOR=1 love .
|
|
# open a specific save
|
|
love . --editor --save "/path/to/save.lua"
|
|
```
|
|
|
|
By default it loads the game's LÖVE save (`save.lua`):
|
|
|
|
- macOS: `~/Library/Application Support/LOVE/pokemon-love2d/save.lua (or without the LOVE in a built version)`
|
|
- Linux: `~/.local/share/love/pokemon-love2d/save.lua`
|
|
- Windows: `%APPDATA%\love\pokemon-love2d\save.lua`
|
|
|
|
If that file is missing or you want another copy, use **Open...**, drop a
|
|
`save.lua` onto the window, or pass `--save`. Each write makes a
|
|
`save.lua.bak-YYYYMMDD-HHMMSS` backup first.
|
|
|
|
See `tools/save-editor/README.md` for headless tests.
|
|
|
|
## Layout
|
|
|
|
```text
|
|
tools/ ROM decoder, save editor, and developer verification tools
|
|
data/generated/ generated Lua game data (gitignored)
|
|
data/scripts/ hand-ported map behavior
|
|
assets/generated generated graphics and compact audio cache (gitignored)
|
|
src/ hand-written LÖVE engine
|
|
scripts/ setup, run, and packaging helpers
|
|
mobile/ Android and iOS build trees
|
|
tests/ headless behavior and parity suites
|
|
docs/ architecture, behavior notes, and platform docs
|
|
```
|
|
|
|
See `docs/architecture.md` for runtime details and
|
|
`docs/behavior-porting-notes.md` for formula provenance.
|
|
|
|
## Delete generated files (mac)
|
|
|
|
```sh
|
|
rm -rf data/generated assets/generated \
|
|
"$HOME/Library/Application Support/LOVE/pokemon-love2d/data/generated" \
|
|
"$HOME/Library/Application Support/LOVE/pokemon-love2d/assets/generated"
|
|
|
|
rm -f "$HOME/Library/Application Support/LOVE/pokemon-love2d/rom-cache.complete"
|
|
|
|
```
|
|
|
|
## Special Thanks
|
|
This project would not be possible without [pret](https://github.com/pret) > the pret band of decompiling maniacs > and their [pokered](https://github.com/pret/pokered) disassembly.
|