JSON Schemas for Mapping
Relevant source files
The following files were used as context for generating this wiki page:
HoloPrint utilizes a suite of JSON Schemas to define the structure and validation rules for mapping data used during the conversion of Minecraft Bedrock Edition (MCBE) structure files into resource packs. These schemas ensure that configurations for material lists, texture atlases, block geometries, and version upgrades remain consistent and strictly typed. By validating mapping files against these schemas, the project maintains high reliability when handling complex block states and entity properties.
The schemas are primarily used by internal modules such as MaterialList.js, TextureAtlas.js, and BlockGeoMaker.js to patch inconsistencies in vanilla Minecraft data or to provide custom logic for rendering holograms.
Data Validation Architecture
The project employs JSON Draft-07 schemas to validate critical mapping files. This architecture allows developers to define complex relationships between Minecraft block IDs and internal HoloPrint rendering logic.
The diagram above shows the relationship between validation schemas, the underlying JSON data, and the JavaScript modules that consume the validated data.
Sources: src/data/schemas/materialListMappings.schema.json, src/data/schemas/textureAtlasMappings.schema.json, src/data/schemas/blockShapeGeos.schema.json
Material List Mappings
The materialListMappings.schema.json defines how blocks are converted into item counts for the in-game material list. It includes patches for blocks with different item names and rules for multiplying item counts based on block entity properties.
Key Validation Properties
- ignored_blocks: An array of block names excluded from material lists.
- block_to_item_mappings: Maps specific block names or regex patterns to item names.
- item_count_multipliers: Defines numeric multipliers for specific items.
- special_block_entity_properties: Handles blocks that must be split based on NBT data (e.g., splitting a single block type into different items based on a property).
| Property | Type | Description |
|---|---|---|
ignored_blocks | Array | Blocks that will not appear in material lists. |
block_to_item_mappings | Object | Dictionary of block-to-item name overrides. |
item_count_multipliers | Object | Rules to multiply item counts (e.g., for slabs or double blocks). |
translation_patches | Object | Custom translations for IDs missing from .lang files. |
Sources: src/data/schemas/materialListMappings.schema.json:10-142
Texture Atlas Mappings
The textureAtlasMappings.schema.json manages how textures are fetched and applied to the hologram's texture atlas. This includes transparency overrides and tinting logic.
Texture and Tint Logic
- blocks_dot_json_patches: Corrects inconsistencies where a block name in
mojang-blocks.jsondoes not match the key inblocks.json. - transparent_blocks: Defines specific opacity values for blocks like water or slime.
- terrain_texture_tints: Maps texture keys to specific hex colors for biomes or custom effects.
This flow represents the logic defined in the Texture Atlas Schema to resolve IDs and apply necessary visual patches.
Sources: src/data/schemas/textureAtlasMappings.schema.json:10-100, src/HoloPrint.js:335-342
Block Shape Geometries
The blockShapeGeos.schema.json defines the geometry of "ghost blocks" used in the hologram. It allows for conditional rendering based on block states.
Geometry Properties
- if: A string-based expression evaluating block states to determine if a specific cube should render.
- pos/size: The 3D coordinates and dimensions of cubes within a 16x16x16 grid.
- uv: Direct mapping of texture coordinates for each face (north, south, east, west, up, down).
- copy: Inheritance mechanism to reuse geometry from another block shape.
Code Example: Geometry Definition
{
"pos": [0, 0, 0],
"size": [16, 16, 16],
"uv": {
"up": [0, 0],
"down": [16, 16]
},
"if": "entity.is_active == 1"
}
Sources: src/data/schemas/blockShapeGeos.schema.json:14-250, src/BlockGeoMaker.js:145-165
Block Upgrade Schemas
While not strictly a mapping schema, BlockUpdater.js implements a logic flow for upgrading blocks from older MCBE versions to the latest version. This relies on an internal schema index to apply renames, added properties, and flattened properties.
| Feature | Description |
|---|---|
renamedIds | Direct mapping of old block IDs to new ones. |
addedProperties | Injecting default states into old block definitions. |
flattenedProperties | Moving a block state value directly into the block ID. |
Sources: src/BlockUpdater.js:105-180
Conclusion
The JSON Schemas in HoloPrint provide the backbone for data consistency across the structure-to-resource-pack pipeline. By centralizing mapping logic into validated JSON files, the project abstracts complex Minecraft data inconsistencies away from the core processing logic, allowing for modular updates as new versions of Minecraft Bedrock Edition are released.