Yuanhao Feng

Back

The first article introduced CubeMuse’s structured instruction set. After the DSL engine executes an op-log, it produces a Grid: a voxel grid that stores the block at every occupied position. This article covers how that Grid becomes an interactive 3D building in the browser.

The first challenge is performance. A mid-sized building has thousands to tens of thousands of blocks, each a unit cube with six faces. With a separate Mesh for each block, the draw call count would grow linearly with the number of blocks. Command submission would become the GPU bottleneck. CubeMuse’s rendering pipeline uses greedy meshing to merge adjacent same-material faces into large rectangles, hidden-face culling to skip occluded faces, vertex AO to approximate ambient occlusion, and a three-pass draw order to handle transparency.

Chunk-Based Meshing and the Rendering Pipeline#

Internally, Grid is organized into Chunks. A Chunk is a 16-unit cube and serves as the basic unit for storage and mesh generation. Each cell stores a Uint16 index into a Palette, which holds deduplicated block ids and states. Grid only allocates non-empty Chunks; empty regions use no memory.

Mesh generation runs per Chunk. Blocks are first handled according to their geometry: full blocks that occupy an entire cell go through the greedy meshing path, while stairs, slabs, fences, and other non-full blocks go through a per-block geometry expansion path. Both paths write to the same typed arrays: positions, normals, colors, uvs, layers, and indices. The geometry is then divided by material transparency into opaque, cutout, and transparent segments. Each non-empty segment becomes one Mesh drawn with MeshBasicMaterial, where all shading comes from face-direction coefficients and AO baked into vertex colors.

Grid + Palette Uint16 indices into deduplicated blocks Split into 16³ Chunks Per-chunk processing Full blocks Hidden face culling Vertex AO sampling Greedy meshing Model blocks (15 kinds) Per-block geometry Fixed AO level 3 opaque cutout transparent Three segments → BufferGeometry → MeshBasicMaterial Opaque list (opaque + cutout) Transparent list (far → near)

The three geometry segments enter two Three.js draw queues. Opaque and cutout share the opaque list; transparent goes into the transparent list, sorted by projected depth from far to near. The project initially used instanced cubes grouped by block id, before moving to the current chunk-mesh approach. The meshing algorithm operates only on typed arrays and runs in Node as well, so the screenshot script and tests share the same code.

Hidden-Face Culling and Greedy Meshing#

Most block faces in a building are hidden behind adjacent blocks and need not be generated. For each face of a full block, if the neighbor in that direction exists, is opaque, and fills the cell, the face is skipped. Transparent full blocks use a different rule: a face is skipped only when the neighbor has the same Palette index, so identical glass blocks merge seamlessly while different colors keep their boundary.

Greedy meshing processes the faces left after culling. The algorithm processes each of the six face directions layer by layer. Each layer uses a 16×16 mask, with a merge key stored in every cell. The merge key combines the Palette index and the four-corner AO values; only cells with the same key can merge. Scanning starts at the top-left corner: for each unprocessed cell, extend along u as far as the key matches, then check full rows along v to extend height, producing a single rectangular quad. Merging does not cross Chunk boundaries.

4×4 mask merging process Original mask Scan steps Merged quads A A B B A A B B A A A A A A A A u → v ↓ Q1 Q2 Q3 key=A UV: 2×2 key=B UV: 2×2 key=A UV: 4×2 16 unit faces → 3 quads → 6 triangles Merge key = Palette index + four-corner AO  Different keys or chunk boundaries break merging Scan order: top-left first, expand u, then expand v ① 2×2 A ② 2×2 B ③ 4×2 A Textures tile per cell via RepeatWrapping; UV span = number of cells covered

Merged faces use UV spans equal to the number of cells they cover. A 2×3 merged face has UV range (0,0) to (2,3), and the GPU tiles the texture automatically via RepeatWrapping.

Below are face counts from a few scenes. The solid stone cube data comes from running the current meshing function in Node.

SceneBlocksRaw facesAfter cullingCull rateFinal quadsTriangles
4³ stone643849675%612
8³ stone5123,07238487.5%612
16³ stone4,09624,5761,53693.75%612
32³ stone32,768196,6086,14496.875%2448

The 16³ cube keeps 1,536 faces after culling 93.75%. Greedy meshing then reduces those 1,536 faces to 6 quads, a further 99.6% reduction. The 32³ scene spans eight Chunks; each exposed face is cut into four pieces at Chunk boundaries, producing 24 quads.

For a building example, consider a 194-block cottage with a 7×6×7 bounding box. Its full blocks have 1,152 raw faces, with 414 left after culling, a 64% cull rate. After merging, 107 quads remain. Adding 6 quads from the door model, the entire building uses 113 quads, 226 triangles, and 2 non-empty geometry segments.

Vertex AO and Directional Lighting#

All shading in CubeMuse comes from a face-direction coefficient and vertex AO, without real-time lighting. The direction coefficient is a fixed constant per face orientation: top 1.0, bottom 0.5, east and west 0.6, north and south 0.8, simulating overhead sunlight. Vertex AO is computed during mesh generation by sampling neighboring blocks to approximate ambient occlusion at corners.

