HoloBuilder

HoloBuilder is an original client-side Minecraft mod for loading a local structure file and displaying a construction hologram in-world.

The project is intentionally independent from Litematica: no Litematica code, class names, packages, internal architecture, file layout, or implementation details are reused.

Targets

Fabric and NeoForge are distributed as separate files for each Minecraft version. The 1.21.1 builds target 1.21.1 exactly and do not claim compatibility with later 1.21.x releases.

Modules

• common: loader-independent model, parsing, placement, comparison, and client state.
• fabric: Fabric entrypoint, key bindings, local game directory integration, and Fabric render event adapter.
• neoforge: NeoForge entrypoint, key bindings, local game directory integration, and NeoForge render event adapter.

Minecraft API references stay out of common. Loader modules adapt Minecraft client state into the small abstractions exposed by common.

MVP Behavior

At startup, the client creates:

<game directory>/holobuilder/schematics/
<game directory>/holobuilder/config.json

If the schematics folder has no example file yet, a simple .holo structure is written automatically. No schematic is loaded automatically at game startup; the player must choose one from the schematic screen.

The overlay compares the expected structure block states against the client world:

• Ghost block: expected block is missing because the world has air.
• Red ghost block: another block is present where the expected block should be.
• Green outline: expected block is already correct, only when enabled in the screen.

Expected minecraft:air blocks are ignored by the renderer. Missing and incorrect blocks are rendered as translucent ghost versions of the expected Minecraft block model, preserving block state properties such as slab half, stair facing, wall/fence shapes when those properties are present in the loaded schematic.

The full schematic volume is marked with an amber outline. When layer view is active, the selected Y layer is also marked with a blue outline.

The renderer only reads the client world. Placement features are opt-in, limited to creative mode, and use normal Minecraft /setblock commands.

Controls

• H: open the schematic selection screen.
• Numpad 5: reload the active schematic.
• Numpad 0: unload the active schematic.
• B: direct-build all missing/incorrect schematic blocks with /setblock when creative.
• V: toggle auto placer. While enabled, right-click places the hologram block currently being aimed at.
• C: toggle full auto build. While enabled, the aimed hologram block is placed automatically with a short cooldown.
• G: toggle schematic rendering. While the schematic is rendered, a HUD shortcut overlay stays visible without blocking player movement.
• Numpad 4 / 6: move placement left or right relative to the player's horizontal view direction.
• Numpad 3 / 9: move placement on Y.
• Numpad 8 / 2: move placement forward or backward relative to the player's horizontal view direction.
• Numpad + / -: rotate the schematic placement by 90 degrees clockwise or counter-clockwise.
• Numpad 1 / 7: enable layer view and show the lower or higher Y layer.
• X: return layer view to all layers.

Direct build, auto placer, and full auto build preserve the exact block state from the schematic, including the active 90-degree rotation. These build assist features require creative mode and send /setblock; on multiplayer servers, command execution still depends on server permissions.

Use /holo undo to restore the previous block states from the latest HoloBuilder build operation in the current session. Block-entity data such as container inventories cannot be restored client-side.

The selection screen lists supported files in holobuilder/schematics/:

• .holo
• .litematic
• .schem
• .schematic

Select a file and press Load to load it near the current player position.

The schematic screen is split into two panels: the left panel lists available schematic files, and the wider right panel previews the non-air blocks required by the active or selected schematic. The scrollable material panel can switch between list and mosaic views, shows block icons, formats counts as stacks plus remainder such as 4x64 + 29, shows block names on hover in mosaic view, and lets the player click a block entry to mark it with a green check while gathering resources.

The screen also exposes simple render settings:

• Hologram opacity.
• Show or hide already-correct blocks.
• Enable or disable outlines.
• Show or hide missing blocks.
• Show or hide incorrect blocks.
• Open the local schematics folder.

Hologram render distance follows Minecraft's effective render distance, capped by HoloBuilder's saved render-distance limit to avoid scanning and drawing far-away hologram blocks on high chunk-distance settings.

Performance Warning

Very large schematics can still cause significant FPS drops or stutters while the hologram is visible, especially with high render-distance settings or complex block states. For the smoothest experience, lower HoloBuilder's render distance, use layer view, hide already-correct blocks, or split very large builds into smaller schematics.

Structure Format

The first internal format is JSON:

{
  "format": "holobuilder.structure.v1",
  "name": "Example platform",
  "placement": [0, 64, 0],
  "palette": [
    "minecraft:oak_planks",
    "minecraft:glass"
  ],
  "regions": [
    {
      "name": "base",
      "origin": [0, 0, 0],
      "blocks": [
        { "pos": [0, 0, 0], "palette": 0 },
        { "pos": [1, 0, 0], "palette": 0 },
        { "pos": [0, 1, 0], "palette": 1 }
      ]
    }
  ]
}

Palette entries may be full block states, for example:

"minecraft:oak_stairs[facing=east,half=bottom,shape=straight,waterlogged=false]"

The common model separates palette entries, regions, relative positions, dimensions, metadata, and placement origin so future transforms can be added without rewriting loader code.

Planned Extension Points

• Rotation and mirror transforms in common.
• Material list aggregation from palette and block counts.
• Richer validation and metadata reporting for imported NBT formats.
• More complete legacy metadata conversion for old .schematic files.

Build

.\gradlew.bat :common:build :fabric:build :neoforge:build

Build artifacts are produced under:

• fabric/build/libs/
• neoforge/build/libs/

Release Notes

Publication helper files are available under release/:

