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.

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

• Read the contents of scripts/validate.luau .

• Adapt the TARGET_MODEL_NAME variable.

• Execute the script via run_code .

• 回帰ループ: 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