erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(core+app): per-cell terrain texture blending (Phase 3c.4)

Browse source 
The visual-win commit that wires up the Phase 3c.1/.2/.3 building blocks:
Holtburg's terrain now uses AC's real per-cell texture-merge blend
(base + up to 3 terrain overlays + up to 2 road overlays, with alpha
masks from the alpha atlas) instead of the flat per-vertex single-layer
atlas lookup that preceded it.

Geometry rewrite:
  - New TerrainVertex struct (40 bytes): Position(vec3) + Normal(vec3) +
    Data0..3 (4x uint32 packed blend recipe)
  - LandblockMesh.Build is now cell-based: iterates 8x8 cells instead of
    the old 9x9 vertex grid, emits 6 vertices per cell (two triangles),
    384 total vertices per landblock
  - For each cell: extract 4-corner terrain/road values → GetPalCode →
    BuildSurface (cached across landblocks via a shared surfaceCache) →
    FillCellData → split direction from CalculateSplitDirection → emit
    6 vertices in the exact gl_VertexID % 6 order WorldBuilder's vertex
    shader expects
  - Per-vertex normals preserved via Phase 3b central-difference
    precomputation on the 9x9 heightmap, interpolated smoothly across
    the cell (we deliberately didn't adopt WorldBuilder's dFdx/dFdy
    flat-shade approach — Phase 3a/3b user-tuned lighting was worth
    keeping)

Renderer rewrite:
  - TerrainRenderer VAO: vec3 Position, vec3 Normal, 4x uvec4 byte
    attributes for Data0..3. The uvec4-of-bytes read pattern matches
    Landscape.vert so the ported shader math stays byte-for-byte
    identical to WorldBuilder's.
  - Binds both atlases: terrain atlas on unit 0 (uTerrain), alpha atlas
    on unit 1 (uAlpha)

Shader rewrite (ports of WorldBuilder Landscape.vert/.frag, trimmed):
  - terrain.vert: unpacks the 4 data bytes + rotation bits, derives the
    cell corner from gl_VertexID % 6 + splitDir, rotates the cell-local
    UV per overlay's rotation field, and computes world-space normal
    for the fragment shader
  - terrain.frag: maskBlend3 three-layer alpha-weighted composite for
    terrain overlays, inverted-alpha road combine, final composite
    base * (1-ovlA)*(1-rdA) + ovl * ovlA*(1-rdA) + road * rdA. Phase
    3a/3b directional lighting applied on top (SUN_DIR, AMBIENT=0.25,
    DIFFUSE=0.75, in sync with mesh.frag).
  - Editor uniforms (grid, brush, unwalkable slopes) deliberately
    omitted — not applicable to a game client
  - Per-texture tiling factor hardcoded to 1.0 for now (WorldBuilder
    reads it from uTexTiling[36] uploaded from the dats); one tile per
    cell = 8 tiles per landblock-side, slightly coarser than the old
    ~2x-per-cell tiling. Tunable via the TILE constant if needed.

TerrainAtlas grew parallel TCode/RCode lists (CornerAlphaTCodes,
SideAlphaTCodes, RoadAlphaRCodes) so TerrainBlendingContext can be
built without the mesh loader touching the dats directly.

GameWindow builds a TerrainBlendingContext once, shares a Dictionary
<uint, SurfaceInfo> surfaceCache across all 9 landblocks. Output:
"terrain: 137 unique palette codes across 9 landblocks" — avg ~15
unique per landblock, cache reuse healthy.

LandblockMeshTests rewritten for 384-vertex layout. 77/77 tests green.
Visual smoke run launches clean: no shader compile/link errors, no
GL warnings, terrain renders to the screen.

User visual verification is the final acceptance gate for Phase 3c.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-04-11 14:02:15 +02:00
parent a6cd56663f
commit e0dfecdf23
8 changed files with 610 additions and 170 deletions
Download patch file Download diff file Expand all files Collapse all files

