# 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.