Structure Validation Particles
Relevant source files
The following files were used as context for generating this wiki page:
Structure Validation Particles are a specialized visual feedback system within HoloPrint designed to assist users in accurately recreating builds in Minecraft Bedrock Edition. By leveraging custom particle effects and geometric locators, the system highlights where blocks are missing or incorrectly placed relative to the loaded .mcstructure file.
The system operates by spawning particles at specific block coordinates. These particles are configured using the Bedrock engine's minecraft:particle_expire_if_in_blocks component, causing them to automatically disappear once the user places the correct block at the designated location. This provides a real-time, interactive checklist for building.
Sources: README.md:21, src/HoloPrint.js:447-452, src/HoloPrint.js:513-520
Architecture and Data Flow
The generation of validation particles is integrated into the core pack-making pipeline. During the execution of makePack, the system scans the structure NBT to identify every block position that requires validation.
Particle Generation Logic
- Block Scanning: The system iterates through the structure's dimensions (X, Y, Z). For every block on the primary layer (layer 0), a validation entry is created.
- Locator Assignment: Each block position is assigned a unique locator name in the format
b_x_y_zwithin the entity geometry. - Unique Particle Definition: To optimize performance, the system identifies all unique block types in the structure and generates a single particle JSON file for each type (e.g.,
holoprint:validate_stone). - Expiration Condition: Each generated particle file contains a
minecraft:particle_expire_if_in_blockscomponent set to the specific block ID it represents.
The following diagram illustrates the data flow from structure file input to the creation of validation components:
Component Breakdown
Geometric Locators
Validation particles rely on a "particle alignment" geometry (geometry.holoprint.hologram.particle_alignment). This geometry contains specific bones and locators that act as anchor points for particle emitters.
- Locator Naming:
b_[x]_[y]_[z] - Parent Bone:
hologram_offset_wrapper - Function: Ensures particles stay attached to the hologram even if it is moved or rotated using in-game controls.
Sources: src/HoloPrint.js:313-315, src/packTemplate/models/entity/holoprint.hologram.geo.json:76-88
Animation Controller State Machine
The logic for showing and hiding validation particles is handled by controller.animation.holoprint.hologram.block_validation. This controller manages transitions based on whether the user has activated the "Validating" mode (typically via an Iron Ingot) and which structure layer is currently selected.
Sources: src/HoloPrint.js:527-589, src/HoloPrint.js:464
Particle Component Configuration
Each validation particle is defined by a template that modifies the Bedrock particle engine behavior.
| Component | Description | Source |
|---|---|---|
identifier | holoprint:validate_[block_name] | src/HoloPrint.js:516 |
minecraft:particle_expire_if_in_blocks | List containing the correct block ID; triggers particle removal. | src/HoloPrint.js:518 |
locator | Tied to b_x_y_z to ensure spatial accuracy. | src/HoloPrint.js:578 |
v.x, v.y, v.z | Molang variables used for setting individual particle positions. | src/HoloPrint.js:581-583 |
User Controls and Interaction
The validation system is toggleable in-game. By default, it is mapped to a specific item criteria, though users can customize this during the pack generation process.
Activation Mechanism
- Trigger Item: Iron Ingot (Default).
- Control: The system checks if the player is holding the required item and updates the
v.hologram.validatingMolang variable. - Feedback: When active, particles appear at all incorrect block locations. If the hologram is in "Single Layer" mode, only particles for the current Y-level are displayed to reduce visual clutter.
Sources: README.md:21, src/HoloPrint.js:46-60, src/HoloPrint.js:464, src/translations/en_US.json:34
Configuration Options
Users can adjust how validation behaves through the web interface before generating the .mcpack.
| Setting | Type | Description |
|---|---|---|
TOGGLE_VALIDATING | Item Criteria | Defines which item(s) or tag(s) trigger the validation mode. |
IGNORED_BLOCKS | String Array | Blocks like "air" or "light_block" that should never spawn validation particles. |
WRONG_BLOCK_OVERLAY_COLOR | Vec4 (RGBA) | Color of the overlay that appears when a block is incorrect. |
| Sources: src/HoloPrint.js:58, src/HoloPrint.js:15, src/HoloPrint.js:425, src/index.html:150 |
Implementation Details in Pack Generation
The function addBlockValidationParticles dynamically builds the animation controller states. It generates a "validate_all" state for when the entire structure is being checked and individual layer states (e.g., validate_0_l_5) for layer-by-layer building.
// src/HoloPrint.js:577
let particleEffect = {
"effect": `validate_${blockToValidate["block"].replace(":", ".")}`,
"locator": blockToValidate["locator"],
"pre_effect_script": `
v.x = ${x};
v.y = ${y};
v.z = ${z};
`.replaceAll(/\s/g, "")
};
This ensures that the particle effect is precisely aligned with the block's world position relative to the hologram's root.
Sources: src/HoloPrint.js:577-586
Summary
Structure Validation Particles provide a critical bridge between the 3D hologram and the actual game world. By utilizing locators within the entity geometry and block-aware expiration components, the system offers a reactive building guide that helps players maintain 100% accuracy in their structures.