Tinyworld Mesh Terrain

---
name: tinyworld-mesh-terrain
description: Use when changing the Mesh Terrain sculptor — the opt-in voxel-block landscape designer that paints per-voxel materials and pull/push-sculpts flat-topped blocks, then keeps the block mesh as the rendered terrain. Module engine/world/46-mesh-terrain.js.
---

# Tiny World Mesh Terrain Sculptor

A self-contained, opt-in landscape designer in `engine/world/46-mesh-terrain.js`.
Lay a fine voxel grid over the home board, paint per-voxel materials, and
pull/push voxels up and down. The result is **flat-topped voxel blocks**, not a
smooth/curved surface, and it stays that way — Apply keeps the block mesh as the
terrain instead of baking into per-tile `setCell`.

## The model is per-voxel blocks (not a smooth heightfield)

- `cellH`: `Float32Array(N*N)` — the flat-top height of **each voxel**. There are
  no shared/interpolated vertices, so tops never slope into curves. Sculpting
  clamps `cellH` to `[0, MAX_HEIGHT]` — ground (0) is the floor, so you build up
  from the ground and cannot dig below it.
- `mats`: `Uint8Array(N*N)` — per-voxel material index into `MATERIALS`
  (ids match real terrain names: grass/sand/water/stone/dirt/snow/lava).
- `N = GRID * effVpt` voxels per side; `effVpt` is clamped so `N <= MAX_N` (96).
- Render (`rebuildGeometry`): each voxel writes a flat **top quad** at its height
  plus **vertical step-walls** only on edges where a neighbour (or the board
  boundary) is lower. The real-material path greedily merges flat same-material
  top rectangles that have no exposed drop edge, then leaves exposed bevels and
  walls per-voxel so the chunky silhouette stays intact. Boundary walls drop to
  a base skirt below the lowest block. Geometry is non-indexed and writes from
  **scalars** via `quad()`/`wv()` (no per-quad array allocation). Sculpt/paint
  edits don't rebuild inline — they call `scheduleRebuild()`, which coalesces to
  **one rebuild per animation frame** (rAF); `flushRebuild()` forces the final
  frame on pointer-up and `cancelScheduledRebuild()` runs on teardown. This keeps
  a fast drag from forcing multiple full-board rewrites per frame (engine perf
  budget).
- Preserved sunken board cells (`water`/`stone`) are mesh holes so the underlying
  board terrain shows through. Treat those holes as open/low neighbours when
  computing adjacent wall panels; otherwise deleting adjacent blocks leaves
  see-through missing side faces around the cutout.
- Materials use the app's REAL terrain shaders. The geometry is laid out grouped
  by terrain (all tops, then all sides) and `surfaceMesh.material` is a parallel
  array: tops get `terrainVoxelMaterials(t).base`, sides get
  `terrainRiserMaterial(t)` (the soil/stone risers). Exception: `stone` reads as
  grainy NOISE rock via `rockNoiseMat` — a grey-tinted clone of the sand material
  (`M.sand`/`texSand`) — because both the masonry finish (`M.stone`) and the
  blocky stone pattern (`M.rock`/`texStone`) look like built walls, not rock. Those materials compute UVs
  from world position in-shader (`applyWorldUVs` `onBeforeCompile`), so the blocks
  pick up the same textures/shading as the rest of the world — **do not** hand-roll
  UVs. Materials are used via double-sided clones (`dsClone`) that copy
  `onBeforeCompile`/`userData`/`customProgramCacheKey` across (Three
  `Material.clone` drops `onBeforeCompile`), cached by uuid so there is no
  per-frame churn; clones are disposed on teardown. If `M`/`terrainVoxelMaterials`/
  `terrainRiserMaterial` are missing, it falls back to a single vertex-coloured
  `flatShading` mesh (fixed per-voxel stride + degenerate fill for absent walls).

## Sculpt / paint

- Entry point: the Terrain toolbar flyout includes a `Mesh Terrain` action tool
  (`id: mesh-terrain`) that opens `window.__tinyworldMeshTerrain.open()`. Keep it
  as an action, not a paint brush.
- **Sculpt**: pressure-brush controls. Hold/drag **left mouse** to raise and
  **right mouse** to lower under the brush; right-click context menu is suppressed
  on the terrain canvas while editing. The brush applies
  `SCULPT_PRESSURE_RATE * dt * falloff(dist/brushRadius)` continuously while the
  button is held, so a stationary press keeps raising/lowering and dragging paints
  height across the surface. Every voxel stays flat at its own height.
- **Paint**: drag left mouse to set every voxel whose centre is within
  `brushRadius`.

## Apply keeps blocks — it does NOT bake into world tiles

- Persistence is **Apply-only**. Edits (sculpt drags, paint, Flatten, resolution
  changes) mutate in-memory state and are NOT written to storage; `applyDesign()`
  is the only writer (`saveDesign()`), and it also snapshots the design in memory
  (`captureApplied()` -> `appliedSnap`). This is what lets Cancel truly discard.
- `applyDesign()` sets `applied = true`, snapshots + persists, hides the flat home
  **tiles** (`setHomeMeshesVisible(false)` toggles only `m.tile`, never `m.object`,
  so placed objects stay visible), and leaves the block mesh in the scene. There
  is **no** `setCell` bake, so there are no full GRID tiles afterward.
