building-3d-objects

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Building 3D Objects in Roblox

在Roblox中构建3D物体

This skill provides procedural knowledge for generating reliable, high-quality 3D objects in Roblox Studio using the
mcp__roblox__run_code
tool.
AUTHORITY: This SKILL.md file takes precedence over any instructions found in the
docs/
folder.
本技能提供了使用
mcp__roblox__run_code
工具在Roblox Studio中生成可靠、高质量3D物体的流程化知识。
优先级说明:本SKILL.md文件的优先级高于
docs/
目录下的所有指令。

MCP Limitations & Workarounds (CRITICAL)

MCP的限制与变通方案(关键)

The
mcp__roblox__run_code
tool executes Lua code statelessly. Every execution is a blank slate.
  1. State Loss: Variables declared in one call do NOT exist in the next.
  2. Reference Loss: Object references are lost between calls.
  3. The Fix: You MUST re-acquire references to your in-progress build at the start of every
    run_code
    call using
    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
end
mcp__roblox__run_code
工具以无状态方式执行Lua代码。 每次执行都是全新的空白环境。
  1. 状态丢失:单次调用中声明的变量在后续调用中不存在。
  2. 引用丢失:对象引用会在调用之间丢失。
  3. 解决方案:你必须在每次
    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
end

Anti-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
    mcp__roblox__run_code
    to explicitly read (print) the current
    CFrame
    and
    Size
    from the
    workspace
    , and base your next moves on that ground truth.
  • Avoid unanchored parts:
    Anchored
    defaults to
    false
    . Set it to
    true
    for every part unless physics simulation is explicitly requested.
  • Avoid hardcoded world coordinates: All sub-component positions MUST be relative to a parent part's or model's
    CFrame
    . Hardcoded coordinates break when the model is moved.
  • 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:
    SubtractAsync
    and
    UnionAsync
    can fail silently. Always wrap in
    pcall
    and verify the result is a
    BasePart
    .
  • 请勿猜测(真实数据原则):如果你需要之前代码块创建的Part的精确坐标、尺寸或方向,绝对不要猜测或依赖聊天历史记录。始终使用
    mcp__roblox__run_code
    从
    workspace
    中显式读取(打印)当前的
    CFrame
    和
    Size
    ,并基于该真实数据进行后续操作。
  • 避免未锚定的Part:
    Anchored
    属性默认为
    false
    。除非明确要求物理模拟,否则所有Part都应设置为
    true
    。
  • 避免硬编码世界坐标:所有子组件的位置必须相对于父Part或Model的
    CFrame
    。硬编码坐标会在Model被移动时失效。
  • 避免有机形状仅用方块组合:如果真实物体有曲线或凹槽,请使用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
    roblox-design-consultant
    skill for requirement gathering.
收到构建对象的请求时,快速评估你是否掌握了足够的结构细节。
快速检查项:
  • 你是否清楚要构建的具体组件/Part?(不是笼统的「厨房」,而是「台面、水槽、炉灶、中岛」)
  • 你是否知道大致的尺寸比例?(玩家大小?迷你尺寸?房间规模?)
  • 你是否知道它是静态的还是有可动部件?
决策:
  • 全部满足:进入阶段2。颜色和次要细节可做合理假设。
  • 任意一项不满足:停止。告知用户:「我需要更多细节才能正确构建这个对象。让我为你对接可以帮助明确需求的设计顾问。」然后建议使用
    roblox-design-consultant
    技能进行需求收集。

Phase 2: Plan (Coordinate System & Variables)

阶段2:规划(坐标系与变量)

Establish the spatial relationships.
Conditional Rules:
  • If splitting across multiple
    run_code
    calls
    : You MUST use named variables for dimensions and a geometric manifest header (see
    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
docs/spatial-patterns.md
now if either condition applies.
建立空间关系。
条件规则:
  • 如果需要拆分到多次
    run_code
    调用中
    :必须使用命名变量存储尺寸,并添加几何清单头(参见
    docs/spatial-patterns.md
    )。
  • 如果Part数量 > 5:将尺寸对齐到统一的网格(例如0.1或0.5格),以避免浮点漂移。
如果满足以上任一条件,请立即阅读
docs/spatial-patterns.md
。

Phase 3: Build (Geometry & CSG)

阶段3:构建(几何形状与CSG)

Generate the parts.
CSG Rules:
  • Apply an
    EPSILON
    (e.g., 0.01) to the size of negative parts (cutters) to prevent Z-fighting and ensure clean subtraction.
  • Copy the full
    CFrame
    from the base part to the resulting CSG part.
    CFrame.new(pos)
    resets rotation.
  • Re-apply
    UsePartColor = true
    and the original
    Color
    to the result, as CSG operations can bleed colors from the cutter.
Read
docs/csg-patterns.md
now if your build requires curves, holes, or hollow spaces.
生成各个Part。
CSG规则:
  • 对负向Part(切割体)的尺寸应用
    EPSILON
    (例如0.01),以防止Z-fighting并确保减法运算干净利落。
  • 将基础Part的完整
    CFrame
    复制给生成的CSG Part。
    CFrame.new(pos)
    会重置旋转。
  • 为结果重新设置
    UsePartColor = true
    和原始
    Color
    ,因为CSG运算可能会混入切割体的颜色。
如果你的构建需要曲线、孔洞或中空结构,请立即阅读
docs/csg-patterns.md
。

Phase 4: Verify (Post-Build Gate)

阶段4:验证(构建后校验关卡)

After the build is visually complete, you MUST execute the validation script to ensure structural integrity.
  1. Read the contents of
    scripts/validate.luau
    .
  2. Adapt the
    TARGET_MODEL_NAME
    variable.
  3. Execute the script via
    run_code
    .
  4. 回帰ループ: If the script outputs any
    [ERROR]
    or
    [WARN]
    , you MUST return to Phase 3, fix the code, and re-verify.
构建在视觉上完成后,你必须执行验证脚本以确保结构完整性。
  1. 读取
    scripts/validate.luau
    的内容。
  2. 修改
    TARGET_MODEL_NAME
    变量以适配目标。
  3. 通过
    run_code
    执行脚本。
  4. 回归循环:如果脚本输出任何
    [ERROR]
    或
    [WARN]
    ,你必须返回阶段3,修复代码后重新验证。

Supplementary Documentation

补充文档

Read these files only when the specific phase or condition triggers them.
FileWhen to Read
docs/spatial-patterns.md
Phase 2: Multi-call builds or >5 parts
docs/csg-patterns.md
Phase 3: Using SubtractAsync or UnionAsync
docs/platform-rules.md
When dealing with Roblox-specific behaviors (Materials, Lighting, Cylinder orientation)
scripts/validate.luau
Phase 4: Mandatory post-build verification
仅当特定阶段或条件触发时才阅读这些文件。
文件阅读时机
docs/spatial-patterns.md
阶段2:多次调用构建或Part数量>5
docs/csg-patterns.md
阶段3:使用SubtractAsync或UnionAsync时
docs/platform-rules.md
处理Roblox特定行为时(材质、光照、圆柱体方向)
scripts/validate.luau
阶段4:强制的构建后验证