# Construction Skill

> 使用 VoxelBuilder API 生成 JavaScript 代码来建造结构。在建筑时务必使用此技能来查看和创建实际的建筑代码。

- Skill: `justcnds/construction-skill` (Agent Skill, multi-file: 27 files)
- Install (CLI): `npx skillmds@latest add justcnds/construction-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justcnds/construction-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: justcnds (https://skillmd.com/u/justcnds)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/justcnds/construction-skill

---


# 📝 建造技能 (Construction Skill)

使用 VoxelBuilder API 生成 JavaScript 代码来建造高品质体素建筑。

## VoxelBuilder API

### 基础方块操作
| 方法 | 用途 |
|------|------|
| `builder.set(x, y, z, block)` | 放置单个方块 |
| `builder.get(x, y, z)` | 获取指定位置方块 |
| `builder.fill(x1, y1, z1, x2, y2, z2, block)` | 填充立方体区域 |
| `builder.walls(x1, y1, z1, x2, y2, z2, block)` | 建四面墙（空心） |
| `builder.line(x1, y1, z1, x2, y2, z2, block)` | 画直线/斜线 |
| `builder.clear(...)` | 清空区域 |

### 分组与优先级 (Groups & Priority)
| 方法 | 用途 |
|------|------|
| `builder.beginGroup(name, { priority })` | 开始分组 |
| `builder.endGroup()` | 结束分组 |
| `builder.setPriority(n)` | 设置当前优先级 |

统一优先级分层：`door=100`, `frame=95`, `windows=70`, `roof=60`, `walls=50`, `decor=20`, `foundation=10`

### 门窗
| 方法 | 用途 |
|------|------|
| `builder.setDoor(x, y, z, type)` | 放置双格门 (如 'oak_door') |

### 屋顶与山墙 (Roofs & Auto-Gable)
| 方法 | 用途 |
|------|------|
| `builder.drawRoofBounds(x1, y, z1, x2, z2, height, style, material, opts)` | 矩形屋顶 |
| `builder.drawPolyRoof(x, y, z, radius, height, sides, style, material)` | 多边形/圆形屋顶 |

- `style`: `straight` / `gambrel` / `arch` / `cone` / `dome` / `curve` / `steep`
- `opts`: `{ gable: '墙体材料', ridge: '屋脊材料' }`
- **⚠️ 重要规范**：屋顶两侧的人字形山墙**严禁手动写 for 循环**！直接在 `opts` 中传入 `{ gable: 'WALL_MATERIAL' }`，系统引擎会自动精准封闭山墙且无任何错位缝隙。

### 几何体
| 方法 | 用途 |
|------|------|
| `builder.drawCylinder(x,y,z,r,h,mat,opts)` | 圆柱体 |
| `builder.drawSphere(x,y,z,r,mat,opts)` | 球体 |
| `builder.drawEllipsoid(x,y,z,rx,ry,rz,mat,opts)` | 椭球体 |
| `builder.drawPolygon(x,y,z,r,sides,h,mat,opts)` | 多边形柱 |
| `builder.drawPyramid(x,y,z,base,h,mat,opts)` | 金字塔 |
| `builder.drawTorus(x,y,z,R,r,mat,opts)` | 圆环 |

**通用 options:**
- `hollow`: 是否空心
- `thickness`: 壁厚
- `axis`: 'y'|'x'|'z' (简单轴向)
- `noise`: { amount, scale } (有机自然起伏，适合树木/山体)
- `rotateX/Y/Z`: 任意角度旋转 (度数)

### 曲线与装饰
| 方法 | 用途 |
|------|------|
| `builder.drawBezier(points,mat,w)` | 贝塞尔曲线 (用于弯曲藤蔓/树干) |
| `builder.scatter(x1,y,z1,x2,z2,d,types)` | 2D地面散布花草 |
| `builder.scatter3D(...)` | 3D空间散布 |
| `builder.drawHanging(x,y,z,opts)` | 单点悬挂物 (灯笼/链条) |
| `builder.drawHangingRing(x,y,z,r,opts)` | 环形悬挂 |
| `builder.drawSpiralStairs(x,y,z,r,h,mat)` | 螺旋楼梯 |

### 组件系统
| 方法 | 用途 |
|------|------|
| `builder.defineComponent(name, (b, params) => { ... })` | 定义组件 (组件内部必须使用传入的 `b` 参数) |
| `builder.placeComponent(name, x, y, z, options)` | 放置组件 |

### 方块属性语法规范
```javascript
'stone'                                      // 普通方块
'oak_stairs?facing=north'                    // 楼梯正放与朝向
'stone_brick_stairs?facing=south,half=top'   // 楼梯倒放 (檐口椽头)
'oak_door?facing=south,half=lower'           // 门下半
'spruce_trapdoor?facing=east,open=true'      // 活板门做百叶窗
'oak_log?axis=x'                             // 原木横放
'lantern?hanging=true'                       // 悬挂灯笼
```

## 使用方法

想了解各函数的具体用法，请使用 `read_subdoc` 查阅子文档，例如：
```json
{ "name": "read_subdoc", "arguments": { "skill": "construction-skill", "doc": "resources/drawRoofBounds" } }
```