building-3d-objects

Building 3D Objects in Roblox

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 Limitations & Workarounds (CRITICAL)

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").

-- 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.

Build Process (4 Phases)

Follow these phases sequentially. Do not attempt to build a complex object in a single run.

Phase 1: Assess (Design & Budget)

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.

Phase 2: Plan (Coordinate System & Variables)

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.

Phase 3: Build (Geometry & 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.

Phase 4: Verify (Post-Build Gate)

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.

Supplementary Documentation

Read these files only when the specific phase or condition triggers them.

File	When 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