Structure File Parsing & NBT
Relevant source files
The following files were used as context for generating this wiki page:
HoloPrint is designed to convert Minecraft Bedrock Edition (MCBE) structure files (.mcstructure) into functional resource packs that display holograms. The core of this process involves parsing Named Binary Tag (NBT) data, which is the standard format used by Minecraft for storing complex structured data including blocks, entities, and metadata. Sources: README.md:10-15, src/HoloPrint.js:448-450
The system handles the extraction of NBT data from multiple sources: direct .mcstructure file uploads, extraction from world files (.mcworld), or updating existing HoloPrint/Structura packs. Once extracted, the NBT data is processed to generate a block palette, handle block entities, and prepare the geometry for hologram rendering. Sources: src/index.html:112-140, src/HoloPrint.js:63-65
NBT Ingestion and Validation
The ingestion process begins with the readStructureNBT function, which utilizes the NBTify library to decode the binary format. Minecraft Bedrock structure files are typically little-endian. The system first attempts a little-endian read and falls back to generic settings if the initial attempt fails, ensuring compatibility with structures generated by external tools. Sources: src/HoloPrint.js:448-471
Validation Logic
A valid structure file must adhere to specific schema requirements identified during the parsing phase. The isNBTValidMcstructure function checks for:
format_versionmust be 1.sizemust be anInt32Arraywith exactly 3 elements (X, Y, Z dimensions).- Presence of the
structuretag. structure_world_originmust be anInt32Arrayof length 3.
Sources: src/HoloPrint.js:481-483
Structure File Flow
The following diagram illustrates the sequence from file upload to the finalized NBT object used in pack generation.
The diagram shows the multi-path ingestion strategy for structure data. Sources: src/HoloPrint.js:448-471, src/index.html:112-140
Block Palette Processing
After the NBT is parsed, the block data undergoes a "tweaking" phase via tweakBlockPalette. This stage is critical for normalizing block states and handling specific Bedrock Edition nuances like block entities and versioning. Sources: src/HoloPrint.js:508-510
Processing Steps
- Block Updating: The
BlockUpdaterutility checks if blocks require version updates to ensure compatibility with the latest Bedrock engine. Sources: src/HoloPrint.js:516-521 - Namespace Normalization: The
minecraft:prefix is stripped from block names for internal processing. Sources: src/HoloPrint.js:523 - Filter Ignored Blocks: Blocks specified in the
IGNORED_BLOCKSlist (e.g., air, light blocks, piston arms) are removed from the palette to prevent them from being rendered in the hologram. Sources: src/HoloPrint.js:23-23, src/HoloPrint.js:524-527 - Block Entity Integration: For blocks containing extra data (like signs or chests), the system clones the base block and appends the
block_entity_data. This ensures unique rendering or material list entries for blocks that look identical but have different NBT data. Sources: src/HoloPrint.js:540-562
Block Entity Schema
The following table describes the properties handled during block entity processing within the NBT structure.
| Field | Type | Description |
|---|---|---|
id | String | The block entity identifier (e.g., "Sign", "Chest"). |
x, y, z | Integer | Local coordinates within the structure (removed during palette tweaking). |
block_entity_data | Object | The raw NBT compound containing stateful info (text, items, etc.). |
Sources: src/HoloPrint.js:540-560, src/data/schemas/materialListMappings.schema.json:71-90
Data Models
The parsed structure is represented by a set of TypeScript-style interfaces derived from the NBT compound tags.
MCStructure Interface
This is the root object returned after a successful NBT read. Sources: src/HoloPrint.js:1062-1073
/**
* @typedef {object} MCStructure
* @property {number} format_version - Always 1.
* @property {I32Vec3} size - Structure dimensions.
* @property {object} structure - Main data container.
* @property {[Int32Array, Int32Array]} structure.block_indices - Indices for layer 0 and layer 1.
* @property {NBTBlock[]} structure.palette.default.block_palette - The list of unique blocks.
*/
NBTBlock Interface
Represents an individual entry in the block palette. Sources: src/HoloPrint.js:1017-1022
/**
* @typedef {object} NBTBlock
* @property {string} name - Block ID (e.g., "stone").
* @property {Record<string, number | string>} states - Map of block states.
* @property {number} version - The version of the block data.
*/
Internal Data Relationships
The relationship between the palette and indices defines how the structure is actually constructed in 3D space.
The ER diagram displays the relationship between the structure metadata and the actual block data. Sources: src/HoloPrint.js:1062-1073, src/HoloPrint.js:538-545
Advanced Mappings & Patches
Because Minecraft's internal IDs sometimes differ between block names and item names (needed for material lists), the system uses a mapping schema.
- Block to Item Mappings: Used when a block like
grass_blockneeds to be represented as the itemgrassin the UI. - Serialization ID Patches: Corrects IDs that do not match the expected
.langfile keys. - Special Block Entity Properties: Allows splitting a single block type into multiple material list entries based on NBT properties (e.g., different types of wood for signs).
Sources: src/data/schemas/materialListMappings.schema.json:20-50, src/data/textureAtlasMappings.json:3-10
Ignored Block Entities
Certain block entities are explicitly ignored during the parsing of block_position_data to optimize performance or avoid rendering issues.
- Beacon
- BrewingStand
- CommandBlock
- StructureBlock
- SculkSensor
Sources: src/HoloPrint.js:24-24
Summary
The parsing and NBT processing system in HoloPrint serves as the translation layer between binary Minecraft files and the internal representation required for 3D hologram generation. By validating schemas, updating block versions, and intelligently merging block entities into the palette, the system ensures that complex structures are accurately represented in the resulting resource pack. Sources: src/HoloPrint.js:564-568, src/HoloPrint.js:100-110