# Pixeldex · Pico-8 Palette Swap Starter

Drop-in `spr_swap` and `flash_white` helpers for Pico-8 (0.2.5+), plus a `PALS` table of named team palettes. Same character at 3 colors without doubling your sprite sheet.

License: **CC0**.
Source: https://pixeldex.dev/prompts/pico8-sprite-sheet-palette-swap

---

## What's in this folder

| File | Purpose |
|---|---|
| `palette_swap.p8` | Standalone Pico-8 cart with the helpers + a working demo showing 5 palette variants + a flash-white effect. |

---

## Fastest path (~30 seconds)

1. Open Pico-8.
2. Run `load palette_swap.p8` (or drag the .p8 file into the Pico-8 window).
3. Press Cmd/Ctrl+R to run. You'll see:
 - Row 1: same sprite at 5 palettes (default, red team, blue team, gold team, green team)
 - Row 2: alternating normal and flash-white frames (hit-flash effect)

---

## Using the helpers in your own cart

Copy these two functions and the `pals` table into your cart's `__lua__` section:

```lua
pals={
 red={[8]=8},
 blue={[8]=12},
 gold={[8]=10},
 green={[8]=11,[2]=3},
}

function spr_swap(n,x,y,swaps)
 if swaps then
 for k,v in pairs(swaps) do pal(k,v) end
 end
 spr(n,x,y)
 pal()
end

function flash_white(n,x,y)
 for i=0,15 do pal(i,7) end
 spr(n,x,y)
 pal()
end
```

Then call them anywhere you'd normally call `spr()`:

```lua
spr_swap(1, 64, 64, pals.red) -- player as red team
spr_swap(1, 80, 64, pals.blue) -- same sprite, blue team

-- Hit flash: alternate between flash_white and spr() based on a timer
if hit_timer > 0 and (hit_timer % 4) < 2 then
 flash_white(1, player.x, player.y)
else
 spr(1, player.x, player.y)
end
```

---

## How it works

Pico-8's `pal(c0, c1)` swaps color c0 with c1 for subsequent draws. `pal()` with no args resets to defaults.

- `spr_swap` applies the swap, draws once, resets.
- `flash_white` maps EVERY color (0..15) to color 7 (white), draws, resets, producing a silhouette.

The `pals` table is just a lookup. Add as many as you want, `pals.boss`, `pals.poisoned`, `pals.dim` for fog-of-war, etc.

---

## Token budget

The helpers + `pals` table together cost ~90 tokens. The full cart with demo is under 300 tokens, leaving you plenty of headroom in Pico-8's 8192-token limit.

---

## Pairing ideas

- Pair with the [Pico-8 puzzle walkthrough](https://pixeldex.dev/walkthroughs/ship-a-pico8-puzzle-game-in-4-hours), recolor boxes per level for variety.
- Use `flash_white` on enemy-hit frames for that classic SNES "ouch" feel.

---

If you publish a cart that uses this, mention `pixeldex.dev` in the description. Not required.