HoloBuilder - 蓝图加载器

HoloBuilder - 蓝图加载器

客户端侧原理图全息投影构建器，支持Fabric和NeoForge。

![Discord](https://img.shields.io/badge/Discord-Join Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)

HoloBuilder

HoloBuilder 是一个原创的客户端侧 Minecraft 模组，用于加载本地结构文件并在世界中显示建筑全息投影。

该项目有意独立于 Litematica：未复用任何 Litematica 的代码、类名、包名、内部架构、文件布局或实现细节。

目标版本

Minecraft Java Fabric Loader Fabric API NeoForge
1.21.1 21 0.19.3 0.116.13+1.21.1 21.1.235
26.1.2 25 0.19.3 0.152.1+26.1.2 26.1.2.76

Fabric 和 NeoForge 版本以独立文件形式针对每个 Minecraft 版本分发。1.21.1 的构建目标严格对应 1.21.1，不声称与后续的 1.21.x 版本兼容。

模块

  • common：与加载器无关的模型、解析、放置、比较和客户端状态。
  • fabric：Fabric 入口点、按键绑定、本地游戏目录集成和 Fabric 渲染事件适配器。
  • neoforge：NeoForge 入口点、按键绑定、本地游戏目录集成和 NeoForge 渲染事件适配器。

Minecraft API 的引用不会进入 common 模块。加载器模块将 Minecraft 客户端状态适配为 common 模块暴露的少量抽象接口。

MVP 行为

启动时，客户端会创建：

<游戏目录>/holobuilder/schematics/
<游戏目录>/holobuilder/config.json

如果 schematics 文件夹中尚无示例文件，会自动写入一个简单的 .holo 结构。游戏启动时不会自动加载任何原理图；玩家必须从原理图界面中选择一个。

叠加层会将预期的结构方块状态与客户端世界进行比较：

  • 幽灵方块：预期方块缺失，因为世界中的位置是空气。
  • 红色幽灵方块：预期方块应处的位置被其他方块占据。
  • 绿色轮廓：预期方块已正确放置，仅在界面中启用此选项时显示。

渲染器会忽略预期的 minecraft:air 方块。缺失和错误的方块会以半透明的幽灵版本形式渲染，显示为预期的 Minecraft 方块模型，并保留加载原理图中所包含的方块状态属性，例如上半砖、楼梯朝向、墙/栅栏形状等。

整个原理图体积会以琥珀色轮廓标记。当图层视图激活时，选中的 Y 层还会以蓝色轮廓标记。

渲染器只读取客户端世界。放置功能是自愿加入的，仅限于创造模式，并使用标准的 Minecraft /setblock 命令。

操作控制

  • H：打开原理图选择界面。
  • 数字键盘 5：重新加载当前激活的原理图。
  • 数字键盘 0：卸载当前激活的原理图。
  • B：在创造模式下，使用 /setblock 直接建造所有缺失/错误的原理图方块。
  • V：切换自动放置器。启用后，右键点击即可放置全息投影中当前瞄准的方块。
  • C：切换全自动建造。启用后，瞄准的全息投影方块会以短暂冷却时间自动放置。
  • G：切换原理图渲染。当原理图渲染时，HUD 快捷方式叠加层会保持可见，且不会阻挡玩家移动。
  • 数字键盘 4 / 6：相对于玩家水平视角方向，向左或向右移动放置位置。
  • 数字键盘 3 / 9：在 Y 轴上移动放置位置。
  • 数字键盘 8 / 2：相对于玩家水平视角方向，向前或向后移动放置位置。
  • 数字键盘 + / -：将原理图放置位置顺时针或逆时针旋转 90 度。
  • 数字键盘 1 / 7：启用图层视图，并显示较低或较高的 Y 层。
  • X：将图层视图恢复为显示所有层。

直接建造、自动放置器和全自动建造会保留原理图中的精确方块状态，包括当前应用的 90 度旋转。这些建造辅助功能需要创造模式，并发送 /setblock 命令；在多人游戏服务器上，命令执行仍取决于服务器权限。

使用 /holo undo 来恢复当前会话中 HoloBuilder 最近一次建造操作之前的方块状态。方块实体数据（如容器中的物品）无法在客户端侧恢复。

选择界面会列出 holobuilder/schematics/ 中支持的文件：

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

选择一个文件，然后按 加载 将其加载到当前玩家位置附近。

原理图界面分为两个面板：左侧面板列出可用的原理图文件，较宽的右侧面板预览当前或所选原理图所需的非空气方块。可滚动的材料面板可以在列表视图和拼贴视图之间切换，显示方块图标，将数量格式化为“组数 + 余数”，例如 4x64 + 29，在拼贴视图中悬停时显示方块名称，并允许玩家点击方块条目以在收集资源时用绿色勾选标记它。

界面还提供简单的渲染设置：

  • 全息投影不透明度。
  • 显示或隐藏已正确放置的方块。
  • 启用或禁用轮廓。
  • 显示或隐藏缺失方块。
  • 显示或隐藏错误方块。
  • 打开本地原理图文件夹。

全息投影渲染距离遵循 Minecraft 的有效渲染距离，但受 HoloBuilder 保存的渲染距离上限限制，以避免在高区块距离设置下扫描和绘制远处的全息投影方块。

性能警告

非常大的原理图在显示全息投影时仍可能导致显著的 FPS 下降或卡顿，尤其是在高渲染距离设置或复杂方块状态的情况下。为获得最流畅的体验，请调低 HoloBuilder 的渲染距离，使用图层视图，隐藏已正确放置的方块，或将大型建筑拆分成多个较小的原理图。

结构格式

第一种内部格式是 JSON：

{
  "format": "holobuilder.structure.v1",
  "name": "示例平台",
  "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 }
      ]
    }
  ]
}

调色板条目可以是完整的方块状态，例如：

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

通用模型将调色板条目、区域、相对位置、尺寸、元数据和放置原点分离开来，以便将来可以在不重写加载器代码的情况下添加变换功能。

计划中的扩展点

  • common 模块中的旋转和镜像变换。
  • 基于调色板和方块数量的材料列表聚合。
  • 对导入的 NBT 格式进行更丰富的验证和元数据报告。
  • 对旧的 .schematic 文件进行更完整的遗留元数据转换。

构建

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

构建产物位于：

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

加入官方 Discord：

Discord