Block States & Eigenvariants

Relevant source files

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

• src/data/blockStateDefinitions.json
• src/BlockGeoMaker.js
• src/BlockUpdater.js
• src/HoloPrint.js
• src/data/schemas/index.ts
• src/data/schemas/blockStateDefinitions.schema.json

The Block States & Eigenvariants system within HoloPrint manages how Minecraft Bedrock Edition (MCBE) block data is interpreted to render accurate 3D holograms. This system handles the translation of NBT-based block properties—such as orientation, growth stages, and activation bits—into specific geometric rotations and texture variants.

This module ensures compatibility across different Minecraft versions by upgrading legacy block states and provides a mapping layer that connects raw block data to the visual representation in the resource pack. Eigenvariants serve as a specialized override mechanism for blocks that require pre-defined variant indices rather than dynamic state lookups.

Block State Architecture

HoloPrint treats blocks as a combination of a unique name and a set of states. These states are extracted from the .mcstructure NBT and processed to determine the final visual output.

Block Upgrading Logic

Minecraft Bedrock Edition frequently changes block names and state definitions. The BlockUpdater class is responsible for migrating older blocks to the latest version (currently 1.21.60.33).

The upgrade process includes:

• Flattening: Converting a property value into a new block name (e.g., specific colors of wool).
• Remapping: Changing property values or keys to match modern schemas.
• Renaming: Updating block IDs that have changed between versions.

Sources: src/BlockUpdater.js:28-150, src/HoloPrint.js:636-658

Texture Variants

Texture variants allow a single block type to display different textures based on its state. This is defined in blockStateDefinitions.json under the texture_variants object.

Variant Resolution Types

1. Global (*): Definitions applied to any block possessing the state (e.g., lit, powered_bit).
2. Block Shapes: Variants specific to a geometry type (e.g., cake bite levels).
3. Block Names: Direct overrides for specific block IDs (e.g., wheat growth stages).

Category	Example Block	State Used	Variant Mapping
Global	Observer	powered_bit	[0, 1]
Block Shape	Cake	bite_counter	[0, 1, 1, 1, 1, 1, 1]
Block Name	Creaking Heart	creaking_heart_state	uprooted:0, dormant:1, awake:2

Sources: src/data/blockStateDefinitions.json:5-75, src/BlockGeoMaker.js:467-518

Rotations

Rotations map block state values to 3D Euler angles (X, Y, Z in degrees). The BlockGeoMaker applies these rotations to block geometry templates during the pack generation process.

Rotation Priority

The system searches for rotation definitions in a specific hierarchy:

1. Exact Block Name: Checks if the specific block ID has a rotation override.
2. Block Shape: Checks if the geometry type (e.g., stairs, piston) has a rotation definition.
3. Global: Falls back to universal state mappings like facing_direction.

Example mappings for facing_direction:

• 0: [0, 0, 180] (Down)
• 1: [0, 0, 0] (Up)
• 2: [90, 180, 0] (South)
• 3: [90, 0, 0] (North)

Sources: src/data/blockStateDefinitions.json:76-130, src/BlockGeoMaker.js:337-360

Eigenvariants

Eigenvariants are pre-calculated variant indices for specific blocks that override the standard state-based texture lookup. They are defined as a simple mapping of block names to numeric indices.

Execution Logic in BlockGeoMaker

When BlockGeoMaker determines a texture variant, it first checks if the block exists in the blockEigenvariants data. If present, it uses that value immediately and skips further state analysis unless explicitly told to ignore the eigenvariant via geometry configuration.

// src/BlockGeoMaker.js:470-474
let eigenvariantExists = blockName in this.#eigenvariants;
if(!ignoreEigenvariant && eigenvariantExists) {
    let variant = this.#eigenvariants[blockName];
    return variant;
}

Sources: src/data/schemas/index.ts:1-5, src/BlockGeoMaker.js:468-475

Data Structures

Block Definition Schema

The BlockStateDefinitions interface structures the logic for both textures and rotations.

Field	Type	Description
texture_variants	BlockStateVariants	Mappings for terrain_texture.json indices.
rotations	Rotation	Mappings for XYZ Euler angles.
#exclusive_add	boolean	If true, multiple states add their indices together (e.g., Copper Bulbs).

Sources: src/data/schemas/index.ts:133-171, src/data/schemas/blockStateDefinitions.schema.json:30-100

NBT Block Structure

Blocks processed by the system follow this internal representation:

• name: The namespaced ID (e.g., minecraft:stone).
• states: A record of key-value pairs representing block properties.
• version: An integer representing the Minecraft data version.

Sources: src/HoloPrint.js:1071-1076, src/BlockUpdater.js:200-210

Summary

The Block States & Eigenvariants module acts as the "brain" for visual accuracy in HoloPrint. By combining version-safe state upgrading, hierarchical rotation lookups, and prioritized eigenvariant overrides, it ensures that complex structures exported from Minecraft Bedrock are rendered with the correct orientation and textures in the resulting hologram resource pack.