building-3d-objects
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBuilding 3D Objects in Roblox
在Roblox中构建3D物体
This skill provides procedural knowledge for generating reliable, high-quality 3D objects in Roblox Studio using the tool.
mcp__roblox__run_codeAUTHORITY: This SKILL.md file takes precedence over any instructions found in the folder.
docs/本技能提供了使用工具在Roblox Studio中生成可靠、高质量3D物体的流程化知识。
mcp__roblox__run_code优先级说明:本SKILL.md文件的优先级高于目录下的所有指令。
docs/MCP Limitations & Workarounds (CRITICAL)
MCP的限制与变通方案(关键)
The tool executes Lua code statelessly.
Every execution is a blank slate.
mcp__roblox__run_code- State Loss: Variables declared in one call do NOT exist in the next.
- Reference Loss: Object references are lost between calls.
- The Fix: You MUST re-acquire references to your in-progress build at the start of every call using
run_code.workspace:FindFirstChild("ModelName")
lua
-- 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
endmcp__roblox__run_code- 状态丢失:单次调用中声明的变量在后续调用中不存在。
- 引用丢失:对象引用会在调用之间丢失。
- 解决方案:你必须在每次调用的开头,使用
run_code重新获取正在构建的对象的引用。workspace:FindFirstChild("ModelName")
lua
-- 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
endAnti-Patterns (What to AVOID)
反模式(应避免的做法)
- Do Not Guess (Ground Truth Rule): If you need the exact coordinates, size, or orientation of a part created in a previous chunk, DO NOT GUESS or rely on your chat history. Always use to explicitly read (print) the current
mcp__roblox__run_codeandCFramefrom theSize, and base your next moves on that ground truth.workspace - Avoid unanchored parts: defaults to
Anchored. Set it tofalsefor every part unless physics simulation is explicitly requested.true - Avoid hardcoded world coordinates: All sub-component positions MUST be relative to a parent part's or model's . Hardcoded coordinates break when the model is moved.
CFrame - Avoid block-only compositions for organic shapes: If the real object has curves or recesses, use CSG (Subtract/Union), Cylinders, or Spheres.
- Avoid silent CSG failures: and
SubtractAsynccan fail silently. Always wrap inUnionAsyncand verify the result is apcall.BasePart
- 请勿猜测(真实数据原则):如果你需要之前代码块创建的Part的精确坐标、尺寸或方向,绝对不要猜测或依赖聊天历史记录。始终使用从
mcp__roblox__run_code中显式读取(打印)当前的workspace和CFrame,并基于该真实数据进行后续操作。Size - 避免未锚定的Part:属性默认为
Anchored。除非明确要求物理模拟,否则所有Part都应设置为false。true - 避免硬编码世界坐标:所有子组件的位置必须相对于父Part或Model的。硬编码坐标会在Model被移动时失效。
CFrame - 避免有机形状仅用方块组合:如果真实物体有曲线或凹槽,请使用CSG(Subtract/Union)、圆柱体或球体。
- 避免CSG静默失败:和
SubtractAsync可能会静默失败。请始终用UnionAsync包裹调用,并验证结果是否为pcall类型。BasePart
Build Process (4 Phases)
构建流程(4个阶段)
Follow these phases sequentially. Do not attempt to build a complex object in a single run.
请按顺序遵循这些阶段,不要尝试在单次运行中构建复杂对象。
Phase 1: Assess (Design & Budget)
阶段1:评估(设计与预算)
When receiving a request to build an object, quickly evaluate if you have enough structural detail.
Quick Check:
- Do you know the specific components/parts to build? (Not just "kitchen" but "counter, sink, stove, island")
- Do you know the approximate scale? (Player-sized? Miniature? Room-scale?)
- Do you know if it's static or has moving parts?
Decision:
- If YES to all: Proceed to Phase 2. Make reasonable assumptions for colors and minor details.
- If NO to any: STOP. Tell the user: "I need more details to build this properly. Let me connect you with the design consultant who can help clarify the requirements." Then suggest using the skill for requirement gathering.
roblox-design-consultant
收到构建对象的请求时,快速评估你是否掌握了足够的结构细节。
快速检查项:
- 你是否清楚要构建的具体组件/Part?(不是笼统的「厨房」,而是「台面、水槽、炉灶、中岛」)
- 你是否知道大致的尺寸比例?(玩家大小?迷你尺寸?房间规模?)
- 你是否知道它是静态的还是有可动部件?
决策:
- 全部满足:进入阶段2。颜色和次要细节可做合理假设。
- 任意一项不满足:停止。告知用户:「我需要更多细节才能正确构建这个对象。让我为你对接可以帮助明确需求的设计顾问。」然后建议使用技能进行需求收集。
roblox-design-consultant
Phase 2: Plan (Coordinate System & Variables)
阶段2:规划(坐标系与变量)
Establish the spatial relationships.
Conditional Rules:
- If splitting across multiple calls: You MUST use named variables for dimensions and a geometric manifest header (see
run_code).docs/spatial-patterns.md - If part count > 5: Snap dimensions to a consistent grid (e.g., 0.1 or 0.5 studs) to avoid floating-point drift.
Read now if either condition applies.
docs/spatial-patterns.md建立空间关系。
条件规则:
- 如果需要拆分到多次调用中:必须使用命名变量存储尺寸,并添加几何清单头(参见
run_code)。docs/spatial-patterns.md - 如果Part数量 > 5:将尺寸对齐到统一的网格(例如0.1或0.5格),以避免浮点漂移。
如果满足以上任一条件,请立即阅读。
docs/spatial-patterns.mdPhase 3: Build (Geometry & CSG)
阶段3:构建(几何形状与CSG)
Generate the parts.
CSG Rules:
- Apply an (e.g., 0.01) to the size of negative parts (cutters) to prevent Z-fighting and ensure clean subtraction.
EPSILON - Copy the full from the base part to the resulting CSG part.
CFrameresets rotation.CFrame.new(pos) - Re-apply and the original
UsePartColor = trueto the result, as CSG operations can bleed colors from the cutter.Color
Read now if your build requires curves, holes, or hollow spaces.
docs/csg-patterns.md生成各个Part。
CSG规则:
- 对负向Part(切割体)的尺寸应用(例如0.01),以防止Z-fighting并确保减法运算干净利落。
EPSILON - 将基础Part的完整复制给生成的CSG Part。
CFrame会重置旋转。CFrame.new(pos) - 为结果重新设置和原始
UsePartColor = true,因为CSG运算可能会混入切割体的颜色。Color
如果你的构建需要曲线、孔洞或中空结构,请立即阅读。
docs/csg-patterns.mdPhase 4: Verify (Post-Build Gate)
阶段4:验证(构建后校验关卡)
After the build is visually complete, you MUST execute the validation script to ensure structural integrity.
- Read the contents of .
scripts/validate.luau - Adapt the variable.
TARGET_MODEL_NAME - Execute the script via .
run_code - 回帰ループ: If the script outputs any or
[ERROR], you MUST return to Phase 3, fix the code, and re-verify.[WARN]
构建在视觉上完成后,你必须执行验证脚本以确保结构完整性。
- 读取的内容。
scripts/validate.luau - 修改变量以适配目标。
TARGET_MODEL_NAME - 通过执行脚本。
run_code - 回归循环:如果脚本输出任何或
[ERROR],你必须返回阶段3,修复代码后重新验证。[WARN]
Supplementary Documentation
补充文档
Read these files only when the specific phase or condition triggers them.
| File | When to Read |
|---|---|
| Phase 2: Multi-call builds or >5 parts |
| Phase 3: Using SubtractAsync or UnionAsync |
| When dealing with Roblox-specific behaviors (Materials, Lighting, Cylinder orientation) |
| Phase 4: Mandatory post-build verification |
仅当特定阶段或条件触发时才阅读这些文件。
| 文件 | 阅读时机 |
|---|---|
| 阶段2:多次调用构建或Part数量>5 |
| 阶段3:使用SubtractAsync或UnionAsync时 |
| 处理Roblox特定行为时(材质、光照、圆柱体方向) |
| 阶段4:强制的构建后验证 |