# Stone wall shape system

How **thick** stone-wall sprites encode a 3D block as flat greyscale face-IDs, how **connections** open faces into neighbours, and how cobble texture is baked onto those masks for gameplay.

Thin walls use the same face vocabulary on a narrower frustum; this document centres on **thick**, which is the clearest reference.

---

## Reference files

| Path | What it is |
|------|------------|
| `client/assets/blocks/thick-stone-wall/thick-stone-wall.png` | **Gameplay** alone 1×1 (textured) |
| `client/assets/blocks/_examples/stone-wall/thick-stone-wall.png` | **Shape mask** alone 1×1 (face-id greys) |
| `client/assets/blocks/thick-stone-wall/thick-stone-wall-*.png` | 15 connected gameplay variants |
| `client/assets/blocks/_examples/stone-wall/ref-thick-alone-256.png` | Nearest-neighbour ×16 alone (shape) |
| `…/ref-thick-face-id-16.png` / `…-256.png` | False-colour face roles |
| `…/ref-thick-height-16.png` / `…-256.png` | Relative heightmap from roles |
| `…/ref-thick-face-legend.png` | Colour key for face-id |
| `…/ref-thick-all-variants.png` | Labeled 4×4 sheet of all 16 thick states |
| `client/scripts/export-thick-wall-refs.py` | Regenerates face-id / height / alone refs |

Gameplay keys: `thick-stone-wall`, `thin-stone-wall`. Suffixes from cardinal neighbours only (`n`/`e`/`s`/`w` → e.g. `we`, `ns`, `esw`, `wne`, `nesw`). See `shared/world/neighborConnect.js`.

---

## 1. Camera and axes

- Tile size: **16×16** px.  
- **+X = east** (right), **+Y = south** (down on screen).  
- View: **top-down with a front bias** — you see the flat **top**, thin **west/east** vertical sides, and a tall **south** front face.  
- Greys are **face identity**, not painted lighting noise. Texture work must stay inside these regions.

```text
        N (−Y)
         ↑
  W ← tile → E
         ↓
        S (+Y, toward camera)
```

---

## 2. Greyscale vocabulary (face IDs)

Exact values from `thick-stone-wall.png`. Six tones only:

| Grey | Hex | Role | Reads as |
|------|-----|------|----------|
| 64 | `0x40` | **Outline / crease** | Outer rim + lip between faces |
| 175 | `0xAF` | **North bevel** | Top rim facing north (−Y) — brightest body |
| 149 | `0x95` | **West face** | Vertical face facing west (−X) |
| 128 | `0x80` | **Top plateau** | Flat upper surface of the volume |
| 108 | `0x6C` | **East face** | Vertical face facing east (+X) — darker than west |
| 84 | `0x54` | **South face** | Vertical face facing south (+Y) — darkest body |

Mnemonic on a free 1×1:

```text
              N = 0xAF (bright)
W = 0x95                E = 0x6C
              top = 0x80
              S = 0x54 (dark)
         outline = 0x40 everywhere edges meet
```

**Do not invent intermediate greys** when cloning the structure. Remap these six roles to material colours / normals later.

---

## 3. Alone anatomy (pixel-exact)

Role map of `thick-stone-wall.png` (`#` outline, `N`/`W`/`E`/`T`/`S` as above):

```text
 y\x  0 1 2 3 4 5 6 7 8 9 A B C D E F
  0   # # # # # # # # # # # # # # # #
  1   # # # N N N N N N N N N N # # #
  2   # W W # # # # # # # # # # E E #
  3   # W W # T T T T T T T T # E E #
  4   # W W # T T T T T T T T # E E #
  5   # W W # T T T T T T T T # E E #
  6   # W W # T T T T T T T T # E E #
  7   # W W # T T T T T T T T # E E #
  8   # W W # T T T T T T T T # E E #
  9   # W W # # # # # # # # # # E E #
 10   # W W # S S S S S S S S # E E #
 11   # W # S S S S S S S S S S # E #
 12   # W # S S S S S S S S S S # E #
 13   # # S S S S S S S S S S S S # #
 14   # # S S S S S S S S S S S S # #
 15   # # # # # # # # # # # # # # # #
```

### Region boxes (inclusive)

| Role | Pixels | Notes |
|------|--------|-------|
| Outline | Full perimeter + every lip between faces | Never fill with body grey |
| North bevel | `y=1`, `x=3..12` | Only when **north is free** |
| West face | `x=1..2`, `y=2..12` (tapers: one px at `y=11..12`) | Only when **west is free** |
| East face | `x=13..14`, `y=2..12` (tapers) | Only when **east is free** |
| Top plateau | `x=4..11`, `y=3..8` | Surrounded by `0x40` lips |
| South face | `y=10..14`, widens downward (`x=4..11` → `x=2..13`) | Only when **south is free** |

