feat(client): terreno 3D — copertura consapevole della quota e ricostruzione in background #273

Closed

panda wants to merge 51 commits from design/3d-terrain into main

pull from: design/3d-terrain

merge into: marco:main

marco:main

marco:renovate/opentelemetry-dotnet-monorepo

marco:renovate/sixlabors.imagesharp-4.x

marco:renovate/sonaranalyzer.csharp-10.x

marco:renovate/dotnet-monorepo

marco:renovate/roslynator.analyzers-4.x

marco:fix/blend-knows-a-bank

marco:docs/rendering-open-problems

marco:feat/shaped-cutaway

marco:spike/confine-unwalkable-blend

marco:fix/sprite-depth

marco:feat/p2a-solid-terrain

marco:feat/relief-overlay-occlusion

marco:feat/cliff-face-legibility

marco:renovate/patch-dependencies

marco:chore/sonaranalyzer-10.30

marco:feat/server-compact-worldmap

marco:feat/world-new-biomes

marco:fix/biome-seams

marco:feat/vitals-hud

marco:fix/marsh-creature-parity

marco:feat/biome-props

marco:feat/world-terrain

Conversation 1 Commits 51 Files changed 162 +10965 -241

panda commented 2026-08-06 12:43:18 +02:00

Collaborator

Copy link

Summary

Il terreno passa al 3D vero, e questa tornata chiude i due problemi emersi camminando sull'asterra: "ad esempio qui dovrebbe esserci della lava" — un lago di lava autorizzato che a schermo era nero — e "è qualcosa nel mesh perché camminando in pendenza lo sfondo cambia di continuo a seconda di dove ci si muove, anche se magari è monobioma come la pendice del vulcano".

Erano due sintomi di una causa sola, in due punti distinti.

Primo: la camera segue il giocatore alla sua posizione disegnata, che contiene già il sollevamento -z*ZScale. I due punti che riconvertivano quella posizione in celle di mappa usavano l'inverso piatto, quindi nominavano le celle a quota 0 che finiscono sugli stessi pixel — 86 celle di distanza a z 237. La finestra dei biomi veniva costruita attorno a un'altra zona della mappa: la lava non veniva mai campionata, e siccome l'errore è proporzionale a z, ogni passo in salita lo spostava.

Secondo: la mesh veniva disegnata su un rettangolo più largo di quello per cui esistevano dati di bioma e rilievo. Nel mezzo i sampler bloccavano al bordo — niente texture, ombreggiatura piatta — e quel bordo si spostava a ogni ricostruzione della finestra. Da qui TerrainWindow, che diventa l'unica autorità su quali celle vanno coperte: mesh e dati derivano da lì e non possono più divergere.

I margini di quota sono asimmetrici perché è la forma giusta, non un'ottimizzazione: con screenY = (x+y)*TileHeight/2 - z*ZScale, il terreno entra in vista da +x+y solo se sta sopra il piano della camera, e da -x-y solo se sta sotto.

Coprire tutto il disegnato costava però 300-500 ms di ricostruzione sul thread di render. Quel lavoro passa a un worker cancellabile con un loader generation-safe; il thread di render fa solo lo scambio delle texture. La misura chiave: adottare una finestra costa ora 1 ms.

Infine le statiche, cullate con padding dimensionato solo sullo sprite e senza termine di quota: dal fondovalle il vulcano risultava correttamente texturizzato e completamente calvo.

Screenshots / recording

Rotta cratere-valle, database fresco, cinque punti diagnostici. Nessuna fascia grigia e nessun bordo diagonale mobile in nessuno dei cinque.

punto	tile	quota	vista
1	7511,4197	234
2	7505,4191	-
3	7499,4185	-
4	7490,4176	-
5	7473,4163	159

Comandi (docs/debug-harness.md), con il database azzerato prima di just dev:

login test
key Enter / type /tp 7511 4197 / key Enter
move northwest x6  ->  screenshot        (ripetuto fino al quinto punto)

How it was tested

