mcpField
B
building-3d-objects

building-3d-objects

github.com/ohzw创意与媒体25318 次安装34 周前更新
代码仓库

关于 building-3d-objects

此技能为在 Roblox Studio 中生成 3D 物体提供分阶段的程序化指导，面向使用 Roblox 工具创建模型的 Agent。内容涵盖坐标规划、几何与 CSG 操作，以及构建后的验证。

主要功能

  1. 01构建前检查组件与尺度
  2. 02按父级坐标规划位置
  3. 03几何与 CSG 构建规则
  4. 04多部件网格对齐
  5. 05运行验证脚本并修复问题

适用场景

  1. 01创建由多个部件组成的物体
  2. 02构建含曲面或空腔的几何体
  3. 03检查模型结构并处理错误

MCP 相关

指导 Agent 通过 mcp__roblox__run_code 在 Roblox Studio 中生成和验证物体，并说明每次调用会丢失变量和对象引用。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ohzw/roblox-dev-skills --skill building-3d-objects

安装后在 Claude Code 中输入/building-3d-objects确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

docs/
csg-patterns.md
platform-rules.md
spatial-patterns.md
scripts/
validate.luau

详细介绍

在 Roblox 中构建 3D 对象

此技能提供了使用 mcp__roblox__run_code 工具在 Roblox Studio 中生成可靠、高质量 3D 对象的程序化知识。

权威性：此 SKILL.md 文件优先于 docs/ 文件夹中的任何说明。

MCP 的限制与解决方法（重要）

mcp__roblox__run_code 工具以无状态方式执行 Lua 代码。 每次执行都是全新的环境。

  1. 状态丢失：一次调用中声明的变量在下一次调用中不存在。
  2. 引用丢失：不同调用之间的对象引用会丢失。
  3. 解决方法：每次调用 run_code 时，必须在开头使用 workspace:FindFirstChild("ModelName") 重新获取正在构建的对象的引用。
-- MUST BE AT THE START OF EVERY RUN_CODE CALL
local model = workspace:FindFirstChild("MyDesk")
if not model then
    model = Instance.new("Model")
    model.Name = "MyDesk"
    model.Parent = workspace
end

反面做法（应避免）

  • 不要猜测（以实际数据为准）：如果需要知道上一个代码块中创建的零件的精确坐标、尺寸或方向，不要猜测，也不要依赖聊天记录。始终使用 mcp__roblox__run_code 明确读取（打印）workspace 中当前的 CFrame 和 Size，并以这些实际数据为依据进行后续操作。
  • 避免未锚定的零件：Anchored 默认为 false。除非明确需要进行物理模拟，否则每个零件都应将其设为 true。
  • 避免硬编码世界坐标：所有子组件的位置都必须相对于父零件或模型的 CFrame。模型移动后，硬编码坐标会失效。
  • 避免仅用方块拼出有机形状：如果真实物体带有曲线或凹槽，请使用 CSG（Subtract/Union）、Cylinder 或 Sphere。
  • 避免 CSG 静默失败：SubtractAsync 和 UnionAsync 可能会静默失败。始终使用 pcall 包装，并确认结果是 BasePart。

构建流程（4 个阶段）

请依次遵循以下阶段。不要尝试在一次运行中构建复杂对象。

阶段 1：评估（设计与预算）

收到构建对象的请求时，快速判断是否掌握了足够的结构细节。

快速检查：

  • 是否知道要构建的具体组件／零件？（不能只知道“厨房”，还要知道“台面、水槽、炉灶、中岛”）
  • 是否知道大致的比例？（与玩家一样大？微缩尺寸？房间大小？）
  • 是否知道它是静态的还是包含活动部件？

决策：

  • 如果所有问题的答案都是“是”：进入阶段 2。对颜色和次要细节做出合理假设。
  • 如果有任何一项的答案是“否”：停止。告诉用户：“要正确构建它，我需要更多细节。请允许我为你联系设计顾问，帮助你明确需求。”然后建议使用 roblox-design-consultant 技能收集需求。
阶段 2：规划（坐标系与变量）

明确空间关系。

条件规则：

  • 如果要分多次调用 run_code：必须为尺寸使用命名变量，并添加几何清单头部（参见 docs/spatial-patterns.md）。
  • 如果零件数量超过 5 个：将尺寸对齐到一致的网格（例如 0.1 或 0.5 studs），以避免浮点误差累积。

如果满足上述任一条件，请立即阅读 docs/spatial-patterns.md。

阶段 3：构建（几何体与 CSG）

生成零件。

CSG 规则：

  • 对负体（切割器）的尺寸应用 EPSILON（例如 0.01），以防止 Z-fighting 并确保干净地完成减法。
  • 将基体的完整 CFrame 复制到生成的 CSG 零件上。CFrame.new(pos) 会重置旋转。
  • 重新应用 UsePartColor = true 和原始 Color，因为 CSG 操作可能会将切割器的颜色带到结果中。

如果构建需要曲线、孔洞或中空空间，请立即阅读 docs/csg-patterns.md。

Phase 4：验证（构建后关卡）

视觉上完成构建后，你必须执行验证脚本以确保结构完整性。

  1. 阅读 scripts/validate.luau 的内容。
  2. 调整 TARGET_MODEL_NAME 变量。
  3. 通过 run_code 执行脚本。
  4. 回归循环：如果脚本输出任何 [ERROR] 或 [WARN]，你必须返回 Phase 3，修复代码并重新验证。

补充文档

仅在特定阶段或条件触发时阅读这些文件。

文件阅读时机
docs/spatial-patterns.mdPhase 2：多次调用构建或部件数量 >5
docs/csg-patterns.mdPhase 3：使用 SubtractAsync 或 UnionAsync
docs/platform-rules.md涉及 Roblox 特定行为时（Materials、Lighting、Cylinder 朝向）
scripts/validate.luauPhase 4：强制进行构建后验证

评论

支持 Markdown