construction-skill

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

📝 建造技能 (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)	放置组件

方块属性语法规范

'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 查阅子文档，例如：

{ "name": "read_subdoc", "arguments": { "skill": "construction-skill", "doc": "resources/drawRoofBounds" } }