建筑系统 (building)

蓝图系统允许 AI 助手生成建筑蓝图，并在游戏内逐层逐块动画建造。玩家还可以通过分享码将蓝图分享给其他人。

扩展包

蓝图系统作为 building 扩展包提供，需要将 arkpilot-building.jar 放入 plugins/ArkPilot/expansions/ 目录。

使用流程

1. 让 AI 生成蓝图

与建筑助手对话，描述你想要的建筑：

@builder 帮我建一个 7x7 的橡木小屋，有尖顶

建筑助手会调用蓝图生成器，生成建筑蓝图 JSON，校验后开始建造。

2. 确认建造

建造前会弹出确认提示：

将在 (100, 64, 200) 建造 1500 个方块: [✓ 确认建造] [✗ 取消]

蓝图支持网页预览，确认提示中可能包含 [⌂ 预览] 按钮，点击可在浏览器中查看 3D 预览。

3. 建造过程

确认后开始逐层逐块动画建造，聊天栏会显示进度：

[⚒ 建造中] 小木屋 (350/1500)

4. 建造控制

建造过程中可随时控制：

命令	说明
/blueprint pause	暂停建造
/blueprint resume	恢复建造
/blueprint cancel	取消建造

5. 分享蓝图

建造完成后，可将蓝图上传并获取分享码：

/blueprint share

成功后获得 6 位分享码（如 Ab3xK9），其他玩家使用分享码即可建造相同建筑：

/blueprint Ab3xK9

蓝图网站

蓝图系统提供一个配套网站，用于：

• 3D 预览：在浏览器中旋转、缩放查看蓝图的 3D 效果
• 分享页面：通过分享码在网页上查看蓝图详情

默认网站地址：https://arkpilot-blueprint.pages.dev

玩家可以：

1. 在建造确认时点击 [⌂ 预览] 按钮打开 3D 预览
2. 通过分享码访问 https://arkpilot-blueprint.pages.dev/share/分享码 查看蓝图

配置

蓝图配置位于扩展包目录 plugins/ArkPilot/expansions/building/config.yml（首次加载自动生成）：

blueprint:
  # 是否启用蓝图系统
  enabled: true
  # 蓝图 API 地址（用于上传/下载蓝图和网页预览）
  apiBaseUrl: "https://arkpilot-blueprint.pages.dev"
  # 单个蓝图最大方块数（防止过大蓝图卡服）
  maxBlocks: 50000
  # 每 tick 最大放置方块数（值越小越流畅，但建造越慢）
  maxBlocksPerTick: 50

参数调优

参数	建议	说明
maxBlocks	10000-50000	根据服务器性能调整
maxBlocksPerTick	20-100	20 = 流畅但慢，100 = 快但可能卡顿

相关助手

蓝图系统涉及两个助手协作：

1. 建筑助手（builder）：面向玩家，接收建筑需求，通过 call-agent 调用蓝图生成器
2. 蓝图生成器（blueprint-generator）：内部助手（internal: true），不出现在 GUI 中，不接受玩家直接对话，仅由 builder 通过 call-agent 调用来生成蓝图 JSON 并执行建造

玩家 → @builder 建个小屋 → builder 调用 blueprint-generator → 生成蓝图 → 建造

这两个助手配置随 building 扩展包提供，位于 expansions/building/assistants/ 目录。

命令汇总

命令	说明
/blueprint <code>	使用分享码建造蓝图
/blueprint share	上传并分享最近的蓝图
/blueprint pause	暂停当前建造
/blueprint resume	恢复建造
/blueprint cancel	取消建造
/blueprint speed <slow|normal|fast>	调整建造速度

别名：/bp