Classroom Public page

Lab 4.1: Your First ROM Hack, Swap a Palette Color

1,013 words

~120 minutes. Find a palette byte in your ROM; change it; verify the color change in Mesen. Your first real modification of a game.

Goal: identify a single palette byte controlling one on-screen color; modify it; verify the change in Mesen; understand why this works.

Estimated time: 120 minutes

Prerequisites: lab 2.1, 2.2, 3.1 complete (you can read INES headers, find tiles, and recognize basic 6502)

Steps

Step 1: Copy your ROM (10 minutes)

Before you do ANYTHING else, make a copy of the original ROM. The course's mantra: never modify your original; always work on a copy.

cd ~/spk-101/roms/nes/
cp my-homebrew.nes ~/spk-101/working/my-homebrew-hack-1.nes

The original stays untouched at ~/spk-101/roms/nes/my-homebrew.nes. You hack the copy at ~/spk-101/working/my-homebrew-hack-1.nes.

Step 2: Find the current palette in Mesen (15 minutes)

Launch Mesen. Load your COPY (the hack file, not the original). Run it until you see colors you want to change. Pause (F3).

Open Tools → PPU Viewer. Click the "Palette" tab. You see eight palettes shown:

  • Background palettes (4 of them, indexed 0-3, each holding 4 colors)
  • Sprite palettes (4 of them, indexed 0-3, each holding 4 colors)

Each palette holds 4 colors. The first color in each palette is the "transparent" / background color (shared across all background palettes; transparent for sprites). The remaining 3 colors are foreground colors usable for tiles drawing under that palette.

Identify ONE specific color you want to change. Maybe the green of grass; the red of a player character; the yellow of a coin sprite.

Mesen typically lets you click a palette swatch and shows the NES color index for that swatch. NES colors are indexed 0x00 through 0x3F (64 colors total). Note the index for the color you want to change.

Write down: "I want to change the color at palette ___, slot ___ (the ___th color in the palette). It is currently NES color 0x__."

Step 3: Find where the palette lives in the ROM (30 minutes)

Palettes are typically stored as 16-byte (or smaller) chunks somewhere in PRG-ROM, and the game's startup code loads them into the PPU's palette RAM at $3F00-$3F1F.

Two strategies for finding the bytes:

Strategy A: search PRG-ROM for the byte sequence.

If you know the palette has, for instance, the byte sequence 0F 1A 2A 3A (background black + three greens), you can open the ROM in your hex editor and search for that exact byte sequence in PRG-ROM (anywhere after offset 0x4010 for a 16 KB PRG-ROM, or 0x8010 for 32 KB).

If you find exactly one match, that is almost certainly the palette. If you find multiple matches, you have to test each one or use Strategy B.

Strategy B: use Mesen's debugger to set a breakpoint on PPU palette writes.

Mesen's debugger lets you set a "PPU breakpoint" on writes to $3F00-$3F1F (palette RAM). When the game writes the palette at startup, the breakpoint fires; you see the PRG-ROM address that did the write; you find the source data table.

Strategy A is simpler; try it first. Strategy B is more powerful and worth knowing about.

Write down: "I found the palette at file offset 0x____."

Step 4: Change the byte (5 minutes)

In your hex editor, navigate to the palette byte you want to change. Note the original value (write it down, you might want to revert).

Change the byte to a new NES color index. The NESdev wiki has a color chart at https://www.nesdev.org/wiki/PPU_palettes#2C02. Pick something dramatically different from the original. (Light blue 0x21 → bright red 0x16 makes for a noticeable change.)

Save the file. Make sure you saved to working/my-homebrew-hack-1.nes, NOT to roms/nes/my-homebrew.nes.

Step 5: Reload in Mesen and verify (10 minutes)

In Mesen, File → Reload, OR File → Open ROM and re-pick your hack file. The game restarts.

Run it past startup. Check: did the color change?

  • If yes: take a screenshot. You completed your first ROM hack. Move to step 6
  • If no: the byte you changed was not the palette byte you thought. Re-check your work. Common causes: you edited a non-palette byte that happens to look like a palette; the game loads its palette dynamically (rare); you saved the file but Mesen is still showing the old version (cache; try closing and reopening Mesen)

Step 6: Take before/after screenshots (15 minutes)

Take a screenshot of the modified ROM running.

Then, in Mesen, load the ORIGINAL ROM (the unmodified one at ~/spk-101/roms/nes/). Run it to the same screen. Take a screenshot of the original at the same scene.

Save both screenshots to ~/spk-101/working/:

  • lab-4-1-before.png
  • lab-4-1-after.png

Step 7: Journal the hack (15 minutes)

Open ~/spk-101/journal/lab-4-1-notes.md. Write a short capstone-style report:

  • What color did you change?
  • What was the original NES color index? What did you change it to?
  • Where in the ROM (file offset) did the palette byte live?
  • How did you find it (strategy A or B)?
  • What did you try that did NOT work first?
  • What was the moment "it worked" like for you?

Expected output

  • A modified .nes ROM with one palette color changed
  • Before/after screenshots showing the change
  • A 3-5 paragraph journal entry walking through your work

Common pitfalls

  • Editing the wrong file: ALWAYS double-check the file path before saving. Original = roms/nes/; hack = working/
  • Searching for the wrong byte sequence: if the search finds nothing, your assumption about the palette values is wrong. Re-check what Mesen's palette viewer shows for the current palette
  • Multiple matches in PRG-ROM: try changing each one; only one will produce a visible change in the game
  • Mesen showing the old ROM after Reload: try closing Mesen entirely and reopening it. Some emulators cache the loaded ROM in memory
  • Forgetting to save in your hex editor: save explicitly. Many hex editors do not auto-save

Stretch (optional)

  • Change a second palette byte. See if you can identify which palette controls which on-screen elements (background vs. sprite; player vs. enemy)
  • Try to find a "rainbow" palette change, change multiple bytes so the affected tiles cycle through several colors
  • Look up the full NES palette PNG at https://www.nesdev.org/wiki/PPU_palettes#2C02 and pick colors that complement rather than clash

Lab 4.1 v0.1. Your first real hack. The "wait, I really can change games" moment.