Community编程与开发github.com

Minecraft 图片构建器

分析上传的 Minecraft 建筑图片或截图,反向推导精确尺寸、方块调色板、屋顶轮廓、立面深度以及隐藏的后侧/内部布局,生成详细的组件清单和坐标锚点表,并立即输出可下载的独立零依赖 Node.js (.mjs) 生成器文件,导出原版 Minecraft .nbt 结构文件 (Minecraft 26.3 / DataVersion 5023),无需提问。

Minecraft 图片构建器 是什么?

Minecraft 图片构建器是一项 AI Agent 技能,专为 Claude Code、Cursor 和 Codex 等平台设计。它的核心功能是:当用户提供 Minecraft 结构的图片或截图时,无需交互提问,自动完成完整的逆向工程和重建流程。该技能会执行四个阶段:首先,从图像中深度提取建筑蓝图、组件清单、尺寸比例和材料调色板(支持多面板技术参考图的合成分析)。其次,验证所有方块 ID 和状态属性与内置的 `registry_26_3.json`(对应 Minecraft 26.3 / DataVersion 5023)完全一致,确保原版兼容性。接着,将分析结果映射为精确的坐标锚点表和五遍构建规则(涉及外壳、框架、门窗、楼梯和内部家具的放置约束)。最后,生成一个自包含的、零依赖的 ESM (.mjs) 文件,该文件使用 `node:fs` 和 `node:zlib`,通过五遍分层构建(从地基到内饰)输出一个 gzip 压缩的 `.nbt` 文件,并附带 Shulkr 3D 查看器和 Minecraft 结构方块加载说明。该技能特别注重处理图像中的遮挡面,通过对称推理和内部布局标准(如 Sims 导航标准)自动补全后侧和内部设计,适用于房屋、塔楼、桥梁、雕像、家具、寺庙等多类结构。

兼容平台✓Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/marvaproject/minecraft-structure-builder/tree/HEAD/minecraft-builder-img

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Minecraft 图片构建器 是做什么的?

将用户上传的任何 Minecraft 结构图片或截图反向推导为精确的组件清单、坐标锚点表和可下载的独立零依赖 ESM (.mjs) 文件(优先使用文件生成工具,而不是在聊天中直接输出原始代码块),此文件可导出适用于 Minecraft 26.3(DataVersion: 5023)的 gzip 压缩原版 .nbt 文件,无需任何提问,一次性完成。

使用场景

  • 用户提供 Minecraft 建筑(房屋、小屋、塔楼、桥梁、水井、雕像、家具、庙宇或复合结构)的图片、截图或渲染图,并要求重建、复制、反向推导或生成 .nbt 或 Node.js 代码。
  • 用户希望直接获得可视化的分解结构、带结构的方块/组件列表以及即时的 .mjs 文件输出,无需来回沟通确认。

不适用场景

  • 纯文字创意构思(无图片提供)——应转交 minecraft-builder 技能进行从零开始的头脑风暴和建筑设计。
  • 红石电路、自定义地形/景观改造、容器 NBT 内容或实体摆 pose——明确说明限制,并仅重建静态外壳。

文件夹布局

minecraft-image-builder/
├── SKILL.md
└── registry_26_3.json

工作流程(直接执行 - 无需提问)

在提供图片时不要提出任何澄清性或头脑风暴式的问题。在单一回复中顺序执行以下所有四个阶段:

阶段 1:深度视觉分解与组件清单