### Volume model

Read the tile as a **truncated box / frustum**:

1. **Roof** — plateau `0x80` with north lip `0xAF`.  
2. **Side walls** — west `0x95`, east `0x6C` (asymmetry = light from NW).  
3. **Front wall** — south `0x54`, taller in screen space.  
4. **Creases** — `0x40` at every face junction and the tile border.

Corners are mitered: NW = N↔W, NE = N↔E, SW = S↔W, SE = S↔E, resolved by outline pixels.

---

## 4. Connection rule (core)

A suffix letter means: **this tile continues into a neighbour on that side**.

For each connected cardinal:

1. **Remove** that side’s free-face band (`N`/`E`/`S`/`W` grey).  
2. **Extrude** interior bands (plateau, remaining free faces, and their outline lips) **to the tile edge** on that side so the neighbour can match.  
3. **Keep** free-face bands only on sides that are **not** connected.

| Open | Remove | Extrude to edge |
|------|--------|-----------------|
| **N** | North bevel `0xAF` (+ north rim treatment) | W / E / T run to `y=0` |
| **E** | East face `0x6C` | N (if free) / T / S run to `x=15` |
| **S** | South face `0x54` | W / E / T run to `y=15` |
| **W** | West face `0x95` | N (if free) / T / S run to `x=0` |

### Opposite pairs

**`ns`** — vertical run: full-height W + T + E columns; no N bevel, no S front.

```text
##WW##TTTTTTTT##EE##   (repeats y=0..15)
```

**`we`** — horizontal run: full-width N rim (if free), T band, S band; no W/E sides.

```text
################  y0
NNNNNNNNNNNNNNNN  y1
################  y2
TTTTTTTTTTTTTTTT  y3..8
################  y9
SSSSSSSSSSSSSSSS  y10..14
################  y15
```

### Seam contract

Across a shared edge, both tiles paint the **same continuing role** to `x=0|15` or `y=0|15`. Example: A=`…e` and B=`…w` both show plateau `0x80` (and matching N/S bands) meeting mid-edge — **no** side-face grey on that shared edge.

---

## 5. Corners, T-junctions, and concave pockets

Corners (`ne`, `es`, `sw`, `wn`) and T’s (`esw`, `wne`, `swn`, `nes`) are **unions** of the open-face rules.

Where two **free** faces would have met at a concave inner corner after opening the other sides, the art keeps a small **pocket**: outline + a stub of the free face greys. That pocket is what makes an L or T read as a turn rather than a flat extrusion.

Examples (schematic):

**`es`** (open E+S → free N+W): south-east corner keeps an E/S pocket while T extrudes east and south elsewhere.

**`esw`** (T, free N only): full-width N + T like `we`, but south edge shows **two** S/W and S/E pockets at the SW and SE corners (the stem of the T going south).

**`wne`** (T, free S only): full-width S band; north edge shows N pockets at NW/NE where the stem goes north.

**`nesw`** (all four open): no full free faces; T fills the centre and runs to all edges, with **four corner pockets** (N stubs at top, S/W/E stubs at bottom corners). Those pockets are intentional — they are the miters where four neighbour walls meet around this cell in a solid fill / 2×2 interior is different from a true cross; authored `nesw` still carries corner detail for visual continuity with T/L art.

### 2×2 solid block

Four tiles use **corner** suffixes, not `nesw`:

| Cell | Suffix |
|------|--------|
| NW | `es` |
| NE | `sw` |
| SW | `ne` |
| SE | `wn` |

Each keeps the two **outer** free faces and opens the two **inner** sides into the cluster. (`nesw` is for a cell with neighbours on all four cardinals — e.g. interior of a thicker shape — not for the four cells of a minimal 2×2.)

---

## 6. Worked single-open examples

**`n`** — north open: row 0 becomes the old “interior” W/T/E pattern; south stack unchanged.

```text
##WW##TTTTTTTT##EE##  y0..8
##WW############EE##  y9
##WW##SSSSSSSS##EE##  y10
… south taper …
################    y15
```

**`s`** — south open: plateau + sides continue through `y=15`; no `0x54`.

**`e`** — east open: N/T/S (and W) run to `x=15`; no `0x6C`.

**`w`** — west open: N/T/S run to `x=0`; free east column remains.

> **Note:** free east on `thick-stone-wall-w` uses `0x6C` (corrected). When flipping `e`↔`w` art, always reassign face greys — do not keep mirrored luminance.

---

## 7. Heightmap (for cloning / normals)