• 1032 test, tutti verdi; IsoMmo.Client.Core.Tests 292.
• Un oracolo di proiezione indipendente (TerrainWindowOracleTests) decide la visibilità di una cella dall'equazione di proiezione, senza chiamare le funzioni sotto test: senza di lui un errore di segno nel margine renderebbe sbagliati insieme DrawnBounds e Required, e ogni test di contenimento passerebbe comunque. È il test che ha trovato il buco del mezzo-rombo.
• Verifica per mutazione su ogni regola di concorrenza del loader: rotta la riga che la fa rispettare, un test nominato deve fallire. Idem per i checkpoint di cancellazione e per il pad geometrico.
• Misure di frame sulla rotta a cinque punti, database fresco, senza screenshot dentro il campione (la codifica PNG sta sul thread di render e falsava il picco): p50 16,2-16,7 ms · p95 21,6-22,9 · p99 24,5-28,3 · max 29,9-37,9. Gate p99 <= 2x mediana: 28,3 <= 33,5. Build bloccanti durante il cammino: 0. snapshot 13-14 ms · build 400-529 ms · upload 1 ms.

Limiti noti, dichiarati

• I test di cancellazione inchiodano che esiste un checkpoint dopo la materializzazione, non che ce n'è uno per ogni passaggio: la seconda è una proprietà di latenza e non ha un punto d'iniezione deterministico senza dipendere dal tempo.
• Una finestra completata che non è più safe ma copre ancora viene scartata anziché adottata. Serve una deriva da teleport (~80 celle/s contro le ~9 di una corsa) e di norma produce comunque una richiesta asincrona, non uno stallo. Registrato come follow-up.
• Il ciclo delle statiche passa da ~9,8k a ~75k celle per frame: il margine è corretto e restringerlo sarebbe un difetto. Il seguito è il min/max-Z per chunk, fuori ambito qui.
• Il personaggio può finire dietro al terreno su un versante rivolto verso la camera: lo sprite è un cartellone il cui piede sta sul vertice della mesh e viene testato in profondità contro quella stessa superficie. Precede questo ramo (i file che governano la profondità sono invariati) e va risolto con un bias di profondità, in una modifica a sé.

Checklist

• just lint passa (CSharpier + analyzer, zero warning)
• just test è verde
• L'intera soluzione compila (client e tool inclusi), anche in Release
• Multi-piattaforma preservato: solo Task/CancellationToken e Texture2D.SetData, nulla di specifico per OS
• Test aggiunti/aggiornati per questa modifica
• Issue collegata: da associare se ne esiste una per il terreno 3D

