feat: complete overworld custom mesh roadmap

[MichaelFisher1997]

Summary

• Add slab and stair custom mesh fixtures to close the remaining Epic: Refresh Overworld Block and Biome Roadmap #616 render-shape gap.
• Wire deterministic custom mesh generation into chunk meshing and add coverage for registry, occlusion, and mesh output.
• Refresh roadmap/capacity docs with the current completion boundary and 79/256 block count.

Verification

• nix develop --command zig fmt modules/world-core/src/block.zig modules/world-core/src/block_registry.zig modules/world-core/src/block_registry_tests.zig modules/world-meshing/src/meshing/custom_mesh_mesher.zig modules/world-meshing/src/chunk_mesh.zig modules/world-meshing/src/root.zig modules/world-meshing/src/chunk_mesh_tests.zig
• nix develop --command zig build -Dskip-present
• nix develop --command zig build test
• nix develop --command zig build -Doptimize=ReleaseFast
• nix develop --command zig build test -- --test-filter custom
• git diff --check

Runtime Notes

• nix develop --command zig build run -Dskip-present -Dauto-world=normal -Dstartup-diagnostic-seconds=5 timed out after shader validation output only.
• nix develop --command zig build run -Dskip-present -Dsmoke-test timed out after shader validation output only.

Closes #616

[github-actions]

📋 Summary

Linked Issue: Closes #616

The PR fully addresses #616 by completing the custom mesh render-shape foundation. It adds stone_slab and stone_stairs block types (IDs 77-78), implements a deterministic custom_mesh_mesher.zig with slab and stair fixture geometry, wires it into chunk_mesh.zig, fixes occlusion logic so non-cube solids don't incorrectly cull neighbors, and adds registry + mesh output tests. Documentation (roadmap audit, block capacity) is updated to reflect the new 79/256 block count. The implementation is scoped correctly as fixture-level (no per-block orientation/state), which matches the PR's stated boundaries.

📌 Review Metadata

• Reviewed Commit SHA: f842d94351a0aa56171f6d9bdcbe12ebc35f2b08
• Reviewed PR: feat: complete overworld custom mesh roadmap #644

---

🔴 Critical Issues (Must Fix - Blocks Merge)

None identified.

⚠️ High Priority Issues (Should Fix)

None identified.

💡 Medium Priority Issues (Nice to Fix)

None identified.

ℹ️ Low Priority Suggestions (Optional)

[LOW] modules/world-meshing/src/meshing/custom_mesh_mesher.zig:83 - sampleCustomLight omits downward light sampling
Confidence: Medium
Description: The sampleCustomLight function iterates oy from 0 to 1, sampling light at y and y+1 but never y-1. For slab bottom faces and the lower portion of stairs, light from below (e.g., in caves or under overhangs) is ignored, which may produce slightly incorrect ambient lighting.
Impact: Minor visual inaccuracy on undersides of custom mesh blocks in specific lighting conditions.
Suggested Fix: Expand the oy loop to oy: i32 = -1; while (oy <= 1) : (oy += 1) to match a symmetric 3×3×3 neighborhood, consistent with typical voxel light sampling.

[LOW] modules/world-meshing/src/meshing/custom_mesh_mesher.zig:72-74 - Stair geometry emits interior faces
Confidence: Medium
Description: The stair variant emits two axis-aligned boxes that share a coplanar boundary at y+0.5 in the region x=[0,1], z=[0.5,1]. Each box emits its own face at this plane (bottom box top face + top box bottom face), creating 12 vertices of interior geometry per stair block that are never visible.
Impact: Wasted vertex bandwidth and minor overdraw. No z-fighting occurs because the face normals are opposite.
Suggested Fix: For a fixture implementation this is acceptable, but a future enhancement could skip the shared face by splitting the stair into non-overlapping prism shapes or adding a face-culling check within emitBox against an internal occlusion mask.

---

📊 SOLID Principles Score

Principle	Score	Notes
Single Responsibility	9	Custom mesh mesher has one job: emit slab/stair geometry. Registry changes are minimal and focused.
Open/Closed	8	New CustomMeshVariant enum makes adding doors/fences later a matter of extending the switch.
Liskov Substitution	9	isFullCubeOccluder() cleanly separates cube occlusion from solid-block occlusion; existing non-cube blocks are unaffected.
Interface Segregation	9	The mesher reuses existing Vertex, TextureAtlas, and boundary APIs without bloating them.
Dependency Inversion	8	Meshing depends on registry data, not hardcoded block types.
Average	8.6

---

🎯 Final Assessment

Overall Confidence Score: 88%

Confidence Breakdown:

• Code Quality: 90% (Clean Zig conventions, proper allocator usage, good comptime registry safety)
• Completeness: 85% (Fulfills the fixture-level scope claimed by Epic: Refresh Overworld Block and Biome Roadmap #616; per-block state/orientation is correctly deferred)
• Risk Level: 85% (Low risk: deterministic meshing, no RHI changes, no threading changes)
• Test Coverage: 90% (Registry, occlusion, and mesh output tests all present)

Merge Readiness:

• All critical issues resolved
• SOLID average score >= 6.0
• Overall confidence >= 60%
• No security concerns
• Tests present and passing (if applicable)

Verdict:

MERGE

The PR is well-scoped, correctly implements the remaining #616 custom mesh foundation, and includes appropriate test coverage. No blocking issues identified.

---

{
  "reviewed_sha": "f842d94351a0aa56171f6d9bdcbe12ebc35f2b08",
  "critical_issues": 0,
  "high_priority_issues": 0,
  "medium_priority_issues": 0,
  "overall_confidence_score": 88,
  "recommendation": "MERGE"
}

opencode session  |  github run