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

**5 frames → 960×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         |

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.

## 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/enemies.png` — enemies

**3 frames → 576×192 px. Transparent background required** — full-wall-height
billboards.

| Frame | Pixels  | Enemy (`enemies.json`) | Stats to suggest visually            |
| ----- | ------- | ---------------------- | ------------------------------------ |
| 0     | 0–191   | `guard`                | baseline: 50 hp, average speed       |
| 1     | 192–383 | `heavy`                | tanky: 120 hp, slow — bulkier build  |
| 2     | 384–575 | `scout`                | fragile: 25 hp, fast — lighter build |

Notes:
- One static frame per enemy for now (no walk/attack animation support yet —
  when that lands, these will likely grow into multi-frame strips, which is
  why keeping each enemy's frames contiguous is a good habit).
- Enemies are drawn at full wall height and stand on the floor; like items,
  have the feet touch the bottom edge of the frame.
- The hurt flash is generated automatically (white-tinted copy) — you don't
  need to draw one.

## Not needed (yet)

- **Pickups** (ammo, health, treasure) and the **exit** currently always use
  their built-in generated diamond markers — there's no `texture` field for
  them in a config file yet. If you want art for those too, say so and the
  same pattern can be extended to them.
- **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/enemy = one new 192×192 frame appended to the relevant
strip + one JSON entry in `src/config/` pointing at its `frame` index. 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.