## Summary Il terreno passa al 3D vero, e questa tornata chiude i due problemi emersi camminando sull'asterra: **"ad esempio qui dovrebbe esserci della lava"** — un lago di lava autorizzato che a schermo era nero — e **"è qualcosa nel mesh perché camminando in pendenza lo sfondo cambia di continuo a seconda di dove ci si muove, anche se magari è monobioma come la pendice del vulcano"**. Erano due sintomi di una causa sola, in due punti distinti. **Primo**: la camera segue il giocatore alla sua posizione *disegnata*, che contiene già il sollevamento `-z*ZScale`. I due punti che riconvertivano quella posizione in celle di mappa usavano l'inverso piatto, quindi nominavano le celle a quota 0 che finiscono sugli stessi pixel — 86 celle di distanza a `z 237`. La finestra dei biomi veniva costruita attorno a un'altra zona della mappa: la lava non veniva mai campionata, e siccome l'errore è proporzionale a `z`, ogni passo in salita lo spostava. **Secondo**: la mesh veniva disegnata su un rettangolo più largo di quello per cui esistevano dati di bioma e rilievo. Nel mezzo i sampler bloccavano al bordo — niente texture, ombreggiatura piatta — e quel bordo si spostava a ogni ricostruzione della finestra. Da qui `TerrainWindow`, che diventa **l'unica autorità** su quali celle vanno coperte: mesh e dati derivano da lì e non possono più divergere. I margini di quota sono **asimmetrici** perché è la forma giusta, non un'ottimizzazione: con `screenY = (x+y)*TileHeight/2 - z*ZScale`, il terreno entra in vista da `+x+y` solo se sta *sopra* il piano della camera, e da `-x-y` solo se sta *sotto*. Coprire tutto il disegnato costava però 300-500 ms di ricostruzione sul thread di render. Quel lavoro passa a un worker cancellabile con un loader generation-safe; il thread di render fa solo lo scambio delle texture. **La misura chiave: adottare una finestra costa ora 1 ms.** Infine le statiche, cullate con padding dimensionato solo sullo sprite e senza termine di quota: dal fondovalle il vulcano risultava correttamente texturizzato e completamente calvo. ## Screenshots / recording Rotta cratere-valle, database fresco, cinque punti diagnostici. Nessuna fascia grigia e nessun bordo diagonale mobile in nessuno dei cinque. | punto | tile | quota | vista | | --- | --- | --- | --- | | 1 | 7511,4197 | 234 |  | | 2 | 7505,4191 | - |  | | 3 | 7499,4185 | - |  | | 4 | 7490,4176 | - |  | | 5 | 7473,4163 | 159 |  | Comandi (`docs/debug-harness.md`), con il database azzerato prima di `just dev`: ``` login test key Enter / type /tp 7511 4197 / key Enter move northwest x6 -> screenshot (ripetuto fino al quinto punto) ``` ## How it was tested - **1032 test**, tutti verdi; `IsoMmo.Client.Core.Tests` 292. - Un **oracolo di proiezione indipendente** (`TerrainWindowOracleTests`) decide la visibilità di una cella dall'equazione di proiezione, senza chiamare le funzioni sotto test: senza di lui un errore di segno nel margine renderebbe sbagliati *insieme* `DrawnBounds` e `Required`, e ogni test di contenimento passerebbe comunque. È il test che ha trovato il buco del mezzo-rombo. - **Verifica per mutazione** su ogni regola di concorrenza del loader: rotta la riga che la fa rispettare, un test nominato deve fallire. Idem per i checkpoint di cancellazione e per il pad geometrico. - **Misure di frame** sulla rotta a cinque punti, database fresco, senza screenshot dentro il campione (la codifica PNG sta sul thread di render e falsava il picco): p50 16,2-16,7 ms · p95 21,6-22,9 · p99 24,5-28,3 · max 29,9-37,9. Gate `p99 <= 2x mediana`: **28,3 <= 33,5**. Build bloccanti durante il cammino: **0**. snapshot 13-14 ms · build 400-529 ms · **upload 1 ms**. ### Limiti noti, dichiarati - I test di cancellazione inchiodano che *esiste* un checkpoint dopo la materializzazione, non che ce n'è uno per ogni passaggio: la seconda è una proprietà di latenza e non ha un punto d'iniezione deterministico senza dipendere dal tempo. - Una finestra completata che non è più *safe* ma **copre ancora** viene scartata anziché adottata. Serve una deriva da teleport (~80 celle/s contro le ~9 di una corsa) e di norma produce comunque una richiesta asincrona, non uno stallo. Registrato come follow-up. - Il ciclo delle statiche passa da ~9,8k a ~75k celle per frame: il margine è corretto e restringerlo sarebbe un difetto. Il seguito è il min/max-Z per chunk, fuori ambito qui. - Il personaggio può finire dietro al terreno su un versante rivolto verso la camera: lo sprite è un cartellone il cui piede sta sul vertice della mesh e viene testato in profondità contro quella stessa superficie. Precede questo ramo (i file che governano la profondità sono invariati) e va risolto con un bias di profondità, in una modifica a sé. ## Checklist - [x] `just lint` passa (CSharpier + analyzer, zero warning) - [x] `just test` è verde - [x] L'intera soluzione compila (client e tool inclusi), anche in Release - [x] Multi-piattaforma preservato: solo `Task`/`CancellationToken` e `Texture2D.SetData`, nulla di specifico per OS - [x] Test aggiunti/aggiornati per questa modifica - [ ] Issue collegata: da associare se ne esiste una per il terreno 3D

punto-3.png

2.6 MiB

punto-2.png

2.7 MiB

punto-4.png

2.6 MiB

punto-5.png

2.5 MiB

punto-1.png

2.8 MiB

panda added 51 commits 2026-08-06 12:43:18 +02:00

docs(design): 3D terrain with a fixed isometric camera — real Z instead of simulated, 2D sprites preserved dbfbd4d65d

