TerrainRenderer

Turns a loaded world into terrain meshes, keeps the animated ones current, builds reliefs near the camera and draws them in the right passes.

Purpose

One TerrainRenderer is built per loaded world (and rebuilt when the world changes in a way it cannot patch). The constructor walks every cell of the World and sorts it into a mesh by what its block definition and its tile's texels call for: the static opaque mesh, the cut-out mesh (alpha-tested sprites), the static blended mesh (faint tiles), the grass-top overlay, the animated and water cells (rebuilt when the animation phase changes), and the lava, lightning and wind cells (each frame of their cycle built once and cached). Cells drawn as 3D models are left out and listed by ModelCells(). The meshes are uploaded as GpuMeshParts, split when one buffer would be too big (MeshParts.hpp).

The class holds GPU resources and needs a GraphicsDevice, so it is not unit-tested itself; the pure parts it relies on are (see Tests).

Collaborators

• World (input) and BlockDefinitionRegistry (render mode, texture icon, animation, water).
• TileAtlas (UVs on the padded terrain sheet) and TileCoverage (opaque, cut-out or translucent per icon).
• Geometry helpers: DirectionalCubeTiles, InnerPillarBoxTiles, ThinBarTiles, InnerFlatPlateTiles, BrickEdges, WaterSurface, LavaSurface, BoltMesh, TerrainModelCells.
• TerrainReliefTable (TerrainRelief.hpp) for the reliefs; TerrainGiSettings (TerrainGi.hpp) for Ultra's baked light.
• WorldRenderer draws it each frame and passes the effects' shaders as a TerrainShading.
• GalaxyEggbertGame creates it, calls Update() each tick and patches or rebuilds it in RefreshTerrainMeshIfChanged().

Public API

TerrainShading (same header) carries the effects' replacement shaders: occluded, lit, cutout, lava, water and Ultra's reliefGi callback; a null member keeps the stock effect.

How it is used

Built at load (src/GalaxyEggbertCNA/GalaxyEggbertGameLoad.cpp):

terrainRenderer_ = std::make_unique<TerrainRenderer>(device, worldRuntime_.GetWorld(), terrainTileAtlas_, tileCoverage_,
                                                     terrainDrawSecret_, StillModelIcons(), TerrainReliefs(),
                                                     TerrainOcclusionWanted(), TerrainGiWanted());
...
terrainRevision_ = worldRuntime_.GetWorld().blockRevision();

After a tick changed blocks, the cheap path is tried first:

const auto changes = world.blockChangesSince(terrainRevision_);
if (TerrainDrawSecret() == terrainDrawSecret_ &&
    terrainRenderer_->PatchModelCells(world, changes, StillModelIcons(), terrainDrawSecret_, tileCoverage_))
{
    terrainRevision_ = world.blockRevision();
    return;
}
... // otherwise build a new TerrainRenderer and call rebuilt->AdoptReliefs(*terrainRenderer_)

• Draw order matters: DrawOpaque() before the models, DrawTransparent() after them, or water does not cover what lies in it (OR-0052).
• Reliefs are off unless the Setup's "3D terrain" is on (or GALAXY_TERRAIN_RELIEF=1); without UpdateRelief() every chunk stays textured cubes.
• Brick edge pieces 262, 263 and 283 are drawn ragged only at a wall's open end (AppendRaggedBrick); the count is RaggedBrickCount().

Tests

• VerifyTileFaces (tools/VerifyTileFaces.cpp): directional-cube faces, water exterior faces, the padded atlas, and that incremental model-cell patching (PatchTerrainModelCells, behind PatchModelCells) equals a full scan.
• VerifyTileCoverage: tile classification of object-m.png and when a brick edge piece is ragged (BrickEdges::ShapeFor).
• VerifyTerrainLighting, VerifyTerrainAnimDivisor: face brightness and the per-type animation pace.
• VerifySceneEffects, VerifyUltra: the occlusion and GI bakes' rules.
• The drawn result: golden frames (tools/verify_golden_frames.sh) and tools/verify_lava_depth.py, manual, with a display.

Related pages

• Rendering — where the terrain sits in the frame.
• WorldRenderer, TileAtlas, World, BlockDefinitionRegistry.