Phase 2: full-voxel chunk storage, greedy mesher, and Babylon 3D viewer

api: chunk_sections table (per 16x16x16 section, base64-encoded u16
blockStateId array) and mesh_pointers table, additive to Phase 1's
column-based chunk_columns/tile_pointers — 2D tile rendering keeps using
the cheap column path unchanged. New "sections" WS message (backfill on
chunk load + delta resend on flush, same "current state, not a diff"
philosophy as columns) reuses the existing dirty-chunk Redis event, so one
event now triggers the worker to re-render both the 2D tile and any 3D
meshes for that chunk. New mesh-serving routes.

worker: a from-scratch greedy mesher (per-axis 2D mask sweep + rectangle
merge — the standard voxel-meshing technique, reimplemented from its
public description, not copied from any codebase) producing a compact
custom binary vertex buffer per non-empty section. Verified with unit
tests, including one that specifically checks a uniform section collapses
to exactly 6 merged quads rather than one quad per voxel face (the
decisive signal that merging, not just per-voxel face emission, is
actually happening).

frontend: a barebones Babylon.js 3D viewer (/3d) that loads a fixed radius
of chunks, parses the mesh binary format, and renders each section as its
own mesh (no cross-section merging yet, no camera-based streaming yet —
both reasonable follow-ups once there's a reason to optimize).

End-to-end verified against live containers, including through the real
mod-side Java WS client (see MCMapper-Mod's matching commit): a known
half-solid section correctly round-trips to exactly 24 vertices / 36
indices at the mesh-serving endpoint, matching the "6 merged outer faces"
the unit tests predict.
This commit is contained in:
2026-08-08 16:19:03 +02:00
parent 7bed571ffa
commit 5ed4d32a56
15 changed files with 707 additions and 12 deletions
+108
View File
@@ -0,0 +1,108 @@
// Barebones Babylon 3D viewer (Phase 2). Loads a fixed radius of chunks around the origin once
// at startup — no camera-based dynamic streaming/culling yet, that's a natural follow-up once
// there's a reason to care about performance at scale. Dimension is hardcoded to 0 (overworld),
// matching the 2D map's assumption (see public/js/map.js).
const DIMENSION = 0;
const CHUNK_RADIUS = 2; // (2*2+1)^2 = 25 chunks
// Binary mesh format written by worker/src/mesh.rs's MeshBuffers::encode():
// u32 vertexCount, u32 indexCount,
// f32[vertexCount*3] positions, f32[vertexCount*3] normals, f32[vertexCount*3] colors,
// u32[indexCount] indices — all little-endian.
function parseMeshBuffer(buf) {
const view = new DataView(buf);
const vertexCount = view.getUint32(0, true);
const indexCount = view.getUint32(4, true);
let offset = 8;
const positions = new Float32Array(buf, offset, vertexCount * 3);
offset += vertexCount * 3 * 4;
const normals = new Float32Array(buf, offset, vertexCount * 3);
offset += vertexCount * 3 * 4;
const rgb = new Float32Array(buf, offset, vertexCount * 3);
offset += vertexCount * 3 * 4;
const indices = new Uint32Array(buf, offset, indexCount);
// Babylon's VertexData.colors wants RGBA.
const colors = new Float32Array(vertexCount * 4);
for (let i = 0; i < vertexCount; i++) {
colors[i * 4] = rgb[i * 3];
colors[i * 4 + 1] = rgb[i * 3 + 1];
colors[i * 4 + 2] = rgb[i * 3 + 2];
colors[i * 4 + 3] = 1;
}
return { positions, normals, colors, indices };
}
async function loadSectionMesh(scene, serverId, chunkX, chunkZ, sectionY) {
const res = await fetch(`/api/meshes/${serverId}/${DIMENSION}/${chunkX}/${chunkZ}/${sectionY}.bin`);
if (!res.ok) return;
const buf = await res.arrayBuffer();
if (buf.byteLength < 8) return;
const { positions, normals, colors, indices } = parseMeshBuffer(buf);
if (indices.length === 0) return;
const mesh = new BABYLON.Mesh(`section-${chunkX}-${chunkZ}-${sectionY}`, scene);
const vertexData = new BABYLON.VertexData();
vertexData.positions = positions;
vertexData.normals = normals;
vertexData.indices = indices;
vertexData.colors = colors;
vertexData.applyToMesh(mesh);
const mat = new BABYLON.StandardMaterial(`mat-${chunkX}-${chunkZ}-${sectionY}`, scene);
// Winding isn't guaranteed to match Babylon's default front-face convention for every quad
// (see worker/src/mesh.rs's emit_quad doc comment) — disable culling as the safety net so
// every face renders regardless of which side it's viewed from.
mat.backFaceCulling = false;
mat.specularColor = new BABYLON.Color3(0, 0, 0);
mesh.material = mat;
mesh.position = new BABYLON.Vector3(chunkX * 16, sectionY * 16, chunkZ * 16);
}
async function loadChunk(scene, serverId, chunkX, chunkZ) {
const res = await fetch(`/api/meshes/${serverId}/${DIMENSION}/${chunkX}/${chunkZ}`);
if (!res.ok) return;
const sectionYs = await res.json();
await Promise.all(sectionYs.map((sy) => loadSectionMesh(scene, serverId, chunkX, chunkZ, sy)));
}
async function main() {
const statusEl = document.getElementById("status");
const canvas = document.getElementById("renderCanvas");
const engine = new BABYLON.Engine(canvas, true);
const scene = new BABYLON.Scene(engine);
scene.clearColor = new BABYLON.Color4(0.1, 0.1, 0.12, 1);
const camera = new BABYLON.ArcRotateCamera(
"camera", -Math.PI / 2, Math.PI / 3, 80,
new BABYLON.Vector3(0, 70, 0), scene,
);
camera.attachControl(canvas, true);
camera.wheelPrecision = 5;
camera.lowerRadiusLimit = 5;
new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0.3, 1, 0.2), scene);
const servers = await fetch("/api/servers").then((r) => r.json());
const server = servers[0];
if (!server) {
statusEl.textContent = "no server registered yet — see backend README (bun run seed)";
} else {
statusEl.textContent = `loading meshes for ${server.name}`;
const loads = [];
for (let cx = -CHUNK_RADIUS; cx <= CHUNK_RADIUS; cx++) {
for (let cz = -CHUNK_RADIUS; cz <= CHUNK_RADIUS; cz++) {
loads.push(loadChunk(scene, server.id, cx, cz));
}
}
await Promise.all(loads);
statusEl.textContent = `${server.name}${scene.meshes.length} section meshes loaded`;
}
engine.runRenderLoop(() => scene.render());
window.addEventListener("resize", () => engine.resize());
}
main();