docs(plan): 3D terrain de-risk spike — shared camera + mesh maths, real map, Z-scale gate 171001d2f5

feat(render): IsoCamera — shared 3D isometric camera maths derived from the UO projection 4f34ddfc52

feat(render): TerrainMesh3D — world-space terrain mesh with averaged vertex normals ef726f00a1

spike(render): 3D terrain on the real map — ortho iso camera, real normals, depth + billboard d7f2c90790

docs(design): 3D terrain gate PASSED — real verticality confirmed, owner picks Z scale x16 d1800b0c43

spike(render): 3D terrain textured with the real biome art from the asset pack 04ef006d19

docs(design): enumerate the existing visual refinements as a Phase 1 carry-over checklist 9bcbb5ead5

feat(render): 3D terrain in the client — unified projection at Z scale 16, real-normal lighting, height-aware picking 450f08818d

fix(render): ray-march tile picking + movement test suite over procedural terrain with peaks 51c79fee37

docs(design): real Z exposes a walkability gap — steepness/gradient, not just per-step height b0c5e9be00

feat(movement): sustained-climb budget — a route's steepness is limited, not just one step dcbc8c3758

feat(render): projection-aware tiling so cliff faces show rock instead of a stretched smear 0976fd500c

docs(design): record the entity-occlusion approach and its shared-depth-mapping pitfall bae2f5f869

feat(render): entities test the terrain depth buffer — a cliff now hides what is behind it dd290df964

fix(roads): grade roads to the sustainable gradient, not the single-step limit — they were unwalkable by construction 8be3067764

feat(editor): DEBUG automation channel — script the real editing tools reproducibly; rebuild the test mountain and its spiral road f19032b58c

feat(editor): road shoulders — blend terrain beside the carriageway so a road is not a knife-edge causeway 77d533e4ca

feat(render): mobiles join the shared depth buffer — a character behind a mountain is hidden by it e19df07370

fix(editor): densify the road stroke — a fast drag painted disconnected pits instead of a road a2d99472ec

docs(design): landform editor — parametric terrain tools, rotatable/switchable views, editable traces 74d1575e28

docs(plan): landform editor — picking-first, then views, landforms, traces, naturalisation 650a69e9e5

feat(editor): EditorCamera — free orbit camera maths, orthonormal at every angle 76ad7f83fb

feat(editor): MeshPicker — ray-cast picking correct at any camera rotation d7d33b9a31

feat(editor): switchable top-down / orbiting 3D view, with the height window read in bulk 8c5379763a

perf(editor): pick by testing only the cells the view ray crosses — exact, and bounded by the ray not the viewport ba1c1418e0

perf(editor): keep the terrain mesh on the GPU and stop rebuilding it while orbiting 5756508f9f

feat(editor): parametric landforms with a flank profile and a reported max gradient f18c7a598b

feat(editor): landform tool — place a shaped hill or basin, with its climbability reported 47e739914c

feat(editor): roads become re-bakeable Traces, shared by the GUI and the automation channel 699cb57f97

feat(editor): naturalisation — thermal erosion and deterministic seeded roughening 9a24e1af64

feat(editor): warn on exit with unsaved chunks instead of discarding them 1e09538dc9

fix(editor): landform is one placement per click, with a live preview of footprint and profile 8f36192daa

feat(editor): --tool flag for scripted capture; ASCII-safe UI strings (ImGui has no em-dash glyph) 761dda86ce

fix(client): cull and blend around the camera's flat focus, not its lifted position ... be23dedfdb

The camera follows the player at their DRAWN position, which carries -z*ZScale. Both
places that invert it back to map cells used the flat inverse, so on high ground they
named the Z-0 cells projecting to the same pixels - 86 cells per axis away at z 237,
ZScale 16. The ground blend window was therefore built around another region entirely
(volcano lava never sampled, the summit rendered as clamped edge weights) and statics
were culled around it too; every step that changed z moved the error, which is why the
ground kept shifting while walking a slope.

IsoCamera.FlatFocus undoes the lift; Camera2D carries the focus height so both callers
invert the point the camera actually looks at.

docs(design): terrain window must cover what the mesh draws (async rebuild) 629c1ec86a

