escape/sprites.md

# Spritesheets to make

The game runs fine without any art (it bakes placeholder patterns), but these
are the sheets it will pick up automatically the moment the PNG files exist.
No code changes needed — the paths and frame numbers below come straight from
`src/config/*.json`, so if you rearrange anything, update the JSON to match.

## Format rules (all sheets)

- **PNG**, laid out as a **horizontal strip of square frames**, left to right.
- Frame size is **192×192 px** (set by `textureSize` in `walls.json` for the
  wall sheet and by `TEX_SIZE` in `src/engine/registry.js` for the rest;
  everything is baked to 192×192 internally, so larger source frames just get
  downscaled).
- `frame` in the config JSON is the **0-based index** into the strip.
- The view renders at 960×600 (1:1 with the display canvas), so wall textures
  are seen at roughly full detail at one cell's distance. Draw with
  **neutral, flat lighting** — the engine adds its own directional shade
  (east/west faces darker) and distance dimming.
- Different entries may point at different files; each unique path is loaded
  once. A sheet that is missing, or too narrow for a requested frame, falls
  back to the placeholder for that entry only.

## 1. `assets/textures/walls.png` — wall textures

**7 frames → 1344×192 px. Opaque** (no transparency; these fill the whole wall).

| Frame | Pixels    | Wall (`walls.json`)      | Placeholder it replaces        |
| ----- | --------- | ------------------------ | ------------------------------ |
| 0     | 0–191     | id 1 — Gray Brick        | gray `#9a9a9a` brick courses   |
| 1     | 192–383   | id 2 — Blue Stone        | blue `#4a6fa5` pattern         |
| 2     | 384–575   | id 3 — Red Brick         | red `#a5503f` pattern          |
| 3     | 576–767   | id 4 — Wood              | brown `#8a6a3a` planks         |
| 4     | 768–959   | id 5 — Door              | gold `#c8a838` pattern         |
| 5     | 960–1151  | id 6 — Gold Door (locked)| gold `#d4af37` pattern         |
| 6     | 1152–1343 | id 7 — Silver Door (locked)| silver `#a8a8c0` pattern     |

Notes:
- One texture covers one full grid cell (all four faces use the same image;
  the engine un-mirrors back faces so text/asymmetric details stay readable).
- Make the texture **tileable left-to-right** if you want long runs of the
  same wall type to look continuous.
- Door frames (4–6) are drawn on the sliding panel itself — it slides sideways
  as the door opens, so avoid critical detail hugging the left edge (that's
  the edge that disappears first). Locked doors should visually hint at their
  key color.

## 2. `assets/textures/overlays.png` — wall overlays

**3 frames → 576×192 px. Transparent background required** — these are
alpha-composited *over* the wall texture, so every transparent pixel shows the
wall behind.

| Frame | Pixels  | Overlay (`overlays.json`) | Intended look                  |
| ----- | ------- | ------------------------- | ------------------------------ |
| 0     | 0–191   | `painting1` — Portrait    | framed picture, centered       |
| 1     | 192–383 | `banner` — Banner         | hanging cloth banner           |
| 2     | 384–575 | `vines` — Vines           | creeping foliage over the wall |

Notes:
- The 192×192 frame maps to the **entire wall face**; leave generous
  transparent margins (the placeholder uses ~30 px) so it reads as an object
  *on* the wall.
- One overlay per wall cell, shown on all faces of that block.

## 3. `assets/sprites/items.png` — decorative items

**3 frames → 576×192 px. Transparent background required** — rendered as
floor-anchored billboards that always face the player.

| Frame | Pixels  | Item (`items.json`)    | In-game height (`scale`) | Blocks? |
| ----- | ------- | ---------------------- | ------------------------ | ------- |
| 0     | 0–191   | `plant` — Potted Plant | 0.6 × wall height        | yes     |
| 1     | 192–383 | `lamp` — Floor Lamp    | 0.8 × wall height        | yes     |
| 2     | 384–575 | `rubble` — Rubble      | 0.4 × wall height        | no      |

Notes:
- **Fill the frame** with the object (touching the bottom edge) — the engine
  handles sizing via `scale` and anchors the frame's bottom to the floor, so
  empty space at the bottom of the frame makes the item float.

## 4. `assets/sprites/enemy_*.png` — enemies (one sheet per enemy)

**13 frames → 2496×192 px each. Transparent background required** —
full-wall-height billboards. One PNG per enemy type:

| File                             | Enemy (`enemies.json`) | Stats to suggest visually            |
| -------------------------------- | ---------------------- | ------------------------------------ |
| `assets/sprites/enemy_guard.png` | `guard`                | baseline: 50 hp, average speed       |
| `assets/sprites/enemy_heavy.png` | `heavy`                | tanky: 120 hp, slow — bulkier build  |
| `assets/sprites/enemy_scout.png` | `scout`                | fragile: 25 hp, fast — lighter build |

