Guide Developer Setup

Developer setup

Running from a source checkout, the optional developer data build, the test suites, and cache management. Players using the packaged app need none of this — see the repository README for the two-minute start.

Source checkout

Requires LÖVE 11.x. Place your legally obtained US Red ROM in the project folder and double-click Play-Mac.command or Play-Windows.bat, or run:

scripts/setup.sh --rom "/path/to/Pokemon Red.gb"
scripts/run.sh

Windows 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. After setup:

love .

Controls: arrow keys or WASD move; Z, Enter, or Space is A; X or Backspace is B; Escape opens START. F1 saves, F2 loads, F10 toggles the mod manager. Controllers are supported.

Dev mode

Run with POKEPORT_DEV=1 for the mod-development loop: F5 hot-reloads mod content, the backtick opens the dev console, and undeclared engine requires from mods log attributed warnings (Getting Started).

Developer data build

The in-app importer is all a player needs. For development and parity checks there is an optional Python build that produces the data modules and 495 PNGs in the source tree:

python3 -m pip install pillow
python3 tools/build_data.py --rom "/path/to/Pokemon Red.gb" --clean

Requirements: Python 3.10+ and Pillow. The packaged app does not use this path.

Test suites

luajit tests/run_tests.lua              # engine + parity + mod API suites
luajit tests/run_link_tests.lua         # link play
luajit tests/run_save_editor_tests.lua  # save editor

The first must end with 0 FAILURES, the second with ALL LINK TESTS PASSED. Tests run under LuaJIT (Lua 5.1 semantics) with no ROM required — mod suites use the fixture dataset in tests/fixture_data/.

Deleting generated files (macOS)

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"

The next launch re-imports from the ROM. On Linux and Windows the cache lives under the LÖVE save directory listed in Save Editor.

Layout

tools/           ROM decoder, save editor, modkit, 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
mods/            native mods (the example ships here)

docs/architecture.md covers runtime details; docs/behavior-porting-notes.md carries formula provenance per pokered source file.