- `cancelEdit()` reverts from the in-memory `appliedSnap` (recovering correctly
  even if the resolution changed mid-edit); if nothing was ever applied it
  disposes the mesh, restores the flat tiles, and `clearDesign()`s any draft.
- `removeDesign()` deletes the block terrain, restores the flat tiles, clears
  `appliedSnap`, and `clearDesign()`s storage.
- Boot `restoreApplied()` rebuilds an applied design and re-hides home tiles
  (with delayed retries + a `tinyworld:world-changed` listener, because world
  tiles can render slightly after this module boots).

## Programmatic generation (used by the "Realistic" landscape generator)

- `window.__tinyworldMeshTerrain.generate(sample, opts)` fills the voxel grid from
  an external per-voxel sampler and displays it as a **transient** block overlay
  (hides the flat home tiles like an applied design, but does NOT persist unless
  `opts.persist`). `sample(cellX, cellZ)` gets board-cell coords in `[0, gridAtEnter]`
  and returns `{ material: 'grass'|'sand'|…, level: 1.. }` (level → `cellH = (level-1)*opts.levelStep`)
  or `{ material, height }` (world-Y directly). It exits the manual editor if open.
- `clearGenerated()` tears the transient overlay down and restores the flat tiles
  (no-op if none, or if the user opened it for editing). `isGenerated()` reports state.
- `sampleWorld(wx, wz)`, `sampleCell(x, z, opts)`, and
  `anchorForCell(x, z, opts)` expose the visible block surface for runtime
  grounding. `anchorForCell` samples the center plus optional cardinal probes
  (`offsetX`, `offsetZ`, `radius`) and returns the highest support. Consumers must
  fall back to LandscapeEngine/tile heights when it returns `null` (for example
  over preserved water/stone holes or outside the home board).
- The Generate modal's **Realistic** landscape style routes here:
  `applyRealisticVoxelLandscape()` (in `engine/world/27-landscape-engine.js`) samples
  `sampleLandscapeCell()` (the same procedural height/biome the old realistic
  LandscapeEngine used) at voxel resolution, with `levelStep = LANDSCAPE_VOXEL_LEVEL_STEP`
  (1.12, matching the landscape-mode tile step so block tops align with the hidden
  tiles objects sit on). It is driven from the generate handler (module 28) and the
  reload path (module 29, when `useLandscapeEngine && landscapeMeshStyle==='realistic'`),
  and torn down by `disposeLandscapeMesh()` → `clearGenerated()`. Realistic keeps
  `landscapeMeshMode = false`; the world save (cells + seed + style) is the single
  source of truth, so reload regenerates the blocks deterministically — the overlay
  itself is not persisted in `tinyworld:meshTerrain:*`.
- A generated overlay is editable: opening the editor on top of it lets the user
  tweak and **Apply** (which turns it into a real persisted design; `generatedActive`
  clears).

## Why it is structured this way (do not regress)

- **One IIFE, no top-level names** → dodges the `tools/check.js` cross-file
  duplicate-declaration guard; keep new code inside the IIFE.
- **Own localStorage keys** (`tinyworld:meshTerrain:v2` design,
  `tinyworld:meshTerrain:prefs:v1` prefs). The world schema and embedded
  `WORLD_SCHEMA` are untouched, so schema parity stays green. Do not persist this
  feature in the world save.
- **Height consumers ask the mesh first, then fall back**. Current wired consumers
  include object/extras placement (`17-tile-renderers.js`), selection/hover
  height (`12-selection-tool.js`, `18-scene-pick-xr.js`), crowd/vehicle grounding
  (`11-vehicle-crowd.js`, `10-world-data.js`), and Tinyverse avatar grounding
  (`47-worlds-room.js`). Keep this one-way: consumers sample the overlay; they do
  not mutate or bake it.
- **CSS injected from JS**; guarded `styles/tiny-world.css` is never edited.
- **Window capture-phase pointer handling** that engages only when
  `e.target === renderer.domElement` and the ray hits the surface, then
  `stopPropagation()`. Otherwise events flow through so orbit/zoom and UI clicks
  keep working. Handlers attach on open, detach on leave.

## Known limitations / next steps

- The block terrain is still a separately persisted overlay. Object/avatar
  grounding can sample it, but the world save/version schema does not yet store a
  mesh-terrain payload for published islands.
- Mesh Terrain is visual/grounding data only for the economy. If a sculpted
  formation should become harvestable, project it to ordinary cells or object
  cells with explicit `economy` metadata; do not infer resource payouts from
  shader/material pixels.
- Home-tile hiding can race world (re)renders; it re-hides on
  `tinyworld:world-changed` and via short boot timers.

## QA checklist (needs a browser — npm test cannot verify rendering)

- Open the editor: a flat grid of grass blocks covers the board; flat tiles hide.
- Sculpt drag raises/lowers **flat-topped blocks** with vertical step-walls —
  no sloped/curved surfaces; neighbours taper with the brush.
- Tops use the real terrain textures/shaders (grass, water flow, stone masonry,
  etc.); side walls use the soil/stone riser materials. If they render as flat
  plain colours, the real-material wiring fell through to the fallback — check
  `M`/`terrainVoxelMaterials`/`terrainRiserMaterial` are defined at open time.
- Paint lays materials per voxel.
- Orbit/zoom still work on empty-space drag / scroll; toolbar clicks not hijacked.
- Apply keeps the blocks (no full tiles reappear); reload restores them.
- Cancel reverts; Remove deletes the blocks and restores the flat tiles.