169
tests/AcDream.Core.Tests/Terrain/LandblockMeshTests.cs
View file

@ -8,15 +8,21 @@ namespace AcDream.Core.Tests.Terrain;
public class LandblockMeshTests
{
/// <summary>
/// Synthetic height table that mirrors Phase 1's simplified "* 2.0f" scale so
/// the existing tests continue to describe the same behavior. Real AC uses a
/// non-linear table from Region.LandDefs.LandHeightTable loaded at runtime.
/// Synthetic height table with a * 2.0f scale (mirrors Phase 1's ramp so
/// existing test intuition carries through the Phase 3c rewrite).
/// </summary>
private static readonly float[] IdentityHeightTable =
Enumerable.Range(0, 256).Select(i => i * 2f).ToArray();
private static readonly IReadOnlyDictionary<uint, uint> EmptyTerrainMap =
new Dictionary<uint, uint>();
private static TerrainBlendingContext MakeContext() => new(
TerrainTypeToLayer: new Dictionary<uint, byte> { [0u] = 0 },
RoadLayer: SurfaceInfo.None,
CornerAlphaLayers: Array.Empty<byte>(),
SideAlphaLayers: Array.Empty<byte>(),
RoadAlphaLayers: Array.Empty<byte>(),
CornerAlphaTCodes: Array.Empty<uint>(),
SideAlphaTCodes: Array.Empty<uint>(),
RoadAlphaRCodes: Array.Empty<uint>());
private static LandBlock BuildFlatLandBlock(byte heightIndex = 0)
{
@ -35,28 +41,31 @@ public class LandblockMeshTests
}
[Fact]
public void Build_FlatBlock_Produces81VerticesAnd128Triangles()
public void Build_FlatBlock_Produces384VerticesAnd128Triangles()
{
var block = BuildFlatLandBlock();
var cache = new Dictionary<uint, SurfaceInfo>();
var mesh = LandblockMesh.Build(block, IdentityHeightTable, EmptyTerrainMap);
var mesh = LandblockMesh.Build(block, 0, 0, IdentityHeightTable, MakeContext(), cache);
Assert.Equal(81, mesh.Vertices.Length);
// 64 cells × 6 vertices per cell = 384
Assert.Equal(384, mesh.Vertices.Length);
// Each cell emits 2 triangles = 6 indices, 64 cells → 384 indices (= 128 triangles)
Assert.Equal(128 * 3, mesh.Indices.Length);
}
[Fact]
public void Build_Vertices_Cover192x192WorldUnits()
public void Build_Vertices_CoverExactly192x192WorldUnits()
{
var block = BuildFlatLandBlock();
var cache = new Dictionary<uint, SurfaceInfo>();
var mesh = LandblockMesh.Build(block, IdentityHeightTable, EmptyTerrainMap);
var mesh = LandblockMesh.Build(block, 0, 0, IdentityHeightTable, MakeContext(), cache);
var minX = mesh.Vertices.Min(v => v.Position.X);
var maxX = mesh.Vertices.Max(v => v.Position.X);
var minY = mesh.Vertices.Min(v => v.Position.Y);
var maxY = mesh.Vertices.Max(v => v.Position.Y);
Assert.Equal(0.0f, minX);
Assert.Equal(192.0f, maxX);
Assert.Equal(0.0f, minY);
@ -67,73 +76,119 @@ public class LandblockMeshTests
public void Build_FlatBlock_AllVerticesSameZ()
{
var block = BuildFlatLandBlock(heightIndex: 10);
var cache = new Dictionary<uint, SurfaceInfo>();
var mesh = LandblockMesh.Build(block, IdentityHeightTable, EmptyTerrainMap);
var mesh = LandblockMesh.Build(block, 0, 0, IdentityHeightTable, MakeContext(), cache);
var zs = mesh.Vertices.Select(v => v.Position.Z).Distinct().ToArray();
Assert.Single(zs);
Assert.Equal(20.0f, zs[0]); // heightIndex 10 × IdentityHeightTable[10] = 20
}
[Fact]
public void Build_HeightValues_ScaleByTwo()
{
var block = BuildFlatLandBlock(heightIndex: 5);
var mesh = LandblockMesh.Build(block, IdentityHeightTable, EmptyTerrainMap);
// AC's Land::LandHeightTable scales height byte index by 2.0f for the simple ramp case.
Assert.Equal(10.0f, mesh.Vertices[0].Position.Z);
}
[Fact]
public void Build_PerVertexTerrainLayer_UsesMappedLayerIndex()
public void Build_FlatBlock_NormalsPointStraightUp()
{
var block = BuildFlatLandBlock();
// TerrainInfo is bit-packed: bits 0-1 Road, bits 2-6 Type, bits 11-15 Scenery.
// Raw ushort 0x001C = binary 0011100 → Type field = 7 (bits 2-6).
// This is what a terrain sample with TerrainTextureType=7 looks like in the
// underlying byte stream. LandblockMesh uses TerrainInfo.Type (not raw) as
// the atlas lookup key.
block.Terrain[2 * 9 + 3] = (ushort)(7 << 2); // Type=7, Road=0, Scenery=0
var cache = new Dictionary<uint, SurfaceInfo>();
var map = new Dictionary<uint, uint>
var mesh = LandblockMesh.Build(block, 0, 0, IdentityHeightTable, MakeContext(), cache);
foreach (var v in mesh.Vertices)
{
[0] = 0u, // default type → atlas layer 0
[7] = 4u, // TerrainTextureType 7 → atlas layer 4
};
Assert.Equal(new Vector3(0, 0, 1), v.Normal);
}
}
var mesh = LandblockMesh.Build(block, IdentityHeightTable, map);
[Fact]
public void Build_AllVerticesOfACellShareIdenticalData()
{
var block = BuildFlatLandBlock();
var cache = new Dictionary<uint, SurfaceInfo>();
// Vertex buffer internal order is y*9+x, so vertex at world (x=2, y=3) is at
// index 3*9+2 = 29.
Assert.Equal(4u, mesh.Vertices[3 * 9 + 2].TerrainLayer);
// An untouched vertex still has Type 0, maps to layer 0.
Assert.Equal(0u, mesh.Vertices[0].TerrainLayer);
var mesh = LandblockMesh.Build(block, 0, 0, IdentityHeightTable, MakeContext(), cache);
// Vertices are emitted in strides of 6 per cell. Within each stride,
// Data0..3 must be identical — the vertex shader relies on that when
// it propagates the cell's blend recipe to all 3 fragment-shader outputs.
for (int cellIdx = 0; cellIdx < 64; cellIdx++)
{
int baseIdx = cellIdx * 6;
var d0 = mesh.Vertices[baseIdx].Data0;
var d1 = mesh.Vertices[baseIdx].Data1;
var d2 = mesh.Vertices[baseIdx].Data2;
var d3 = mesh.Vertices[baseIdx].Data3;
for (int i = 1; i < 6; i++)
{
Assert.Equal(d0, mesh.Vertices[baseIdx + i].Data0);
Assert.Equal(d1, mesh.Vertices[baseIdx + i].Data1);
Assert.Equal(d2, mesh.Vertices[baseIdx + i].Data2);
Assert.Equal(d3, mesh.Vertices[baseIdx + i].Data3);
}
}
}
[Fact]
public void Build_SurfaceCacheIsReusedAcrossIdenticalCells()
{
var block = BuildFlatLandBlock(); // every cell has identical all-zero corners
var cache = new Dictionary<uint, SurfaceInfo>();
LandblockMesh.Build(block, 0, 0, IdentityHeightTable, MakeContext(), cache);
// A uniform flat landblock produces exactly ONE palette code (all
// corners are type 0, no roads) → BuildSurface called once, cache
// contains a single entry even though 64 cells were processed.
Assert.Single(cache);
}
[Fact]
public void Build_CellsWithDistinctTerrainTypes_ProducesDistinctPaletteCodes()
{
// Put a dirt cell (type 4) at the center of an otherwise grass landblock.
// Grass cells all share one palCode; the "dirt + grass border" cells
// around the center introduce additional palette codes.
var block = BuildFlatLandBlock();
// Type is at bits 2-6, so type=4 → ushort = (4 << 2) = 0x10.
block.Terrain[4 * 9 + 4] = (ushort)(4 << 2);
var ctx = new TerrainBlendingContext(
TerrainTypeToLayer: new Dictionary<uint, byte> { [0u] = 0, [4u] = 1 },
RoadLayer: SurfaceInfo.None,
CornerAlphaLayers: new byte[] { 0, 1, 2, 3 },
SideAlphaLayers: Array.Empty<byte>(),
RoadAlphaLayers: Array.Empty<byte>(),
CornerAlphaTCodes: new uint[] { 1, 2, 4, 8 },
SideAlphaTCodes: Array.Empty<uint>(),
RoadAlphaRCodes: Array.Empty<uint>());
var cache = new Dictionary<uint, SurfaceInfo>();
LandblockMesh.Build(block, 0, 0, IdentityHeightTable, ctx, cache);
// Should have more than one palette code now — uniform-grass cells
// plus at least one boundary cell with a non-zero corner type.
Assert.True(cache.Count >= 2, $"Expected mix of palette codes, got {cache.Count}");
}
[Fact]
public void Build_HeightmapPackedAsXMajor_NotYMajor()
{
// Regression: Phase 1 used block.Height[y*9+x] which transposes the terrain
// along its diagonal relative to AC's native x-major packing. Invisible on
// flat landblocks but catastrophically wrong on Holtburg where static-object
// positions reference the un-transposed ground truth, leaving buildings
// buried by ~10 world-Z units.
//
// Set up an asymmetric heightmap: value at x-major index (x=2, y=0) = 5
// (scaled to Z=10), everything else 0. The vertex at world position
// (x=2*24=48, y=0) should have Z=10. The vertex at (x=0, y=2*24=48) should
// have Z=0. Y-major indexing would swap these.
// Regression from the Phase 1 → 2a transpose bug. The underlying
// heightmap is indexed x*9+y; testing this lives on even after the
// per-cell refactor because the corner lookup in the cell loop still
// reads block.Height[cx*9+cy] for the BL corner.
var block = BuildFlatLandBlock();
block.Height[2 * 9 + 0] = 5; // x=2, y=0 in x-major packing
block.Height[2 * 9 + 0] = 5; // x=2, y=0 → world (48, 0), Z should be 10
var mesh = LandblockMesh.Build(block, IdentityHeightTable, EmptyTerrainMap);
var cache = new Dictionary<uint, SurfaceInfo>();
var mesh = LandblockMesh.Build(block, 0, 0, IdentityHeightTable, MakeContext(), cache);
// Find vertices by position. Vertex buffer uses y*9+x internally.
var vAt_x2_y0 = mesh.Vertices[0 * 9 + 2]; // world (48, 0)
var vAt_x0_y2 = mesh.Vertices[2 * 9 + 0]; // world (0, 48)
// Search the vertex buffer for a vertex at world position (48, 0).
var atX48Y0 = mesh.Vertices.FirstOrDefault(v =>
Math.Abs(v.Position.X - 48f) < 0.01f && Math.Abs(v.Position.Y) < 0.01f);
var atX0Y48 = mesh.Vertices.FirstOrDefault(v =>
Math.Abs(v.Position.X) < 0.01f && Math.Abs(v.Position.Y - 48f) < 0.01f);
Assert.Equal(new Vector3(48, 0, 10), vAt_x2_y0.Position);
Assert.Equal(new Vector3(0, 48, 0), vAt_x0_y2.Position);
Assert.Equal(10.0f, atX48Y0.Position.Z);
Assert.Equal(0.0f, atX0Y48.Position.Z);
}
}