docs(design): render architecture — cliff walls + iso depth buffer + SurfaceStack (supersedes tiles/overlay) #271

Merged

panda merged 3 commits from design/render-architecture into main

2026-08-05 13:39:23 +02:00

panda commented

2026-08-03 23:41:39 +02:00

Collaborator

Summary

Updates the multi-level world-model design (#268) with a rendering architecture that supersedes two earlier drafts (surfaces-as-tiles C2 and the P2b discrete-cell overlay spike). It incorporates an external architecture review (kept in-repo) plus our own DesktopGL depth findings.

Root cause it names: a heightfield with one shared vertex per cell can't be a wall, a top surface and a depth all at once — hence both "no verticality" and "no occlusion". The overlay spike (branch feat/relief-overlay-occlusion, not merged) proved the anti-occlusion mechanism but was a band-aid on that model.

Four-pillar architecture (2.5-D iso, still 2-D sprite):

Explicit cliff walls — raw-ΔZ edge classification; at a cliff, duplicate edge vertices + emit vertical wall quads (a <material>_cliff art). Keep the SDF top mesh for gentle ground.
Edge-aware smoothing — bilateral/region-connected, never crosses a cliff (a raw cliff stays a cliff in display-Z).
Isometric depth buffer — depth = camera-forward axis (not foot-Y); terrain + entities share it → terrain occludes entities natively.
SceneRT + one composite — sidesteps MonoGame's back-buffer discard.

Anti-occlusion (Diablo/Fallout reveal) becomes a native depth compare + circle-of-transparency fade + hero silhouette — no per-cell overlay. Rendering is chunked mesh per surface (ModernUO SurfaceStack semantics), which is the multi-level model (P2b and multi-level are one architecture, not two).

The risk this PR flags (ours, the review couldn't know it): the depth buffer on DesktopGL/SM3 is a known-hard case (#240 — no invariant gl_Position, no early_fragment_tests, back-buffer depth fps hit). So P2 now opens with a de-risk spike (SceneRT + DepthFormat, two overlapping quads), gating the rest.

Phases retargeted: P2·spike (gate) → P2·A solid terrain → P2·B iso depth → P2·C player reveal. P2a (#270) already shipped.

How it was tested

N/A — design docs only. check-doc-refs clean.

Checklist

Design-first: architecture + risk + phased DoD, before code
ModernUO reference (SurfaceStack) preserved; external review credited + kept in-repo
Our DesktopGL/SM3 depth constraint (#240) folded in as the gating risk
Implementation — NOT started; the depth-spike is the next buildable gate

Design update for #268.

## Summary Updates the multi-level world-model design (#268) with a **rendering architecture** that supersedes two earlier drafts (*surfaces-as-tiles C2* and the P2b *discrete-cell overlay* spike). It incorporates an **external architecture review** (kept in-repo) plus our own DesktopGL depth findings. **Root cause it names:** a heightfield with one shared vertex per cell **can't be a wall, a top surface and a depth all at once** — hence both "no verticality" and "no occlusion". The overlay spike (branch `feat/relief-overlay-occlusion`, not merged) proved the anti-occlusion *mechanism* but was a band-aid on that model. **Four-pillar architecture (2.5-D iso, still 2-D sprite):** 1. **Explicit cliff walls** — raw-ΔZ edge classification; at a cliff, duplicate edge vertices + emit vertical wall quads (a `<material>_cliff` art). Keep the SDF top mesh for gentle ground. 2. **Edge-aware smoothing** — bilateral/region-connected, never crosses a cliff (a raw cliff stays a cliff in display-Z). 3. **Isometric depth buffer** — depth = camera-forward axis (not foot-Y); terrain + entities share it → terrain occludes entities natively. 4. **SceneRT + one composite** — sidesteps MonoGame's back-buffer discard. Anti-occlusion (Diablo/Fallout reveal) becomes a **native depth compare + circle-of-transparency fade + hero silhouette** — no per-cell overlay. Rendering is **chunked mesh per surface** (ModernUO SurfaceStack semantics), which *is* the multi-level model (P2b and multi-level are one architecture, not two). **The risk this PR flags (ours, the review couldn't know it):** the depth buffer on DesktopGL/SM3 is a known-hard case (#240 — no `invariant gl_Position`, no `early_fragment_tests`, back-buffer depth fps hit). So P2 now **opens with a de-risk spike** (SceneRT + DepthFormat, two overlapping quads), gating the rest. Phases retargeted: **P2·spike (gate) → P2·A solid terrain → P2·B iso depth → P2·C player reveal**. P2a (#270) already shipped. ## How it was tested N/A — design docs only. `check-doc-refs` clean. ## Checklist - [x] Design-first: architecture + risk + phased DoD, before code - [x] ModernUO reference (SurfaceStack) preserved; external review credited + kept in-repo - [x] Our DesktopGL/SM3 depth constraint (#240) folded in as the gating risk - [ ] Implementation — NOT started; the depth-spike is the next buildable gate Design update for #268.

panda added 1 commit

2026-08-03 23:41:39 +02:00

docs(design): render architecture — explicit cliff walls + iso depth buffer + edge-aware smoothing + SurfaceStack (supersedes surfaces-as-tiles/overlay); flag DesktopGL depth risk

ci / Lua content lint (pull_request) Successful in 11s

Details

ci / Lint & Test (pull_request) Successful in 4m44s

Details

dd5c6b742a

panda added 1 commit

2026-08-03 23:54:37 +02:00

spike(render): P2 depth GATE passes — off-screen RT Depth24 depth-tests single-pass on DesktopGL/SM3

ci / Lua content lint (pull_request) Successful in 22s