BlueGit

timfa questward

Files

questward / docs / STONE_WALL_SHAPES.md

STONE_WALL_SHAPES.md

wall sprites and examples
timfa Tim Falken · pushed by timfa · 2 months ago
5666b73e History
STONE_WALL_SHAPES.md 11.7 KiB Download Raw

Stone wall shape system

How thick stone-wall sprites encode a 3D block as flat greyscale, how connections open faces into neighbours, and how to clone the structure for new materials / textures.

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

---

Reference files

PathWhat it is
client/assets/blocks/thick-stone-wall/thick-stone-wall.pngSource of truth — alone 1×1
client/assets/blocks/thick-stone-wall/thick-stone-wall-*.png15 connected variants
client/assets/blocks/_examples/stone-wall/ref-thick-alone-256.pngNearest-neighbour ×16 alone
…/ref-thick-face-id-16.png / …-256.pngFalse-colour face roles
…/ref-thick-height-16.png / …-256.pngRelative heightmap from roles
…/ref-thick-face-legend.pngColour key for face-id
…/ref-thick-all-variants.pngLabeled 4×4 sheet of all 16 thick states
client/scripts/export-thick-wall-refs.pyRegenerates 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.
        N (−Y)
         ↑
  W ← tile → E
         ↓
        S (+Y, toward camera)

---

2. Greyscale vocabulary (face IDs)

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

GreyHexRoleReads as
640x40Outline / creaseOuter rim + lip between faces
1750xAFNorth bevelTop rim facing north (−Y) — brightest body
1490x95West faceVertical face facing west (−X)
1280x80Top plateauFlat upper surface of the volume
1080x6CEast faceVertical face facing east (+X) — darker than west
840x54South faceVertical face facing south (+Y) — darkest body

Mnemonic on a free 1×1:

              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):

 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)

RolePixelsNotes
OutlineFull perimeter + every lip between facesNever fill with body grey
North bevely=1, x=3..12Only when north is free
West facex=1..2, y=2..12 (tapers: one px at y=11..12)Only when west is free
East facex=13..14, y=2..12 (tapers)Only when east is free
Top plateaux=4..11, y=3..8Surrounded by 0x40 lips
South facey=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.

