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

scripts/test.sh is the unified entry point: it runs every tier this checkout can run and exits non-zero if any fails. Tiers that need only the committed fixture dataset (tests/fixture_data/) run anywhere, including a ROM-less CI box; the content tier asserts real game facts and is skipped automatically until the ROM has been imported.

scripts/test.sh          # every tier this checkout can run
scripts/test.sh --quick  # skip the slow content tier

Single tiers (LUA=luajit is the default interpreter; the engine targets LuaJIT / Lua 5.1 semantics):

luajit tests/run_engine.lua            # engine invariants + parity gates (ROM-free)
luajit tests/run_modkit.lua            # mod SDK (ROM-free)
luajit tests/run_tests.lua             # content behavior; needs data/generated/
luajit tests/run_save_editor_tests.lua # save editor logic/panel tests
luajit tests/run_link_tests.lua        # link play loopback lockstep; needs data/generated/

The content suite must end with 0 FAILURES, the link suite with ALL LINK TESTS PASSED.

Deleting generated files (macOS)

Each imported game keeps its own cache under the LÖVE save directory: red/, blue/, yellow/, and gold/ each hold a data/generated/, an assets/generated/, and a rom-cache.complete marker.

rm -rf data/generated assets/generated
cd "$HOME/Library/Application Support/LOVE/pokemon-love2d"
rm -rf red blue yellow gold data/generated assets/generated rom-cache.complete

(The last three paths cover a pre-multi-game install's flat cache.) 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.

Packaging builds

scripts/build.sh [mac|win|linux|android|ios|all] packs game.love (engine, data, the save editor, and the ROM manifests; never */generated/) and fuses it onto each platform's LÖVE binary, writing distributables into dist/ (gen1recomp-macos.zip, -win64.zip, -linux.zip AppImage, the Android APK, the iOS app). --version X.Y.Z stamps the release version; code signing and notarization flags are documented in the script header. Per-platform wrappers (build_windows.ps1, build_switch.sh, build_xbox_uwp.sh, linux-arm64/build_appimage.sh) live beside it.

One Windows-specific asset: gen1tls.dll, the native TLS dialer that gives mods love.system.tlsOpen/tls* for wss:// connections. CI builds it (native/tls_dial/) and build.sh bundles it into the Windows zip from dist/native/win-x64/gen1tls.dll (or GEN1TLS_DLL). A local Windows package without it still runs; the build warns and wss:// stays unavailable.

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.

Home

Start here

Concepts

Tutorials

Reference

Guides

Playing

Engine 1.0.0 · mod API 2 · repository · Discord

This project ships no ROM data. All game content is decoded on the player's machine from their own verified Pokemon Red ROM; mods ship recipes and original assets, never extracted content.