Each corner of a visible face samples three neighbors in the outer layer: two edge neighbors s1, s2 and one diagonal neighbor c. If both edge neighbors are occluded, AO is 0 (darkest) and the diagonal is ignored. Otherwise AO = 3 - s1 - s2 - c, where each variable is 0 or 1. The four AO levels map to coefficients 0.45, 0.63, 0.82, and 1.00.

Corner AO Sampling Currentface Corner s1 s2 c Edge neighbor Edge neighbor Diagonal neighbor AO Formula s1, s2 = occluded ? 1 : 0 c = occluded ? 1 : 0 s1 && s2 ? AO=0 : AO=3-s1-s2-c Both edges occluded: diagonal is ignored Four AO Levels AO = 3 1.00 No occlusion AO = 2 0.82 One edge AO = 1 0.63 Edge + diagonal AO = 0 0.45 Both edges Diagonal Flip C00 C11 Default diagonal C00–C11 C01 C10 Flipped diagonal C10–C01 When AO00+AO11 < AO10+AO01 Pick the diagonal with lessbrightness difference Face direction coeff: top 1.0 / bottom 0.5 / east-west 0.6 / north-south 0.8  Vertex color = direction coeff × AO coeff

All three vertex color channels are set to the direction coefficient multiplied by the AO coefficient. An east-facing corner with one edge neighbor occluded has AO level 2, giving vertex brightness = 0.6 × 0.82 = 0.492.

AO values are included in the merge mask before greedy meshing runs. Two adjacent cells with the same Palette index but different four-corner AO produce different merge keys and will not be merged into the same quad. This preserves corner shading gradients across merged faces.

The four-corner AO values also determine triangulation direction. Each quad is split into two triangles, defaulting to the C00-C11 diagonal. When AO00 + AO11 < AO10 + AO01, the split switches to the C10-C01 diagonal, choosing the diagonal with less brightness difference to avoid jagged shading artifacts at asymmetric corners.

Non-full block cuboids use a fixed AO level of 3 (brightest), and cross plants set the direction coefficient to 1. These model pieces are small enough that per-corner sampling provides little benefit.

Block Models and State#

Stairs, slabs, and doors occupy only part of their cells. Stairs occupy a half-block plus one step, slabs are half height, and doors span two cells but are only one face wide. These non-full blocks cannot go through greedy meshing and require per-block geometry expansion based on their ModelKind.

CubeMuse defines 15 ModelKinds: full, slab, stairs, door, cross, flat, pane, fence, gate, wall, trapdoor, rod, box, wallflat, potted. To choose a ModelKind, CubeMuse checks an explicit lookup table first, then block-family rules that match name prefixes or suffixes. Any remaining blocks fall back to full.

Block Model Geometry Full blocks use greedy meshing; the other 15 ModelKinds expand per-block cuboids or specialized quads full 1×1×1 Greedy merged slab y: 0–0.5 Sub-cuboid stairs facing + half + shape (corners) cross Two intersectingquads 4 triangles cutout + double-sided ascending rail Height 0 → 1 1 sloped quad 2 triangles Non-full blocks skip greedy meshing; AO is fixed at level 3 (brightest) All 15: full / slab / stairs / door / cross / flat / pane / fence / gate / wall / trapdoor / rod / box / wallflat / potted Fences, walls, and glass panes use fixed-shape approximations; neighbor connectivity not implemented

Most model blocks expand into sub-cuboids within their cell. A bottom slab spans y 0 to 0.5. Stairs read facing and half state to produce a bottom half-block plus an upper step toward the facing direction; inner and outer corner shapes further adjust the geometry. Doors use the facing, hinge, and open states to determine their transform. Logs select the end-grain texture based on axis orientation.

Two block types use specialized quad paths. Cross plants generate two intersecting quads totaling 4 triangles, rendered with cutout material and double-sided faces to preserve leaf silhouettes. Ascending rails read the direction state and produce a single sloped quad going from height 0 to 1. Straight and curved rails lie flat; curved rail textures currently use a straight-track approximation.

Face culling keeps more faces for non-full blocks. When the neighbor is a stair or slab, wall faces are kept. Only faces flush with the cell boundary and fully occluded by an adjacent full block are skipped. Fences, walls, and glass panes use fixed-shape approximations; neighbor connectivity is not yet implemented.

Transparency and Cutout Materials#

The three geometry segments correspond to three material configurations.

CategoryExamplestransparentdepthWritealphaTestside
opaquestone, planks, leavesfalsetrue0FrontSide
cutoutflowers, rails, laddersfalsetrue0.5DoubleSide
transparentglass, watertruefalse0FrontSide

Opaque is the default material. It writes depth, renders only front faces, and uses no alpha test. Stone, planks, and leaves all use it. Although Minecraft leaves have transparent pixels, CubeMuse treats them as full blocks and tints the texture with a fixed foliage color to fill the entire face.

Cutout handles blocks with irregular silhouettes. Flowers, rails, and ladders use an alpha test that discards pixels below 0.5, preserving their outlines. Cutout enables double-sided rendering so the shape is visible from any angle. Because cutout writes depth, it needs no sorting.

