BlueGit

timfa questward

wall sprites and examples

timfa Tim Falken · pushed by timfa

Authored 2026-08-31 · 2 months ago

Hash
5666b73ee014d232b720789d3fac2169b7a79643
Parent
f499e5ae
58 files changed +317 −0
client/assets/blocks/_examples/stone-wall/example-stone-thick-T.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thick-connecting-2x2.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thick-connecting-L.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thick-connecting-up.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thick-connecting-updown.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thick-connecting.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thick.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting-2x2.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting-L.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting-Ldownright.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting-T-upsidedown.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting-T.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting-down.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting-up.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting-updown.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin-connecting.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/example-stone-thin.png deleted Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/ref-thick-all-variants.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/ref-thick-alone-256.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/ref-thick-face-id-16.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/ref-thick-face-id-256.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/ref-thick-face-legend.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/ref-thick-height-16.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/ref-thick-height-256.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-e.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-es.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-esw.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-n.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-ne.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-nes.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-nesw.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-ns.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-s.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-sw.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-swn.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-w.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-we.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-wn.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall-wne.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thick-stone-wall.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-e.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-es.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-esw.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-n.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-ne.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-nes.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-nesw.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-ns.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-s.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-sw.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-swn.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-w.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-we.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-wn.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall-wne.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/_examples/stone-wall/thin-stone-wall.png added Binary file +0 −0

The contents of this binary file are not shown.

client/assets/blocks/thick-stone-wall/thick-stone-wall-w.png Binary file +0 −0

The contents of this binary file are not shown.

docs/STONE_WALL_SHAPES.md added +317 −0
@@ -0,0 +1,317 @@
1 # Stone wall shape system
2
3 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.
4
5 Thin 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
22 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`.
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
45 Exact 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
56 Mnemonic on a free 1×1:
57
58 ```text
59 N = 0xAF (bright)
60 W = 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
72 Role 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
107 Read the tile as a **truncated box / frustum**:
108
109 1. **Roof** — plateau `0x80` with north lip `0xAF`.
110 2. **Side walls** — west `0x95`, east `0x6C` (asymmetry = light from NW).
111 3. **Front wall** — south `0x54`, taller in screen space.
112 4. **Creases** — `0x40` at every face junction and the tile border.
113
114 Corners 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
120 A suffix letter means: **this tile continues into a neighbour on that side**.
121
122 For each connected cardinal:
123
124 1. **Remove** that side’s free-face band (`N`/`E`/`S`/`W` grey).
125 2. **Extrude** interior bands (plateau, remaining free faces, and their outline lips) **to the tile edge** on that side so the neighbour can match.
126 3. **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
147 NNNNNNNNNNNNNNNN y1
148 ################ y2
149 TTTTTTTTTTTTTTTT y3..8
150 ################ y9
151 SSSSSSSSSSSSSSSS y10..14
152 ################ y15
153 ```
154
155 ### Seam contract
156
157 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.
158
159 ---
160
161 ## 5. Corners, T-junctions, and concave pockets
162
163 Corners (`ne`, `es`, `sw`, `wn`) and T’s (`esw`, `wne`, `swn`, `nes`) are **unions** of the open-face rules.
164
165 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.
166
167 Examples (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
179 Four tiles use **corner** suffixes, not `nesw`:
180
181 | Cell | Suffix |
182 |------|--------|
183 | NW | `es` |
184 | NE | `sw` |
185 | SW | `ne` |
186 | SE | `wn` |
187
188 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.)
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
227 Ordering to preserve when editing:
228 `outline ≤ south ≤ east ≤ west ≤ top ≤ north`.
229
230 Uses:
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
236 This 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
242 False 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
253 Suggested pipeline for a new wall set:
254
255 1. Author or copy **face-id** (or height + face-id) at 16×16.
256 2. Fill each role with albedo / material detail **inside** the mask.
257 3. Optional soft light multiply that still respects N lightest → S darkest.
258 4. Keep outline as mortar/edge or replace with a 1px edge pass.
259 5. 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
305 Editor 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
311 Whenever `thick-stone-wall.png` (alone) changes:
312
313 ```bash
314 python3 client/scripts/export-thick-wall-refs.py
315 ```
316
317 Then update the grey table in §2 if the vocabulary shifted.
@@ -0,0 +1,317 @@
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.