OpenRemoveExtrude to edge
NNorth bevel 0xAF (+ north rim treatment)W / E / T run to y=0
EEast face 0x6CN (if free) / T / S run to x=15
SSouth face 0x54W / E / T run to y=15
WWest face 0x95N (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.

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

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

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

CellSuffix
NWes
NEsw
SWne
SEwn

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.

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

> Authoring note: on the current thick-stone-wall-w.png, the free east column is painted with 0x95 (west grey) rather than 0x6C. Structurally it is still “east free face”. When texturing or rebuilding, prefer remapping to 0x6C so E/W lighting stays consistent with alone. Horizontal flips of e must reassign face greys — do not keep mirrored luminance.

---

7. Heightmap (for cloning / normals)

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

RoleHeightOrder
Outline40Lowest (crease / contact)
South face80Front of prism
East face140Side
West face160Side (slightly higher = lit side)
Top plateau200Roof
North bevel220Upper 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:

ColourRole
WhiteNorth bevel
RedWest face
BlueEast face
GreenSouth face
AmberTop plateau
Near-blackOutline

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

0 of 4 tasks completed

  • 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

0 of 5 tasks completed

  • 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

0 of 3 tasks completed

  • 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 face roles on a narrow frustum (alone body inset; N/S runs stay narrow; E/W opens the frustum to the edge). Clone thin silhouettes, recolour by the thick role table. Prefer thick as the teaching reference when learning the system.

---

11. Code touchpoints

ConcernLocation
Cardinal suffix / mask (& 15)shared/world/neighborConnect.js
Block defsshared/definitions/tiles.js
Spritesclient/assets/blocks/thick-stone-wall/, thin-stone-wall/
Shape examples + refsclient/assets/blocks/_examples/stone-wall/
Example-driven generatorclient/scripts/generate-stone-wall-sprites.mjs
Ref exportclient/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.

---

12. Regenerate reference maps

Whenever thick-stone-wall.png (alone) changes:

python3 client/scripts/export-thick-wall-refs.py

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

Source
1# Stone wall shape system
2
3How **thick** stone-wall sprites encode a 3D block as flat greyscale, how **connections** open faces into neighbours, and how to clone the structure for new materials / textures.
4
5Thin walls use the same face vocabulary on a narrower frustum; this document centres on **thick**, which is the clearest reference.
6
7---
8
9## Reference files
10
11| Path | What it is |
12|------|------------|
13| `client/assets/blocks/thick-stone-wall/thick-stone-wall.png` | **Source of truth** — alone 1×1 |
14| `client/assets/blocks/thick-stone-wall/thick-stone-wall-*.png` | 15 connected variants |
15| `client/assets/blocks/_examples/stone-wall/ref-thick-alone-256.png` | Nearest-neighbour ×16 alone |
16| `…/ref-thick-face-id-16.png` / `…-256.png` | False-colour face roles |
17| `…/ref-thick-height-16.png` / `…-256.png` | Relative heightmap from roles |
18| `…/ref-thick-face-legend.png` | Colour key for face-id |
19| `…/ref-thick-all-variants.png` | Labeled 4×4 sheet of all 16 thick states |
20| `client/scripts/export-thick-wall-refs.py` | Regenerates face-id / height / alone refs |
21
22Gameplay 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`.
23
24---
25
26## 1. Camera and axes
27
28- Tile size: **16×16** px.
29- **+X = east** (right), **+Y = south** (down on screen).
30- View: **top-down with a front bias** — you see the flat **top**, thin **west/east** vertical sides, and a tall **south** front face.
31- Greys are **face identity**, not painted lighting noise. Texture work must stay inside these regions.
32
33```text
34 N (−Y)
35 ↑
36 W ← tile → E
37 ↓
38 S (+Y, toward camera)
39```
40
41---
42
43## 2. Greyscale vocabulary (face IDs)
44
45Exact values from `thick-stone-wall.png`. Six tones only:
46
47| Grey | Hex | Role | Reads as |
48|------|-----|------|----------|
49| 64 | `0x40` | **Outline / crease** | Outer rim + lip between faces |
50| 175 | `0xAF` | **North bevel** | Top rim facing north (−Y) — brightest body |
51| 149 | `0x95` | **West face** | Vertical face facing west (−X) |
52| 128 | `0x80` | **Top plateau** | Flat upper surface of the volume |
53| 108 | `0x6C` | **East face** | Vertical face facing east (+X) — darker than west |
54| 84 | `0x54` | **South face** | Vertical face facing south (+Y) — darkest body |
55
56Mnemonic on a free 1×1:
57
58```text
59 N = 0xAF (bright)
60W = 0x95 E = 0x6C
61 top = 0x80
62 S = 0x54 (dark)
63 outline = 0x40 everywhere edges meet
64```
65
66**Do not invent intermediate greys** when cloning the structure. Remap these six roles to material colours / normals later.
67
68---
69
70## 3. Alone anatomy (pixel-exact)
71
72Role map of `thick-stone-wall.png` (`#` outline, `N`/`W`/`E`/`T`/`S` as above):
73
74```text
75 y\x 0 1 2 3 4 5 6 7 8 9 A B C D E F
76 0 # # # # # # # # # # # # # # # #
77 1 # # # N N N N N N N N N N # # #
78 2 # W W # # # # # # # # # # E E #
79 3 # W W # T T T T T T T T # E E #
80 4 # W W # T T T T T T T T # E E #
81 5 # W W # T T T T T T T T # E E #
82 6 # W W # T T T T T T T T # E E #
83 7 # W W # T T T T T T T T # E E #
84 8 # W W # T T T T T T T T # E E #
85 9 # W W # # # # # # # # # # E E #
86 10 # W W # S S S S S S S S # E E #
87 11 # W # S S S S S S S S S S # E #
88 12 # W # S S S S S S S S S S # E #
89 13 # # S S S S S S S S S S S S # #
90 14 # # S S S S S S S S S S S S # #
91 15 # # # # # # # # # # # # # # # #
92```
93
94### Region boxes (inclusive)
95
96| Role | Pixels | Notes |
97|------|--------|-------|
98| Outline | Full perimeter + every lip between faces | Never fill with body grey |
99| North bevel | `y=1`, `x=3..12` | Only when **north is free** |
100| West face | `x=1..2`, `y=2..12` (tapers: one px at `y=11..12`) | Only when **west is free** |
101| East face | `x=13..14`, `y=2..12` (tapers) | Only when **east is free** |
102| Top plateau | `x=4..11`, `y=3..8` | Surrounded by `0x40` lips |
103| South face | `y=10..14`, widens downward (`x=4..11` → `x=2..13`) | Only when **south is free** |
104
105### Volume model
106
107Read the tile as a **truncated box / frustum**:
108
1091. **Roof** — plateau `0x80` with north lip `0xAF`.
1102. **Side walls** — west `0x95`, east `0x6C` (asymmetry = light from NW).
1113. **Front wall** — south `0x54`, taller in screen space.
1124. **Creases** — `0x40` at every face junction and the tile border.
113
114Corners are mitered: NW = N↔W, NE = N↔E, SW = S↔W, SE = S↔E, resolved by outline pixels.
115
116---
117
118## 4. Connection rule (core)
119
120A suffix letter means: **this tile continues into a neighbour on that side**.
121
122For each connected cardinal:
123
1241. **Remove** that side’s free-face band (`N`/`E`/`S`/`W` grey).
1252. **Extrude** interior bands (plateau, remaining free faces, and their outline lips) **to the tile edge** on that side so the neighbour can match.
1263. **Keep** free-face bands only on sides that are **not** connected.
127
128| Open | Remove | Extrude to edge |
129|------|--------|-----------------|
130| **N** | North bevel `0xAF` (+ north rim treatment) | W / E / T run to `y=0` |
131| **E** | East face `0x6C` | N (if free) / T / S run to `x=15` |
132| **S** | South face `0x54` | W / E / T run to `y=15` |
133| **W** | West face `0x95` | N (if free) / T / S run to `x=0` |
134
135### Opposite pairs
136
137**`ns`** — vertical run: full-height W + T + E columns; no N bevel, no S front.
138
139```text
140##WW##TTTTTTTT##EE## (repeats y=0..15)
141```
142
143**`we`** — horizontal run: full-width N rim (if free), T band, S band; no W/E sides.
144
145```text
146################ y0
147NNNNNNNNNNNNNNNN y1
148################ y2
149TTTTTTTTTTTTTTTT y3..8
150################ y9
151SSSSSSSSSSSSSSSS y10..14
152################ y15
153```
154
155### Seam contract
156
157Across 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.
158
159---
160
161## 5. Corners, T-junctions, and concave pockets
162
163Corners (`ne`, `es`, `sw`, `wn`) and T’s (`esw`, `wne`, `swn`, `nes`) are **unions** of the open-face rules.
164
165Where 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.
166
167Examples (schematic):
168
169**`es`** (open E+S → free N+W): south-east corner keeps an E/S pocket while T extrudes east and south elsewhere.
170
171**`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).
172
173**`wne`** (T, free S only): full-width S band; north edge shows N pockets at NW/NE where the stem goes north.
174
175**`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.
176
177### 2×2 solid block
178
179Four tiles use **corner** suffixes, not `nesw`:
180
181| Cell | Suffix |
182|------|--------|
183| NW | `es` |
184| NE | `sw` |
185| SW | `ne` |
186| SE | `wn` |
187
188Each 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.)
189
190---
191
192## 6. Worked single-open examples
193
194**`n`** — north open: row 0 becomes the old “interior” W/T/E pattern; south stack unchanged.
195
196```text
197##WW##TTTTTTTT##EE## y0..8
198##WW############EE## y9
199##WW##SSSSSSSS##EE## y10
200… south taper …
201################ y15
202```
203
204**`s`** — south open: plateau + sides continue through `y=15`; no `0x54`.
205
206**`e`** — east open: N/T/S (and W) run to `x=15`; no `0x6C`.
207
208**`w`** — west open: N/T/S run to `x=0`; free east column remains.
209
210> **Authoring note:** on the current `thick-stone-wall-w.png`, the free east column is painted with **`0x95` (west grey)** rather than `0x6C`. Structurally it is still “east free face”. When texturing or rebuilding, prefer **remapping to `0x6C`** so E/W lighting stays consistent with alone. Horizontal flips of `e` must reassign face greys — do not keep mirrored luminance.
211
212---
213
214## 7. Heightmap (for cloning / normals)
215
216`ref-thick-height-*.png` maps roles → relative height (0–255):
217
218| Role | Height | Order |
219|------|--------|-------|
220| Outline | 40 | Lowest (crease / contact) |
221| South face | 80 | Front of prism |
222| East face | 140 | Side |
223| West face | 160 | Side (slightly higher = lit side) |
224| Top plateau | 200 | Roof |
225| North bevel | 220 | Upper lip |
226
227Ordering to preserve when editing:
228`outline ≤ south ≤ east ≤ west ≤ top ≤ north`.
229
230Uses:
231
232- Extrude a new material with the **same silhouettes**.
233- Bake normals: up on plateau, −Y on north bevel, ±X on sides, +Y on south.
234- Validate connection variants (no south-height pixels on the plateau).
235
236This is a **role-derived** height field, not scanned depth. Absolute values may shift for a shader; keep the order.
237
238---
239
240## 8. Face-id map (tooling)
241
242False colour in `ref-thick-face-id-*.png`:
243
244| Colour | Role |
245|--------|------|
246| White | North bevel |
247| Red | West face |
248| Blue | East face |
249| Green | South face |
250| Amber | Top plateau |
251| Near-black | Outline |
252
253Suggested pipeline for a new wall set:
254
2551. Author or copy **face-id** (or height + face-id) at 16×16.
2562. Fill each role with albedo / material detail **inside** the mask.
2573. Optional soft light multiply that still respects N lightest → S darkest.
2584. Keep outline as mortar/edge or replace with a 1px edge pass.
2595. Derive the 15 connection variants by applying §4–§5 (or paint from thick examples with recolour-by-role).
260
261---
262
263## 9. Checklist — new thick-style wall
264
265**Alone**
266
267- [ ] Full-tile thick footprint (or intentional inset for a thin family).
268- [ ] Only the six role greys (or 1:1 mapped equivalents).
269- [ ] Free N → `0xAF` rim; free W → `0x95`; free E → `0x6C`; free S → `0x54`; centre → `0x80`.
270- [ ] Outline separates every face pair.
271
272**Each suffix**
273
274- [ ] Connected side has no free-face band of that direction.
275- [ ] Interior bands meet the tile edge on connected sides.
276- [ ] Free sides keep the correct face grey (`E` = `0x6C`, not a flipped `0x95`).
277- [ ] Seam matches the opposite suffix on the neighbour (`e`↔`w`, `n`↔`s`).
278- [ ] L/T/`nesw` keep concave corner pockets where needed.
279
280**Texturing**
281
282- [ ] No detail crossing role boundaries without an outline.
283- [ ] Normals follow face directions in §7.
284- [ ] After recolour, regenerate face-id/height refs and spot-check all 16 states.
285
286---
287
288## 10. Thin walls
289
290`thin-stone-wall` uses the **same face roles** on a **narrow frustum** (alone body inset; N/S runs stay narrow; E/W opens the frustum to the edge). Clone thin silhouettes, recolour by the thick role table. Prefer thick as the teaching reference when learning the system.
291
292---
293
294## 11. Code touchpoints
295
296| Concern | Location |
297|---------|----------|
298| Cardinal suffix / mask (`& 15`) | `shared/world/neighborConnect.js` |
299| Block defs | `shared/definitions/tiles.js` |
300| Sprites | `client/assets/blocks/thick-stone-wall/`, `thin-stone-wall/` |
301| Shape examples + refs | `client/assets/blocks/_examples/stone-wall/` |
302| Example-driven generator | `client/scripts/generate-stone-wall-sprites.mjs` |
303| Ref export | `client/scripts/export-thick-wall-refs.py` |
304
305Editor recomputes neighbour suffixes on paint and on chunk load so a 2×2 stays on corner suffixes, not `nesw`.
306
307---
308
309## 12. Regenerate reference maps
310
311Whenever `thick-stone-wall.png` (alone) changes:
312
313```bash
314python3 client/scripts/export-thick-wall-refs.py
315```
316
317Then update the grey table in §2 if the vocabulary shifted.