从下到上、从前到后仔细检查图片,然后输出简洁、结构化的蓝图与组件清单:

  1. 多面板技术图纸与坐标轴对齐(如适用):
    • 当上传的图片是多面板技术参考图(例如,“01. 前右 3/4 视图”、“02. 后左 3/4 视图”、“03. 内部/结构细节视图”)时,将所有面板综合在一起分析,而不是视为独立的建筑。
    • 将 X、Y 和 Z 方向严格锁定为面板 01 的 3D XYZ 坐标轴小图标(红色 X,绿色 Y 向上,蓝色 Z)以及任何“前方”地面标签。忽略面板 02 中与面板 01 相机旋转冲突的翻转或重复的坐标轴箭头。
    • 交叉核对面板 01 和面板 02,提取所有 4 个外部立面而不猜测,并优先使用面板 03 的剖面图布局来确定内部房间隔断、楼梯和家具放置。
    • 忽略面板 03 中偶然出现的重复道具(如额外的灯笼或告示牌),这些道具在面板 01 和面板 02 中均未出现。
  2. 总体尺寸与比例(网格三角测量):
    • 通过沿宽度 (X)、高度 (Y) 和深度 (Z) 计数可见方块,估算精确的边界框 SIZE = [W, H, L],保持与截图一致的非 1:1:1 比例。
    • 如果墙壁或表面在 AI 生成的参考图像中显得光滑/非体素化,则根据 1x1 地面网格线、角落框架柱、窗格和屋顶台阶进行三角测量得出精确方块数,而不是根据光滑的墙面高度猜测。
    • 定义标高基准层:Y_base、Y_floor1、Y_floor2(如果是多层)、Y_roof_start 和 Y_roof_peak。
  3. 材料调色板分解(匹配到 registry_26_3.json):
    • 地基/底座: 例如 cobblestone、stone_bricks、tuff_bricks、deepslate_bricks。
    • 框架柱与横梁: 例如带有 axis 属性的 oak_log、spruce_log、stripped_dark_oak_log。
    • 主要与次要墙面: 例如 oak_planks、white_concrete、calcite、mud_bricks。
    • 屋顶与饰边: 例如 spruce_stairs、brick_stairs、deepslate_tile_stairs、台阶和悬挑饰边。
    • 开口、照明与外部细节: 窗户 (glass_pane)、百叶窗 (*_trapdoor)、门 (*_door)、栅栏/墙、灯笼、烟囱、藤蔓/植物以及在画面中可见的装饰性道具。
  4. 后侧与内部重建计划(遮挡面):
    • 对于在所有面板中仍然隐藏的任何面或内部角落,推断出对称或功能连贯的布局(匹配窗户节奏和屋顶坡度),并按照模拟人生导航标准(床/工作台/展示品,每 4x4 区域布置照明,以及可通行的 1x2 路径)干净地布置内部,无需询问用户。

阶段 2:方块注册表验证 (registry_26_3.json)

  • 根据技能目录中的 registry_26_3.json(Minecraft 26.3 / DataVersion: 5023)验证每个选定的方块 ID(minecraft:<name>)和状态属性。
  • 切勿创造虚构的方块 ID 或枚举值。如果截图中出现模组、光滑或非体素的道具(例如光滑石膏墙、空调、展示冰箱、文字标牌),将其转换为 registry_26_3.json 中最接近的有效原版 26.3 方块组合,并在组件清单中注明映射关系。

阶段 3:坐标锚点表与 5 遍构建规则

在编写代码之前,将组件清单映射为精确的坐标锚点表(X, Y, Z):

  1. 外壳与框架柱: 角柱 (X, Z) 坐标和外墙平面。
  2. 内部地板边界(X_min..X_max,Z_min..Z_max): 确保所有内部家具严格位于 X_wall_west + 1 .. X_wall_east - 1 和 Z_wall_north + 1 .. Z_wall_south - 1 范围内,使得第 5 遍永远不会覆盖墙壁。
  3. 门、窗与阳台: 精确的 (X, Y, Z) + facing,在门/门前和门后保持 1-2 块可通行的地面砖块,并确保任何有围栏的阳台在其外部栏杆内部有 >= 1 块可通行的地板行(depth >= 2)。
  4. 楼梯与阁楼屋脊对齐:
    • 使用明确的 shape: 'straight' 锁定可通行的楼梯台阶和楼梯椅,使 autoConnectStairs() 仅塑造屋顶楼梯的形状。
    • 任何通向倾斜屋顶上层/阁楼的楼梯必须在高中央屋脊(Y_roof_peak)下方终止,以便 carveStairHeadroom(x, y, z, 3) 永远不会穿透外部屋顶斜面。
    • 对于转角楼梯,使用一个与第 1 段顶部台阶平齐(Y_turn)的平坦 1x1(L 形转)或 1x2(U 形转)整块平台,在平坦平台上方保持 2 块空气,并在 Y_turn + 1 处开始第 2 段。
    • 仅在直接位于上升台阶上方的位置移除上层地板砖块,其中 step.y + 3 >= Y_upper,并用 *_fence 安全栏杆围绕开放的楼梯井边缘。
  5. 离散网格邻接与烟囱帽:
    • 墙壁安装物品(wall_torch、*_wall_sign、ladder、trapdoor 百叶窗、vine)占据相邻的空气方块(X_wall +/- 1 或 Z_wall +/- 1),切勿覆盖墙方块。
    • 对于延伸到屋顶尖顶上方的外部烟囱,检查顶部 campfire 周围所有 4 个水平邻居,并在每个与 air 相邻的边上放置打开的 *_trapdoor(open: 'true'、half: 'top')。