Every sheet uses the same fixed frame order (`ENEMY_FRAME_ORDER` in
`src/engine/registry.js`), offset from the enemy's `frame` base index in
`enemies.json` (0 for a dedicated file; a nonzero base lets several enemies
share one long strip):

| Offset | Pose        | Shown when                                          |
| ------ | ----------- | --------------------------------------------------- |
| 0      | `front`     | facing the player, standing                         |
| 1      | `frontWalk` | facing the player, walk-cycle alternate             |
| 2      | `left`      | facing left (its left shoulder toward you), standing|
| 3      | `leftWalk`  | walk-cycle alternate                                |
| 4      | `right`     | facing right, standing                              |
| 5      | `rightWalk` | walk-cycle alternate                                |
| 6      | `back`      | facing away, standing                               |
| 7      | `backWalk`  | walk-cycle alternate                                |
| 8      | `aim`       | spotted the player, weapon raised (reaction window / between shots) |
| 9      | `fire`      | flashed for ~150 ms after each shot                 |
| 10     | `pain`      | flinch while hurt (~120 ms after a non-fatal hit)   |
| 11     | `dying`     | first 0.5 s after death (falling)                   |
| 12     | `dead`      | corpse — held 3 s, then fades out over 1 s          |

Notes:
- Walk frames alternate with their standing pose while the enemy patrols
  (cadence tracks the enemy's speed); `aim`/`fire` are **front-facing only** —
  enemies turn to face the player whenever they engage.
- Enemies are drawn at full wall height and stand on the floor; have the feet
  touch the bottom edge of the frame. The `dying`/`dead` frames live in the
  same full-height square, so draw the corpse lying along the bottom edge.
- The hurt flash is generated automatically (white-tinted copy of the `pain`
  frame) — you don't need to draw one.
- Any missing/short sheet falls back per-frame to pose-specific placeholder
  art, so partial sheets are fine while you work.

## 5. `assets/sprites/pickups.png` — pickups & keys

**16 frames → 3072×192 px. Transparent background required** — small
floor-anchored billboards (drawn at 0.5 × wall height by default; add a
`scale` field in `pickups.json` to change per pickup).

| Frame | Pixels    | Pickup (`pickups.json`)          | Placeholder it replaces |
| ----- | --------- | -------------------------------- | ----------------------- |
| 0     | 0–191     | `ammo` — Ammo                    | yellow diamond          |
| 1     | 192–383   | `health` — Health                | green diamond           |
| 2     | 384–575   | `treasure` — Treasure            | gold diamond            |
| 3     | 576–767   | `key_gold` — Gold Key            | gold key glyph          |
| 4     | 768–959   | `key_silver` — Silver Key        | silver key glyph        |
| 5     | 960–1151  | `ammo_mg` — MG Ammo              | orange diamond          |
| 6     | 1152–1343 | `ammo_gatling` — Gatling Ammo    | orange diamond          |
| 7     | 1344–1535 | `ammo_plasma` — Plasma Cells     | teal diamond            |
| 8     | 1536–1727 | `gun_machinegun` — Machine Gun   | brown diamond           |
| 9     | 1728–1919 | `gun_gatling` — Gatling Gun      | rust diamond            |
| 10    | 1920–2111 | `gun_plasma` — Plasma Gun        | teal diamond            |
| 11    | 2112–2303 | `ammo_rocket` — Rockets          | red-orange diamond      |
| 12    | 2304–2495 | `gun_rocket` — Rocket Launcher   | dark-red diamond        |
| 13    | 2496–2687 | `ammo_shells` — Shells           | amber diamond           |
| 14    | 2688–2879 | `gun_shotgun` — Shotgun          | tan diamond             |
| 15    | 2880–3071 | `gun_doubleshotgun` — Double Shotgun | brown diamond       |

Notes:
- Key colors should match their door and their HUD chip (the chip uses the
  pickup's `color` from `pickups.json`).

## Not needed (yet)

- The **exit** uses a built-in generated marker (it's a level mechanic, not a
  configurable pickup).
- **Floors/ceilings** are flat colors (`FLOOR_COLOR` / `CEILING_COLOR` in
  `src/engine/constants.js`); textured floors are a separate engine feature.
- **Weapon/hands** on the HUD is a gray rectangle stub (`HudScene`).

## Adding more content later

New wall/overlay/item/pickup = one new 192×192 frame appended to the relevant
strip + one JSON entry in `src/config/` pointing at its `frame` index. A new
enemy = a fresh 13-frame sheet (see section 4) + its JSON entry. Nothing
else. You can also start a fresh PNG per entry if you prefer — the `texture`
path is per-entry, not global.

## Changing resolution later

Frame size and render resolution are independent knobs: `TEX_SIZE` in
`src/engine/registry.js` (+ `textureSize` in `walls.json`) for textures,
`RENDER_WIDTH`/`RENDER_HEIGHT` in `src/engine/constants.js` for the view.
Existing art keeps working after a change — frames are scaled at bake time —
but redraw at the new size for full sharpness.