minecraft-builder-skill

Minecraft Builder Skill

概述

通过编写使用 Lodestone 辅助函数的小型 JavaScript 配方来创建 Minecraft 建筑。导出原版 .nbt 结构文件，然后打开随附的查看器，以便用户检查并迭代修改建筑。

工作流

1. 在已安装的技能目录中操作。安装后不要重新运行 Skills CLI；使用此技能本地的 scripts/ 和 assets/。
2. 运行任何建筑或预览脚本之前，确保已安装依赖项。如果缺少 node_modules/@mattzh72/lodestone，请在已安装的技能目录中运行：

npm install --omit=dev

3. 编写一个 ESM 配方文件。对于大型浮空巨构，请将 assets/examples/celestial-forge.mjs 用作规范示例。
4. 生成 NBT：

node scripts/run-build.mjs path/to/recipe.mjs --out-dir minecraft-builds/my-build

5. 打开预览：

node scripts/preview.mjs --nbt minecraft-builds/my-build/my-build.nbt

6. 通过编辑配方、重新生成 .nbt 并重新打开或刷新预览来迭代修改。

依赖项

Skills CLI 安装会复制技能文件，但可能不会安装 Node 包。此技能会将依赖项保存在 package.json 和 npm-shrinkwrap.json 中，而不随附 node_modules。

使用 scripts/run-build.mjs 或 scripts/preview.mjs 之前，请检查是否存在 node_modules/@mattzh72/lodestone。如果不存在，请在已安装的技能目录中运行 npm install --omit=dev。不要全局安装依赖项，也不要猜测其他 Lodestone 版本。

配方约定

导出一个默认函数，该函数接收 api，并返回 Lodestone Structure，或包含 { structure, metadata } 的对象。

export default function build(api) {
  const structure = api.createStructure([16, 12, 16])
  api.fill(structure, [0, 0, 0], [15, 0, 15], 'minecraft:stone_bricks')
  api.hollowBox(structure, [4, 1, 4], [11, 7, 11], 'minecraft:spruce_planks')
  return { structure, metadata: { name: 'example-build' } }
}

可用的辅助函数包括 createStructure、setBlock、fill、hollowBox、line、sphere、cylinder、normalizeBlock、createBlockNbt，以及 api.lodestone 下的 Lodestone 类。

参考资料

• 有关配方辅助函数的准确签名、支持的选项字段、默认值和不支持的行为，请查阅 references/recipe-api.md。
• 有关 Lodestone 类、结构 NBT、方块状态、渲染器 API、资源包 API、支持的字段和不支持的行为，请查阅 references/lodestone/。
• 有关默认包的准确方块 ID、渲染方块状态的枚举值、特殊渲染器状态值，以及 waterlogged 等通用渲染器属性，请查阅 references/lodestone/default-pack-block-states.md。
• 优先查阅这些本地参考资料，不要凭猜测操作。使用 rg 查找类名、方法名、方块状态属性、NBT 标签名和选项字段，再使用高级 API。

参考资料查找

• 选择非平凡的方块状态值之前，请查阅 references/lodestone/default-pack-block-states.md。
• 对于单个方块，请打印其完整章节，例如 rg -n -A 80 '### `minecraft:oak_stairs`' references/lodestone/default-pack-block-states.md。
• 对于全局属性枚举，请搜索属性索引行，例如 rg -n '^- `shape`|^- `waterlogged`' references/lodestone/default-pack-block-states.md。
• 依赖自动连接行为之前，请在 references/lodestone/structure.md 中搜索 updateBlockStates()，并检查其支持和不支持的覆盖范围。
• 编写方块实体或自定义 NBT 之前，请查阅 references/lodestone/nbt.md 和 references/recipe-api.md，再构造标签。

构建指南

• 确保所有坐标都在结构尺寸范围内。运行器会验证边界，发现越界时立即失败。
• 使用带有 minecraft: 命名空间的原版方块 ID。支持 minecraft:oak_stairs[facing=east,half=bottom,shape=straight] 这样的方块状态字符串。
• 运行器默认启用 Lodestone 类 Minecraft 的方块状态更新。玻璃板、铁栏杆和栅栏会根据相邻的兼容方块或实心方块获得 north/east/south/west 状态。只有在配方需要手动设置这些状态时，才使用 --no-block-state-updates。
• 优先使用清晰的方块调色板和易读的几何结构。查看器使用 Lodestone 自带的默认资源包，因此非常罕见或自定义的方块可能无法正常预览。
• 使用 metadata.name 控制输出文件名。名称会转换为 slug 格式。
• 默认情况下，输出为 gzip 压缩的原版结构 NBT，DataVersion 由运行器设置，除非另行指定。
• 对于方块实体，将 Lodestone NbtCompound 作为最后一个参数传给 setBlock，或使用 api.createBlockNbt({ id: 'minecraft:chest' })。

预览

预览脚本会启动一个最简 Vite 服务并自动打开构建结果。它通过本地中间件提供目标 .nbt 文件和 Lodestone 的默认资源包，因此配方无需复制资源。

在非交互式环境中运行时，使用 --no-open：

node scripts/preview.mjs --nbt path/to/build.nbt --no-open

需要时，可直接以夜间光照打开以便检查：

node scripts/preview.mjs --nbt path/to/build.nbt --lighting night