`ref-thick-height-*.png` maps roles → relative height (0–255):

| Role | Height | Order |
|------|--------|-------|
| Outline | 40 | Lowest (crease / contact) |
| South face | 80 | Front of prism |
| East face | 140 | Side |
| West face | 160 | Side (slightly higher = lit side) |
| Top plateau | 200 | Roof |
| North bevel | 220 | Upper lip |

Ordering to preserve when editing:  
`outline ≤ south ≤ east ≤ west ≤ top ≤ north`.

Uses:

- Extrude a new material with the **same silhouettes**.  
- Bake normals: up on plateau, −Y on north bevel, ±X on sides, +Y on south.  
- Validate connection variants (no south-height pixels on the plateau).

This is a **role-derived** height field, not scanned depth. Absolute values may shift for a shader; keep the order.

---

## 8. Face-id map (tooling)

False colour in `ref-thick-face-id-*.png`:

| Colour | Role |
|--------|------|
| White | North bevel |
| Red | West face |
| Blue | East face |
| Green | South face |
| Amber | Top plateau |
| Near-black | Outline |

Suggested pipeline for a new wall set:

1. Author or copy **face-id** (or height + face-id) at 16×16.  
2. Fill each role with albedo / material detail **inside** the mask.  
3. Optional soft light multiply that still respects N lightest → S darkest.  
4. Keep outline as mortar/edge or replace with a 1px edge pass.  
5. Derive the 15 connection variants by applying §4–§5 (or paint from thick examples with recolour-by-role).

---

## 9. Checklist — new thick-style wall

**Alone**

- [ ] Full-tile thick footprint (or intentional inset for a thin family).  
- [ ] Only the six role greys (or 1:1 mapped equivalents).  
- [ ] Free N → `0xAF` rim; free W → `0x95`; free E → `0x6C`; free S → `0x54`; centre → `0x80`.  
- [ ] Outline separates every face pair.

**Each suffix**

- [ ] Connected side has no free-face band of that direction.  
- [ ] Interior bands meet the tile edge on connected sides.  
- [ ] Free sides keep the correct face grey (`E` = `0x6C`, not a flipped `0x95`).  
- [ ] Seam matches the opposite suffix on the neighbour (`e`↔`w`, `n`↔`s`).  
- [ ] L/T/`nesw` keep concave corner pockets where needed.

**Texturing**

- [ ] No detail crossing role boundaries without an outline.  
- [ ] Normals follow face directions in §7.  
- [ ] After recolour, regenerate face-id/height refs and spot-check all 16 states.

---

## 10. Thin walls

`thin-stone-wall` uses the **same idea** on a **narrow frustum**, but a slightly different grey vocabulary:

| Grey | Hex | Thin role |
|------|-----|-----------|
| 64 | `0x40` | Outline |
| 182 | `0xB6` | West face |
| 149 | `0x95` | North rim / ridge top |
| 128 | `0x80` | East face (**not** top plateau — differs from thick) |
| 115 | `0x73` | South / front body |

Clone thin silhouettes; recolour via this table (or `texture-stone-wall-sprites.mjs`).

---

## 11. Baking cobble texture

Gameplay sprites in `thick-stone-wall/` and `thin-stone-wall/` are **textured**. Greyscale face-id masks stay in `_examples/stone-wall/`.

```bash
node client/scripts/texture-stone-wall-sprites.mjs
```

Reads example masks → writes cobble-shaded PNGs using the old cool-grey stone palette (TOP / FACE / EDGE / MORTAR speckles), keyed by face role. Re-run after editing shapes in `_examples`.

---

## 12. Code touchpoints

| Concern | Location |
|---------|----------|
| Cardinal suffix / mask (`& 15`) | `shared/world/neighborConnect.js` |
| Block defs | `shared/definitions/tiles.js` |
| Textured sprites (gameplay) | `client/assets/blocks/thick-stone-wall/`, `thin-stone-wall/` |
| Greyscale shape masks + refs | `client/assets/blocks/_examples/stone-wall/` |
| Shape generator from connecting examples | `client/scripts/generate-stone-wall-sprites.mjs` |
| Cobble texture bake | `client/scripts/texture-stone-wall-sprites.mjs` |
| Ref export | `client/scripts/export-thick-wall-refs.py` |

Editor recomputes neighbour suffixes on paint and on chunk load so a 2×2 stays on corner suffixes, not `nesw`.

---

## 13. Regenerate reference maps

Whenever the thick alone **shape** mask changes:

```bash
python3 client/scripts/export-thick-wall-refs.py
node client/scripts/texture-stone-wall-sprites.mjs
```

Then update the grey table in §2 / §10 if the vocabulary shifted.