• PROJECT_DESCRIPTION.md
• CHANGELOG_0.1.4.md
• UPLOAD_CHECKLIST.md
• holobuilder-icon-400.png

Join the official Discord:

HoloBuilder

HoloBuilder is an original client-side Minecraft mod for loading a local structure file and displaying a construction hologram in-world.

The project is intentionally independent from Litematica: no Litematica code, class names, packages, internal architecture, file layout, or implementation details are reused.

Targets

Fabric and NeoForge are distributed as separate files for each Minecraft version. The 1.21.1 builds target 1.21.1 exactly and do not claim compatibility with later 1.21.x releases.

Modules

• common: loader-independent model, parsing, placement, comparison, and client state.
• fabric: Fabric entrypoint, key bindings, local game directory integration, and Fabric render event adapter.
• neoforge: NeoForge entrypoint, key bindings, local game directory integration, and NeoForge render event adapter.

Minecraft API references stay out of common. Loader modules adapt Minecraft client state into the small abstractions exposed by common.

MVP Behavior

At startup, the client creates:

<game directory>/holobuilder/schematics/
<game directory>/holobuilder/config.json

If the schematics folder has no example file yet, a simple .holo structure is written automatically. No schematic is loaded automatically at game startup; the player must choose one from the schematic screen.

The overlay compares the expected structure block states against the client world:

• Ghost block: expected block is missing because the world has air.
• Red ghost block: another block is present where the expected block should be.
• Green outline: expected block is already correct, only when enabled in the screen.

Expected minecraft:air blocks are ignored by the renderer. Missing and incorrect blocks are rendered as translucent ghost versions of the expected Minecraft block model, preserving block state properties such as slab half, stair facing, wall/fence shapes when those properties are present in the loaded schematic.

The full schematic volume is marked with an amber outline. When layer view is active, the selected Y layer is also marked with a blue outline.

The renderer only reads the client world. Placement features are opt-in, limited to creative mode, and use normal Minecraft /setblock commands.

Controls

• H: open the schematic selection screen.
• Numpad 5: reload the active schematic.
• Numpad 0: unload the active schematic.
• B: direct-build all missing/incorrect schematic blocks with /setblock when creative.
• V: toggle auto placer. While enabled, right-click places the hologram block currently being aimed at.
• C: toggle full auto build. While enabled, the aimed hologram block is placed automatically with a short cooldown.
• G: toggle schematic rendering. While the schematic is rendered, a HUD shortcut overlay stays visible without blocking player movement.
• Numpad 4 / 6: move placement left or right relative to the player's horizontal view direction.
• Numpad 3 / 9: move placement on Y.
• Numpad 8 / 2: move placement forward or backward relative to the player's horizontal view direction.
• Numpad + / -: rotate the schematic placement by 90 degrees clockwise or counter-clockwise.
• Numpad 1 / 7: enable layer view and show the lower or higher Y layer.
• X: return layer view to all layers.

Direct build, auto placer, and full auto build preserve the exact block state from the schematic, including the active 90-degree rotation. These build assist features require creative mode and send /setblock; on multiplayer servers, command execution still depends on server permissions.

Use /holo undo to restore the previous block states from the latest HoloBuilder build operation in the current session. Block-entity data such as container inventories cannot be restored client-side.

The selection screen lists supported files in holobuilder/schematics/:

• .holo
• .litematic
• .schem
• .schematic

Select a file and press Load to load it near the current player position.

The schematic screen is split into two panels: the left panel lists available schematic files, and the wider right panel previews the non-air blocks required by the active or selected schematic. The scrollable material panel can switch between list and mosaic views, shows block icons, formats counts as stacks plus remainder such as 4x64 + 29, shows block names on hover in mosaic view, and lets the player click a block entry to mark it with a green check while gathering resources.

The screen also exposes simple render settings:

• Hologram opacity.
• Show or hide already-correct blocks.
• Enable or disable outlines.
• Show or hide missing blocks.
• Show or hide incorrect blocks.
• Open the local schematics folder.

Hologram render distance follows Minecraft's effective render distance, capped by HoloBuilder's saved render-distance limit to avoid scanning and drawing far-away hologram blocks on high chunk-distance settings.

Performance Warning

Very large schematics can still cause significant FPS drops or stutters while the hologram is visible, especially with high render-distance settings or complex block states. For the smoothest experience, lower HoloBuilder's render distance, use layer view, hide already-correct blocks, or split very large builds into smaller schematics.

Structure Format

The first internal format is JSON:

{
  "format": "holobuilder.structure.v1",
  "name": "Example platform",
  "placement": [0, 64, 0],
  "palette": [
    "minecraft:oak_planks",
    "minecraft:glass"
  ],
  "regions": [
    {
      "name": "base",
      "origin": [0, 0, 0],
      "blocks": [
        { "pos": [0, 0, 0], "palette": 0 },
        { "pos": [1, 0, 0], "palette": 0 },
        { "pos": [0, 1, 0], "palette": 1 }
      ]
    }
  ]
}

Palette entries may be full block states, for example:

"minecraft:oak_stairs[facing=east,half=bottom,shape=straight,waterlogged=false]"

The common model separates palette entries, regions, relative positions, dimensions, metadata, and placement origin so future transforms can be added without rewriting loader code.

Planned Extension Points

• Rotation and mirror transforms in common.
• Material list aggregation from palette and block counts.
• Richer validation and metadata reporting for imported NBT formats.
• More complete legacy metadata conversion for old .schematic files.

Build

.\gradlew.bat :common:build :fabric:build :neoforge:build

Build artifacts are produced under:

• fabric/build/libs/
• neoforge/build/libs/