Texture & Material Mappings
Relevant source files
The following files were used as context for generating this wiki page:
Texture & Material Mappings represent the data-driven layer of HoloPrint that bridges the gap between Minecraft Bedrock Edition (MCBE) internal block data and the visual/functional requirements of a resource pack. These mappings handle inconsistencies in vanilla naming conventions, define visual overrides like transparency or tints, and ensure that material lists correctly translate block data into player-facing item counts.
Sources: src/MaterialList.js, src/TextureAtlas.js, src/data/textureAtlasMappings.json
Material List Architecture
The material list system processes block data from .mcstructure files to generate a comprehensive count of items required to build a structure. It utilizes a series of JSON-defined patches to handle complex cases where a block does not have a 1:1 mapping to an item (e.g., a placed "trip_wire" block resulting from a "string" item).
Data Transformation Flow
The following diagram illustrates how the MaterialList class transforms a block entry into a translated material list entry.
Core Components and Mapping Types
The MaterialList class relies on several specific mapping categories defined in materialListMappings.json:
| Mapping Category | Purpose | Example |
|---|---|---|
block_to_item_mappings | Maps internal block names to the items used to place them. | trip_wire -> string |
item_count_multipliers | Adjusts counts for items that drop in multiples or have special removal rules. | glow_lichen multiplier: 1 |
special_block_entity_properties | Splits items based on NBT data, such as colors. | Shulker Boxes (by color property) |
serialization_id_patches | Corrects tile.* or item.* IDs that do not match .lang file keys. | tile.grass.name fix |
Sources: src/MaterialList.js:28-50, src/data/schemas/materialListMappings.schema.json:10-100
Count Partitioning
To assist players in gathering materials, the system partitions large counts into Shulker Boxes and stacks. A custom glyph (\uE200) is used to represent a Shulker Box in the UI.
- Shulker Box: 1728 items (27 stacks of 64).
- Stacks: Remainder divided by 64.
- Format:
Total = [Boxes] + [Stacks] + [Remainder](e.g.,2000 = 1 + 4s + 16).
Sources: src/MaterialList.js:180-188
Texture Atlas Mappings
The Texture Atlas system manages the visual representation of blocks by stitching individual textures into a single atlas. This process involves resolving vanilla blocks.json references and applying custom visual corrections.
Texture Processing Pipeline
Sources: src/TextureAtlas.js:77-180
Mapping and Override Logic
The system handles several edge cases through textureAtlasMappings.json:
- blocks.json Patches: Resolves inconsistencies where the block name does not match the key in the vanilla
blocks.json(e.g.,grass_blockmapping tograss). - Carried Textures: Identifies blocks that should use their "carried" (item) texture rather than their world-block texture, such as leaves or grass.
- Transparency Overrides: Manually sets opacity for specific blocks. For example,
wateris set to0.65opacity, whileslimeis set to0.8. - Tints: Defines foliage and water colors to be applied to greyscale textures.
Sources: src/data/textureAtlasMappings.json:3-50, src/TextureAtlas.js:255-300
Tinting Data Model
Tints are defined either as 6-digit hex strings or linked to specific color keys (foliage, water).
| Field | Type | Description |
|---|---|---|
colors | Object | Map of color names to Hex codes (e.g., "foliage": "#79C05A"). |
terrain_texture_keys | Object | Map of texture names to a color or a tint configuration. |
tint_like_png | Boolean | If true, forces TGA textures to use PNG-style tinting logic. |
Sources: src/data/schemas/textureAtlasMappings.schema.json:42-100, src/data/textureAtlasMappings.json:16-43
Integration in Pack Generation
The HoloPrint.js module orchestrates these mappings during the resource pack creation process. It initializes the MaterialList and TextureAtlas using the data files and the user's provided resource pack stack.
// src/HoloPrint.js:220-224
let data = await dataPromise.all;
let textureAtlas = new TextureAtlas(config, resourcePackStack, blocksDotJson, vanillaTerrainTexture, flipbookTextures, data.textureAtlasMappings);
let materialList = new MaterialList(bedrockMetadata.blocks, bedrockMetadata.items, data.materialListMappings);
The MaterialList entries are specifically used to populate the holoprint_material_list.json UI and the pack's texts/*.lang files, providing users with a localized bill of materials.
Sources: src/HoloPrint.js:220-225, src/HoloPrint.js:460-475
Conclusion
Texture & Material Mappings provide the necessary logic to handle the complexities of the Minecraft Bedrock data format. By separating these definitions into JSON mapping files, the project maintains a clean architecture that can be easily updated to support new Minecraft versions without significant code changes. The MaterialList ensures functional accuracy for gameplay, while the TextureAtlas ensures visual fidelity through a robust override system.
Sources: src/data/materialListMappings.json, src/data/textureAtlasMappings.json