阶段 4:即时独立 .mjs 文件输出与运行说明

生成并导出完整的、自包含的 ESM 文件(<build-name>.mjs)作为可下载的 .mjs 文件(如果可用,使用 file_gen 工具——除非文件生成不可用,否则不要将完整的 .mjs 源代码作为原始 Markdown 代码块转储到聊天响应中),仅使用 node:fs 和 node:zlib,按5 遍分层构建顺序进行:

  • 第 1 遍: 地基、桩基和楼板。
  • 第 2 遍: 框架柱、外墙、窗户、阳台和门(placeDoor)。
  • 第 3 遍: 屋顶(1 块悬挑)和外部烟囱(带 4 面帽)。
  • 第 4 遍: 楼梯(shape: 'straight')、精确的楼梯井地板切口、安全栏杆和 carveStairHeadroom()。
  • 第 5 遍: 内部家具(在房间范围内)、placeBed()、墙壁附件、照明,然后依次是 autoConnectStairs()、autoPairDoubleDoors()、connectDoubleChests()、connectWalls() 和 connectFencesAndPanes()。

切勿包含运行时 throw new Error 验证函数,以确保脚本始终干净执行。始终以简短的运行命令、Shulkr 3D 查看器预览(https://www.shulkr.com/en/viewer)和 Minecraft 结构方块加载命令作为结尾。

独立 .mjs 模板

import fs from 'node:fs';
import zlib from 'node:zlib';

class NbtWriter {
  constructor() { this.chunks = []; }
  u8(v) { const b = Buffer.alloc(1); b.writeUInt8(v); this.chunks.push(b); }
  i16(v) { const b = Buffer.alloc(2); b.writeInt16BE(v); this.chunks.push(b); }
  i32(v) { const b = Buffer.alloc(4); b.writeInt32BE(v); this.chunks.push(b); }
  str(s) { const buf = Buffer.from(s, 'utf8'); this.i16(buf.length); this.chunks.push(buf); }
  tagHeader(type, name) { this.u8(type); this.str(name); }
  tagInt(name, v) { this.tagHeader(3, name); this.i32(v); }
  tagString(name, v) { this.tagHeader(8, name); this.str(v); }
  tagListHeader(name, elemType, length) { this.tagHeader(9, name); this.u8(elemType); this.i32(length); }
  tagCompoundStart(name) { this.tagHeader(10, name); }
  tagEnd() { this.u8(0); }
  toBuffer() { return Buffer.concat(this.chunks); }
}

const SIZE = [11, 12, 13];
const palette = [];
const paletteMap = new Map();
const blockGrid = new Map();

const DIR_VEC = {
  north: [0, -1],
  south: [0, 1],
  west: [-1, 0],
  east: [1, 0],
};
const LEFT_OF = { north: 'west', west: 'south', south: 'east', east: 'north' };
const RIGHT_OF = { north: 'east', east: 'south', south: 'west', west: 'north' };

function getStateIndex(name, props = {}) {
  const keys = Object.keys(props).sort();
  const key = `${name}|${keys.map((k) => `${k}=${props[k]}`).join(',')}`;
  if (!paletteMap.has(key)) {
    paletteMap.set(key, palette.length);
    palette.push({ Name: name, Properties: props });
  }
  return paletteMap.get(key);
}

function setBlock(x, y, z, name, props = {}) {
  if (x < 0 || x >= SIZE[0] || y < 0 || y >= SIZE[1] || z < 0 || z >= SIZE[2]) return;
  const posKey = `${x},${y},${z}`;
  if (name === 'minecraft:air') {
    blockGrid.delete(posKey);
    return;
  }
  blockGrid.set(posKey, { pos: [x, y, z], name, props, state: getStateIndex(name, props) });
}

function fill(x1, y1, z1, x2, y2, z2, name, props = {}) {
  for (let x = Math.min(x1, x2); x <= Math.max(x1, x2); x++) {
    for (let y = Math.min(y1, y2); y <= Math.max(y1, y2); y++) {
      for (let z = Math.min(z1, z2); z <= Math.max(z1, z2); z++) {
        setBlock(x, y, z, name, props);
      }
    }
  }
}

function placeDoor(x, y, z, blockId, facing = 'south', hinge = 'left', open = 'false') {
  setBlock(x, y, z, blockId, { facing, half: 'lower', hinge, open, powered: 'false' });
  setBlock(x, y + 1, z, blockId, { facing, half: 'upper', hinge, open, powered: 'false' });
}

function placeBed(headX, y, headZ, blockId = 'minecraft:red_bed', facing = 'north') {
  const [dx, dz] = DIR_VEC[facing] ?? [0, -1];
  setBlock(headX, y, headZ, blockId, { facing, part: 'head', occupied: 'false' });
  setBlock(headX - dx, y, headZ - dz, blockId, { facing, part: 'foot', occupied: 'false' });
}

function carveStairHeadroom(x, y, z, height = 3) {
  for (let dy = 1; dy <= height; dy++) {
    setBlock(x, y + dy, z, 'minecraft:air');
  }
}

function autoConnectStairs(skipPositions = new Set()) {
  for (const b of blockGrid.values()) {
    if (!b.name.endsWith('_stairs')) continue;
    const [x, y, z] = b.pos;
    if (skipPositions.has(`${x},${y},${z}`)) continue;
    if (b.props.shape !== undefined) continue;
    const f = b.props.facing;
    const half = b.props.half ?? 'bottom';
    if (!f || !DIR_VEC[f]) continue;

    const getStairAt = (nx, ny, nz) => {
      const nb = blockGrid.get(`${nx},${ny},${nz}`);
      if (!nb || !nb.name.endsWith('_stairs')) return null;
      if ((nb.props.half ?? 'bottom') !== half) return null;
      return nb.props.facing;
    };

    const [fx, fz] = DIR_VEC[f];
    const [lx, lz] = DIR_VEC[LEFT_OF[f]];
    const [rx, rz] = DIR_VEC[RIGHT_OF[f]];
    const frontFacing = getStairAt(x + fx, y, z + fz);
    const backFacing = getStairAt(x - fx, y, z - fz);
    const leftFacing = getStairAt(x + lx, y, z + lz);
    const rightFacing = getStairAt(x + rx, y, z + rz);
    let shape = 'straight';

    if (frontFacing === LEFT_OF[f] && rightFacing !== f) shape = 'outer_left';
    else if (frontFacing === RIGHT_OF[f] && leftFacing !== f) shape = 'outer_right';
    else if (backFacing === LEFT_OF[f] && leftFacing !== f) shape = 'inner_left';
    else if (backFacing === RIGHT_OF[f] && rightFacing !== f) shape = 'inner_right';

    const nextProps = {
      ...b.props,
      half,
      shape,
      waterlogged: b.props.waterlogged ?? 'false',
    };
    b.props = nextProps;
    b.state = getStateIndex(b.name, nextProps);
  }
}

function autoPairDoubleDoors() {
  const paired = new Set();
  for (const b of blockGrid.values()) {
    if (!b.name.endsWith('_door') || b.name === 'minecraft:iron_door') continue;
    if (b.props.half !== 'lower') continue;
    const [x, y, z] = b.pos;
    const key = `${x},${y},${z}`;
    if (paired.has(key)) continue;

    const f = b.props.facing ?? 'south';
    if (!DIR_VEC[f]) continue;
    const [lx, lz] = DIR_VEC[LEFT_OF[f]];
    const viewerRightKey = `${x + lx},${y},${z + lz}`;
    const neighborLower = blockGrid.get(viewerRightKey);

    if (
      neighborLower &&
      !paired.has(viewerRightKey) &&
      neighborLower.name === b.name &&
      neighborLower.props.half === 'lower' &&
      (neighborLower.props.facing ?? 'south') === f
    ) {
      const setDoorHinge = (dx, dz, hinge) => {
        for (const dy of [0, 1]) {
          const halfBlock = blockGrid.get(`${dx},${y + dy},${dz}`);
          if (halfBlock && halfBlock.name === b.name) {
            halfBlock.props = { ...halfBlock.props, hinge };
            halfBlock.state = getStateIndex(halfBlock.name, halfBlock.props);
          }
        }
      };
      setDoorHinge(x, z, 'left');
      setDoorHinge(x + lx, z + lz, 'right');
      paired.add(key);
      paired.add(viewerRightKey);
    }
  }
}

…

[为翻译而截断]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能