Tinyworld Mesh Terrain

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