prompt-to-romhack

Prompt to Romhack

Use this plugin when a user asks for a playable Pokemon Red, Blue, or Yellow romhack, dialogue/data/map edits, build verification, emulator smoke testing, or a browser preview.

Workspace Bootstrap

Do not assume the pokered or pokeyellow disassembly is already present. Start by cloning the requested base repo or fork into the workspace, then install this plugin's helper tooling into that clone.

From the plugin root:

node scripts/prompt-to-romhack.mjs setup --game red --dir ./pokered
node scripts/prompt-to-romhack.mjs setup --game yellow --dir ./pokeyellow

For a fork or branch:

node scripts/prompt-to-romhack.mjs setup --game red --repo https://github.com/owner/pokered.git --branch my-branch --dir ./my-hack

Defaults:

• red and blue clone https://github.com/pret/pokered.git.
• yellow clones https://github.com/pret/pokeyellow.git.
• RGBDS is vendored under the plugin root and recorded in .prompt-to-romhack/config.json inside the cloned workspace.
• The plugin copies helper scripts, preview assets, smoke-test code, and docs into the workspace. It does not include or redistribute the pret disassembly.

If the repo already exists, install or refresh only the helper layer:

node /path/to/prompt-to-romhack/scripts/prompt-to-romhack.mjs install-tools --workspace .
node /path/to/prompt-to-romhack/scripts/prompt-to-romhack.mjs vendor-rgbds --workspace .

First Checks

Inside the cloned disassembly workspace, run:

node scripts/prompt_to_romhack.mjs doctor

If tools are present, use the helper instead of calling the emulator manually:

node scripts/prompt_to_romhack.mjs preview --rom red --allow-missing-logo
node scripts/prompt_to_romhack.mjs preview --rom yellow --allow-missing-logo

Use --allow-missing-logo only for a first mechanical check. For a real hack preview, generate or choose a distinctive non-official title logo under web/romhack-preview/assets/ and pass it with --logo.

For early runtime confidence without opening the browser:

node scripts/prompt_to_romhack.mjs smoke --rom red --path early-game
node scripts/prompt_to_romhack.mjs headless --rom red --path pallet-town
node scripts/prompt_to_romhack.mjs headless --rom yellow --path boot

Red/Blue currently have the strongest smoke-path coverage. For Yellow, begin with boot, main-menu, build, and browser preview unless you have validated a longer path in that checkout.

Edit Loop

1. Locate the narrow data or script surface for the prompt with rg.
2. Make focused edits in the disassembly; avoid generated .gbc, .map, .sym, .o, .1bpp, .2bpp, and .pic outputs.
3. Build with node scripts/prompt_to_romhack.mjs build --rom red, --rom blue, or --rom yellow.
4. For vanilla scaffolding, expect the SHA-1 to match roms.sha1. For real hacks, expect the SHA-1 to differ.
5. When the change touches title/menu/intro/map-load/early-overworld behavior in Red/Blue, run node scripts/prompt_to_romhack.mjs smoke --rom red --path early-game --no-build --expect-map REDS_HOUSE_2F --expect-coord 3,7.
6. When the change affects Red's house, Pallet Town, warps, or movement in Red/Blue, also run node scripts/prompt_to_romhack.mjs headless --rom red --path pallet-town --no-build --expect-map PALLET_TOWN --expect-coord 5,6.
7. Generate or choose a distinctive non-official preview title logo before browser preview, saving the final PNG under web/romhack-preview/assets/. Avoid official logo lettering, ball emblems, character art, or mascots.
8. Start or reuse node scripts/prompt_to_romhack.mjs preview --rom red --no-build --title "Hack Title" --logo /web/romhack-preview/assets/hack-title-logo.png --romhack-id hack-title. The helper fails before serving the webpage when no preview logo is present; use --allow-missing-logo only for mechanical tests where visual review is not needed.
9. Open the printed local URL in the local browser when visual or human review matters.

Keep --romhack-id stable for a single playthrough so SRAM persists across rebuilds and page reloads.

Live Preview Tools

While the preview is open, use the local rendezvous API through:

node scripts/prompt_to_romhack.mjs live session
node scripts/prompt_to_romhack.mjs live status
node scripts/prompt_to_romhack.mjs live read wCurMap,wXCoord,wYCoord
node scripts/prompt_to_romhack.mjs live write wEnemyMonHP=0,1
node scripts/prompt_to_romhack.mjs live press a --frames 8
node scripts/prompt_to_romhack.mjs live screenshot --out artifacts/live/preview.png
node scripts/prompt_to_romhack.mjs live refresh-map
node scripts/prompt_to_romhack.mjs live apply-rom-diff

Before any godmode/state edit, read the live RAM state instead of relying on the last screenshot or previous route. At minimum check live status and live read wCurMap,wXCoord,wYCoord,wIsInBattle.

Documentation

After setup, the cloned workspace receives:

• docs/prompt-to-romhack.md for the high-level prompt-to-ROM loop.
• docs/romhack/edit-surfaces.md for where common data lives.
• docs/romhack/game-logic.md for battle and formula work.
• docs/romhack/scripts-and-dialogue.md for scripts, text, and cutscenes.
• docs/romhack/headless-emulator-testing.md for smoke-test design.
• docs/romhack/live-patching.md for live preview and ROM-diff iteration.
• docs/romhack/emulator-only-limits.md for emulator-targeted hack boundaries.

Use the docs as orientation, then verify against the actual checkout because forks can drift.

Verification Stance

For every prompted hack, at minimum report whether the ROM builds. When the change affects early gameplay, run a relevant headless smoke path before browser review. When browser testing is requested or visual/human review matters, use the preview URL and verify the title screen/new game path or the changed area. Keep notes about behavior that was not play-tested.