Transparent handles glass and water. Alpha blending is on, depth writing is off, and only front faces are rendered. Water textures multiply alpha by 0.7 during decoding. Three.js draws opaque and cutout together in the opaque list, followed by the transparent list. Within the transparent list, objects sort by projected Mesh depth from far to near. All transparent faces in one Chunk share a single Mesh. Its triangles keep the index order from mesh generation, so sorting remains approximate for complex overlaps.

Texture Roles and Async Loading#

Different faces of the same block can use different textures. A grass block’s top face shows grass, its side shows a grass-to-dirt transition, and its bottom shows dirt. CubeMuse controls this through texture roles: each Palette entry has a base layer index N, and the face direction maps through faceRoleIndex to a role offset. The top face reads layer N+0, sides read N+1, and the bottom reads N+2. Each texture layer is a 16×16 RGBA pixel slice; all layers stack by index in a single DataArrayTexture. Stone uses one role and one layer, grass blocks use three, and logs use two: end and side.

Texture Role Selection Palette entry grass_block base = N faceRoleIndex selects role by face direction top N+0 side N+1 bottom N+2 DataArrayTexture layer N layer N+1 layer N+2 16×16 RGBA per layer Log: end + side (2 layers)  Stone: all (1 layer)  Merged faces tile via RepeatWrapping Async Loading Timeline t ① Synchronous init Placeholder pixels fill each layer (solid color) ② Create atlas object NearestFilter / no mipmap / RepeatWrapping ③ Async loading (per layer) Candidate paths: vanilla/ → pixel-perfection/ Decode PNG → tint (e.g. foliage color) →overwrite layer bytes ④ needsUpdate = true Loading done → GPU re-upload Atlas cache Same Palette signature → reuse New Palette entry → rebuild Screenshot waits for pending/ready signal Fallback PNG load failure → placeholder pixels remain

Merged faces still need per-cell texture tiling. Each vertex’s texture layer index is the Palette entry’s base plus the role offset. The UV span matches the number of cells covered, and the GPU repeats the texture via RepeatWrapping. NearestFilter preserves the pixel-art aesthetic, and mipmaps are disabled.

Loading happens in three steps. Step one is synchronous: fill every layer with a procedurally generated solid-color placeholder and create the DataArrayTexture object. Step two loads each layer asynchronously, checking the vanilla directory first, then Pixel Perfection. Once a PNG is found, it is decoded and tinted with foliage or water color if needed. The resulting pixels overwrite the layer’s bytes. Step three sets needsUpdate = true so Three.js re-uploads the data to the GPU on the next frame. Layers that fail to load keep their placeholder content.

During editing, the atlas is cached by Palette content signature. Block position changes that don’t alter the Palette reuse the atlas. Adding a new Palette entry triggers a rebuild and reload. The screenshot script uses the pending and ready signals to wait until textures are fully loaded before capturing an image.

Dirty Chunks and Incremental Rebuilds#

When the user edits a single block, only the affected Chunks need rebuilding. The remaining Chunks keep their geometry and GPU resources unchanged.

To find the affected Chunks, expand the edit coordinate by 1 on each axis. This covers the positions that affect neighbor-face visibility and corner AO. Then floor-divide the expanded range by 16 to get the set of dirty Chunks. Depending on position, a single-cell edit may touch 1, 2, 4, or 8 Chunks.

Dirty Chunk Range from Single-Cell Edits Edit coordinate ±1 on each axis, then floor(÷16) to find dirty chunk set Chunk 0 Interior point (8, 8, 8) Range 7–9 All within Chunk 0 1 dirty chunk C0 C1 Face boundary (15, 8, 8) x range 14–16 Spans two chunks 2 dirty chunks Edge boundary (15, 15, 8) x, y each span two chunks 2 × 2 × 1 4 dirty chunks Corner (15, 15, 15) All three axes span two chunks 2 × 2 × 2 8 dirty chunks Clean chunks keep ChunkMesh + BufferGeometry references  fromGrid mismatch falls back to full rebuild

Edit coordinateDirty chunksReason
(8, 8, 8)1Range 7–9 stays within Chunk 0
(15, 8, 8)2x range 14–16 spans two Chunks
(15, 15, 8)4x and y each span two Chunks
(15, 15, 15)8All three axes span two Chunks

Incremental rebuilding re-meshes only the dirty Chunks. Clean Chunks retain their ChunkMesh and BufferGeometry references, allowing their GPU resources to be reused. When the Palette gains new entries, existing entries keep their indices and texture layer bases stable, so clean Chunks’ existing layer attributes remain valid.

The incremental path includes a safety check: the supplied fromGrid must match the cached Grid reference and dirtyKeys must be non-empty. A reference mismatch triggers a full rebuild. Loading a new blueprint or switching views also triggers full rebuilds. Incremental results are verified against full-rebuild results through deep comparison of all typed arrays, and clean Chunks maintain the same object references.

References#

CubeMuse's Voxel Rendering Engine
https://me.yuanhaofeng.com/en/blog/cubemuse-voxel-engine
Author Yuanhao Feng
Published at October 4, 2026