docs(plan): terrain window coverage implementation plan eac268b5e7

docs(plan): merge the reviewed terrain window coverage plan 8ee96d8266

feat(client): define and prove the terrain coverage contract 0396170c67

fix(client): derive the tile-footprint pad from geometry f4579ce7ef

fix(client): derive mesh and blend data from one window b2e690f204

refactor(client): snapshot and cancellable terrain field inputs 200217b5e8

fix(client): bound cancellation latency in the terrain field builders 98f499f7cc

perf(client): add a generation-safe terrain window loader 395265f635

fix(client): stop the terrain loader swallowing a foreign cancellation a15a5b9438

perf(client): rebuild terrain windows without stale adoption c2669d8971

fix(client): guard the empty viewport and pin the relief read budget dbac3a57ba

fix(client): statics on distant high ground are no longer culled 3b42f35749

fix(client): skip the 3D terrain pass when nothing is on screen c71b91c654

test(client): measure terrain window frame costs 1ec66cd827

fix(client): scope the height margins and pin the cancellation checkpoints ... 8cfdad70ff

Fixes six review findings on the terrain-window change plus a stale doc
passage: DrawGround no longer inherits statics-only height margins it
cannot use, the relief read-margin comment now shows the composed
(displayZ + relief) 24-cell reach instead of the outer 15 and corrects
the WideSigma ceiling, cancellation is pinned with tests that cancel on
materialisation's last read (verified by mutation), dead BlockingBuilds
telemetry is removed, a redundant Cancel() before BuildNow is dropped,
_buildMs is no longer static, and architecture.md now describes the
cancellable background rebuild instead of a synchronous one.

panda referenced this pull request 2026-08-06 12:50:19 +02:00

fix(client): copertura del terreno consapevole della quota, ricostruita in background #274

panda commented 2026-08-06 12:50:37 +02:00

Author

Collaborator

Copy link

Sostituita da #274: questo ramo portava una seconda copia del codice 3D che #272 aveva già schiacciato in main, quindi il conflitto non era risolvibile in modo pulito. #274 contiene lo stesso lavoro replicato su main senza conflitti.

Sostituita da #274: questo ramo portava una seconda copia del codice 3D che #272 aveva già schiacciato in main, quindi il conflitto non era risolvibile in modo pulito. #274 contiene lo stesso lavoro replicato su main senza conflitti.

panda closed this pull request 2026-08-06 12:50:37 +02:00

panda referenced this pull request from a commit 2026-08-06 12:56:02 +02:00

fix(client): copertura del terreno consapevole della quota, ricostruita in background (#274)

All checks were successful

Hide checks

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

Details

ci / Lint & Test (pull_request) Successful in 5m20s

Required

Details

Pull request closed

Please reopen this pull request to perform a merge.

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

alpha:wave-0

Alpha — de-risk, do first

  

alpha:wave-1

Alpha — foundations

  

alpha:wave-2

Alpha — features

  

alpha:wave-3

Alpha — refine & stabilize

  

area:assets

Art, sound, the assets.isoa pack and its tools

  

area:combat

Combat system, weapons, balance

  

area:ecology

Natural nodes, harvesting, spawners

  

area:infra

CI, analyzers, dependencies, performance, ops

  

area:render

Client rendering: terrain mesh, shading, sprites, cutaway

  

area:scripting

Lua content scripting host and API

  

area:ui

Client UI, HUD, input, targeting

  

area:world

World model, map format, editor, topology

  

enhancement

New feature or improvement

  

epic

Milestone-level roadmap epic

  

migration

Platform or framework migration

  

post-alpha

Explicitly out of the alpha scope

  

roadmap

Roadmap tracker

  

tech-debt

Accepted debt to revisit

  

type:bug

Something is wrong and reproducible

  

type:chore

Housekeeping: no behaviour change

  

type:design

Design to agree before any implementation

No labels

alpha:wave-0

alpha:wave-1

alpha:wave-2

alpha:wave-3

area:assets

area:combat

area:ecology

area:infra

area:render

area:scripting

area:ui

area:world

enhancement

epic

migration

post-alpha

roadmap

tech-debt

type:bug

type:chore

type:design

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

marco/IsoMmo!273

No description provided.