3D Geometry Generation

Relevant source files

The following files were used as context for generating this wiki page:

• src/BlockGeoMaker.js
• src/EntityGeoMaker.js
• src/PolyMeshMaker.js
• src/HoloPrint.js
• src/PreviewRenderer.js
• src/data/schemas/blockShapeGeos.schema.json
• src/packTemplate/models/entity/holoprint.hologram.geo.json

3D Geometry Generation in HoloPrint is the core engine responsible for converting Minecraft Bedrock Edition .mcstructure data into client-side entity geometry. The system translates block palette data into optimized poly-mesh structures that can be rendered as holograms within a resource pack.

This process involves several stages, including resolving block states to specific shapes, applying Euler rotations, optimizing geometry via cube merging and face culling, and finally assembling the data into a format compatible with Minecraft's poly_mesh geometry system.

Sources: src/HoloPrint.js:125-150, src/BlockGeoMaker.js:46-52

Geometry Generation Pipeline

The pipeline starts with a decoded structure NBT and concludes with the generation of a JSON geometry file for the resource pack.

The diagram above illustrates the high-level flow of 3D data from the source structure file to the final rendering components.
Sources: src/HoloPrint.js:125-200

Block Geometry Mapping

The BlockGeoMaker class is the primary component for defining how individual blocks are represented as 3D geometry. It uses a collection of JSON-defined "block shapes" and "patterns" to determine which cubes to render based on a block's ID and its state data.

Key Logic and Processing

1. Shape Selection: Matches block names against individual definitions or regex patterns to find a corresponding geometry template.
2. Conditional Rendering: Evaluates if expressions within geometry definitions. These expressions check block states (e.g., lever_direction==down) to decide if specific cubes should be rendered.
3. Rotation and Pivoting: Applies block-level rotations based on block states. It uses Euler rotations (X-Y-Z) around a defined pivot point (defaulting to [8, 8, 8]).
4. Scaling: Ghost blocks are scaled (default 95%) towards their center of mass to prevent Z-fighting and distinguish them from real blocks.

Sources: src/BlockGeoMaker.js:93-113, src/BlockGeoMaker.js:168-175, src/BlockGeoMaker.js:630-650, src/BlockGeoMaker.js:774-783

Block Shape Schema

Geometry is defined as an array of cubes. Each cube can have properties that allow for advanced modeling:

Property	Type	Description
pos	Array[3]	The coordinates of the bottom-left-back corner of the cube.
size	Array[3]	The dimensions of the cube in each axis.
rot	Array[3]	The XYZ rotation in degrees, applied in X-Y-Z order.
uv	Object	Coordinate overrides for faces (west, east, up, down, etc.).
copy	String	Recursively copies another block shape definition.
if	String	C-style syntax for conditional rendering based on block states.

Sources: src/data/schemas/blockShapeGeos.schema.json:17-150

Optimization and Merging

To ensure high performance in the Bedrock engine, HoloPrint performs automated geometry optimization. The #optimizeGeometry method in BlockGeoMaker reduces the number of rendered faces and cubes.

Face Culling and Cube Merging

• Adjacency Detection: The system detects if two cubes share a face. If cubes share identical properties (textures, tints, etc.) and are perfectly adjacent, they are merged into a single larger cube.
• Hidden Face Culling: If two cubes are adjacent but cannot be merged (e.g., different textures), the touching faces are set to "none" to prevent the engine from rendering internal surfaces.
• Translucency Management: Cubes are sorted by volume and transparency to ensure that blocks like slime or honey render correctly, with inner layers drawn before outer layers.

Sources: src/BlockGeoMaker.js:358-380, src/BlockGeoMaker.js:410-450

Poly-Mesh Assembly

The PolyMeshMaker class aggregates all resolved block templates into a single poly_mesh object. Unlike standard Bedrock box geometry, poly_mesh allows for more complex, arbitrary vertex positioning.

PolyMeshMaker uses TripleSet and CoupleSet structures to ensure that identical vertices, normals, and UV coordinates are deduplicated, significantly reducing the final file size.
Sources: src/PolyMeshMaker.js:5-30, src/PolyMeshMaker.js:34-80

Web-Based Preview Rendering

The PreviewRenderer utilizes Three.js to provide an immediate visualization of the generated geometry. It maps the Bedrock poly_mesh data into Three.js BufferGeometry.

Rendering Features

• Instanced Rendering: For performance, identical block types are rendered using THREE.InstancedMesh.
• Dynamic Lighting: Supports global directional light and up to 100 localized point lights (e.g., for torches or lanterns) based on the structure's contents.
• Shadow Mapping: Implements THREE.PCFShadowMap for the directional light, including a ground shadow plane.
• Transparency: Separates opaque and translucent materials into different rendering passes using alphaTest and transparent material settings.

Sources: src/PreviewRenderer.js:151-180, src/PreviewRenderer.js:235-255, src/PreviewRenderer.js:370-385

Conclusion

The 3D Geometry Generation system transforms abstract block data into a highly optimized, visual representation. By combining procedural template generation in BlockGeoMaker with deduplicated mesh assembly in PolyMeshMaker, HoloPrint creates resource packs that remain performant even when displaying complex, multi-layered builds.