building-maps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Maps in Roblox

在 Roblox 中构建地图

This skill provides procedural knowledge for generating reliable, coherent large-scale environments 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 中生成可靠、连贯的大规模环境的流程化知识。

权限说明：本 SKILL.md 文件的优先级高于

docs/

文件夹中的所有说明。

MCP Limitations & Workarounds (CRITICAL)

MCP 限制与解决方案（重要）

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 map at the start of every
```
run_code
```
call using
```
workspace:FindFirstChild("MapRoot")
```
.

lua

-- MUST BE AT THE START OF EVERY RUN_CODE CALL
local mapRoot = workspace:FindFirstChild("CityMap")
if not mapRoot then
    mapRoot = Instance.new("Folder")
    mapRoot.Name = "CityMap"
    mapRoot.Parent = workspace
end

mcp__roblox__run_code

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

状态丢失：在一次调用中声明的变量在下一次调用中不存在。
引用丢失：对象引用会在两次调用之间丢失。
解决方案：你必须在每次
```
run_code
```
调用的开头，使用
```
workspace:FindFirstChild("MapRoot")
```
重新获取正在构建的地图的引用。

lua

-- MUST BE AT THE START OF EVERY RUN_CODE CALL
local mapRoot = workspace:FindFirstChild("CityMap")
if not mapRoot then
    mapRoot = Instance.new("Folder")
    mapRoot.Name = "CityMap"
    mapRoot.Parent = workspace
end

Anti-Patterns (What to AVOID)

反模式（需要避免的做法）

Do Not Guess (Ground Truth Rule): Map building spans many chunks. If you lose track of where a zone or landmark is, DO NOT GUESS. Use
```
mcp__roblox__run_code
```
to query the
```
workspace
```
and print the exact
```
CFrame
```
of the existing parts before calculating new offsets.
Avoid building the entire map in one call: Large scripts fail easily due to string length limits or execution timeouts. Split the build by phase and zone.
Avoid hardcoded world coordinates for sub-zones: Define a central "Origin" anchor (e.g., a 1x1 invisible part at 0,0,0). All zone offsets MUST be relative to this
```
Origin.CFrame
```
.
Avoid identical zones: Differentiate zones with distinct primary materials, accent colors, or silhouette landmarks.
Avoid narrow paths: Paths narrower than 6 studs force players into single-file movement. Main roads should be 10+ studs wide.
Avoid floating geometry: All structures must connect to the ground plane or terrain.

不要猜测（事实依据规则）：地图构建涉及大量区块。如果你忘记了某个区域或地标的位置，绝对不要猜测。在计算新的偏移量之前，使用
```
mcp__roblox__run_code
```
查询
```
workspace
```
并打印现有部件的精确
```
CFrame
```
。
避免在一次调用中构建完整地图：大型脚本很容易因字符串长度限制或执行超时而失败。请按阶段和区域拆分构建任务。
避免为子区域硬编码世界坐标：定义一个中心
```
Origin
```
锚点（例如位于 0,0,0 的 1x1 不可见部件）。所有区域偏移量必须相对于此
```
Origin.CFrame
```
。
避免区域同质化：通过不同的主材质、强调色或轮廓地标来区分各个区域。
避免狭窄路径：宽度小于 6 studs 的路径会迫使玩家单列移动。主路宽度应达到 10 studs 以上。
避免悬空几何体：所有结构都必须连接到地平面或地形。

Build Process (6 Phases)

构建流程（6 个阶段）

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

不要尝试在单次运行中构建复杂地图，请按顺序遵循以下阶段。

Phase 1: Layout Planning (Before Coding)

阶段 1：布局规划（编码前）

When receiving a request to build a map, you MUST strictly follow this evaluation process before writing any code. Words like "spacious(広い)", "western(洋風)", or "cool(かっこいい)" are VAGUE MODIFIERS, not structural requirements.

Step 1: Force Thinking and Checklist Evaluation Before calling

mcp__roblox__run_code

, you MUST output a

<thinking>

block to evaluate the user's prompt against this Mandatory Checklist:

[Scale/Scope] Is the total size defined? (e.g., a 100x100 small arena vs a 2000x2000 city).
[Gameplay Type] Is the structural topology defined? (e.g., a flat social lobby vs a vertical parkour obby).
[Zone Breakdown] Are the specific areas/zones listed? (e.g., "a town" is invalid. "a town with a spawn plaza, 3 houses, and a shop" is valid).

Step 2: Choose Execution Path Inside your

<thinking>

block, answer Yes or No for each item.

CRITICAL RULE: If ANY item is "No" or "Ambiguous", you MUST STOP. Do NOT proceed to build. Do NOT "reasonably assume" anything. You are FORBIDDEN from guessing the structure.

Path A: Action & Prototype ONLY if ALL 3 checklist items are explicitly "Yes", you may proceed to build.
Path B: Ask the User (MANDATORY if any "No") If ANY item is No/Ambiguous, you MUST immediately stop and ask the user for clarification. Do NOT write any code. Do NOT read docs. STOP and ASK THE USER. Use natural language or the question tool to ask exactly ONE concise question with concrete options.

收到构建地图的请求后，你必须在编写任何代码之前严格遵循此评估流程。诸如“spacious(広い)”、“western(洋風)”或“cool(かっこいい)”之类的词汇是模糊修饰词，而非结构性要求。

步骤 1：强制思考与清单评估 在调用

mcp__roblox__run_code

之前，你必须输出一个

<thinking>

块，对照此强制清单评估用户的提示：

[规模/范围] 是否定义了总大小？（例如 100x100 的小型竞技场 vs 2000x2000 的城市）。
[玩法类型] 是否定义了结构拓扑？（例如平坦的社交大厅 vs 垂直跑酷 obby）。
[区域拆分] 是否列出了具体的区域/地带？（例如“一个城镇”是无效的，“带有出生广场、3 栋房屋和 1 家商店的城镇”才是有效的）。

步骤 2：选择执行路径 在你的

<thinking>

块中，为每个项目回答“是”或“否”。

重要规则：如果有任何一项为“否”或“不明确”，你必须停止。不要继续构建，不要做任何“合理假设”，严禁猜测结构。

路径 A：执行与原型构建 仅当清单的所有 3 项都明确为“是”时，你才可以继续构建。
路径 B：询问用户（如有任何“否”则必须执行） 如果有任何一项为“否/不明确”，你必须立即停止并向用户请求澄清。不要编写任何代码，不要查阅文档，立刻停止并询问用户。使用自然语言或提问工具，仅提出一个简洁的、带有具体选项的问题。

Phase 2: Ground & Boundaries

阶段 2：地面与边界

Generate the main floor plane(s) and boundary walls. Create the

Origin

anchor part and the

MapRoot

folder hierarchy. Keep parts per call target: 10–20.

生成主地平面和边界墙。创建

Origin

锚点部件和

MapRoot

文件夹层级结构。每次调用的部件数量目标：10–20 个。

Phase 3: Zone Shells

阶段 3：区域框架

Generate the specific floor sections, major walls, and dividers for each zone. Calculate offsets relative to the

Origin

. Parts per call target: 20–40.

为每个区域生成具体的地面区块、主墙体和分隔物。相对于

Origin

计算偏移量。每次调用的部件数量目标：20–40 个。

Phase 4: Landmarks

阶段 4：地标

Build towers, fountains, prominent trees, or key structures. These orient the player. Parts per call target: 20–30 per landmark.

Read
../building-3d-objects/docs/spatial-patterns.md
if building complex geometric landmarks.

建造塔楼、喷泉、显眼的树木或关键结构，这些可以帮助玩家辨别方向。每个地标的部件数量目标：20–30 个。

如果要构建复杂的几何地标，请阅读
../building-3d-objects/docs/spatial-patterns.md
。

Phase 5: Zone Fill

阶段 5：区域填充

Populate zones with props, furniture, and vegetation. Parts per call target: 20–30 per zone.

用道具、家具和植被填充区域。每个区域的部件数量目标：20–30 个。

Phase 6: Environment, Lighting & Spawns

阶段 6：环境、光照与出生点

Configure the map's environment and place spawn points. This includes both global settings and local light sources. Parts per call target: 5–20.

Do not limit yourself to instance-level lights. Also consider:

```
Lighting
```
service properties (ClockTime/TimeOfDay, Ambient, Brightness)
```
Atmosphere
```
(Density, Offset, Color, Decay, Glare, Haze)
```
SpawnLocation
```
on solid ground

配置地图环境并放置出生点。这包括全局设置和局部光源。每次调用的部件数量目标：5–20 个。

不要局限于实例级别的光源。 还可以考虑：

```
Lighting
```
服务属性（ClockTime/TimeOfDay、Ambient、Brightness）
```
Atmosphere
```
（Density、Offset、Color、Decay、Glare、Haze）
放置在坚实地面上的
```
SpawnLocation
```

Folder Organization

文件夹组织

Always organize into a hierarchy. Never dump parts flat in the workspace.

workspace/
  MapName/                  ← MapRoot (Folder)
    Origin                  ← invisible anchor part (0,0,0)
    Terrain/                ← ground planes, terrain features
    Zone_A/                 ← named zone (Folder)
      Floor
      Walls/
      Props/
    Zone_B/
    Landmarks/              ← major visual anchors
    Lighting/               ← ambient sources
    Spawns/                 ← SpawnLocation instances

始终按层级结构组织，永远不要将部件直接平铺在 workspace 中。

workspace/
  MapName/                  ← MapRoot (Folder)
    Origin                  ← invisible anchor part (0,0,0)
    Terrain/                ← ground planes, terrain features
    Zone_A/                 ← named zone (Folder)
      Floor
      Walls/
      Props/
    Zone_B/
    Landmarks/              ← major visual anchors
    Lighting/               ← ambient sources
    Spawns/                 ← SpawnLocation instances

Post-Build Verification

构建后验证

After the build is visually complete, run a validation script via

mcp__roblox__run_code

. Adapt the

MAP_ROOT_NAME

variable to your map's folder name.

lua

local MAP_ROOT_NAME = "YourMapName" -- AI: Update this
local root = workspace:FindFirstChild(MAP_ROOT_NAME)
if not root then print("[ERROR] " .. MAP_ROOT_NAME .. " not found"); return end

local errors, warnings, partCount = 0, 0, 0
for _, desc in ipairs(root:GetDescendants()) do
    if desc:IsA("BasePart") then
        partCount = partCount + 1
        if not desc.Anchored then
            print("[ERROR] " .. desc:GetFullName() .. " not Anchored")
            errors = errors + 1
        end
        if desc.Position.Y - desc.Size.Y/2 < -0.5 then
            print("[WARN] " .. desc.Name .. " below floor Y=" .. string.format("%.1f", desc.Position.Y - desc.Size.Y/2))
            warnings = warnings + 1
        end
        if desc.Color == Color3.new(163/255,162/255,165/255) and desc.Material == Enum.Material.Plastic then
            print("[WARN] " .. desc.Name .. " uses default color")
            warnings = warnings + 1
        end
    end
end
print(string.format("Parts: %d | Errors: %d | Warnings: %d", partCount, errors, warnings))

Regression loop: If the script outputs

[ERROR]

[WARN]

, fix the issues and re-verify.

Additionally, check these structural properties:

Traversal: Is every zone reachable from spawn?
Scale Check: Does the environment feel right relative to player size (~5 studs)?
Hierarchy: Are all parts parented inside the
```
MapRoot
```
folder hierarchy?
Anchoring: Confirmed by the script above.

构建在视觉上完成后，通过

mcp__roblox__run_code

运行验证脚本。将

MAP_ROOT_NAME

变量修改为你的地图文件夹名称。

lua

local MAP_ROOT_NAME = "YourMapName" -- AI: Update this
local root = workspace:FindFirstChild(MAP_ROOT_NAME)
if not root then print("[ERROR] " .. MAP_ROOT_NAME .. " not found"); return end

local errors, warnings, partCount = 0, 0, 0
for _, desc in ipairs(root:GetDescendants()) do
    if desc:IsA("BasePart") then
        partCount = partCount + 1
        if not desc.Anchored then
            print("[ERROR] " .. desc:GetFullName() .. " not Anchored")
            errors = errors + 1
        end
        if desc.Position.Y - desc.Size.Y/2 < -0.5 then
            print("[WARN] " .. desc.Name .. " below floor Y=" .. string.format("%.1f", desc.Position.Y - desc.Size.Y/2))
            warnings = warnings + 1
        end
        if desc.Color == Color3.new(163/255,162/255,165/255) and desc.Material == Enum.Material.Plastic then
            print("[WARN] " .. desc.Name .. " uses default color")
            warnings = warnings + 1
        end
    end
end
print(string.format("Parts: %d | Errors: %d | Warnings: %d", partCount, errors, warnings))

回归循环：如果脚本输出

[ERROR]

或

[WARN]

，修复问题后重新验证。

此外，检查以下结构属性：

可通行性：从出生点是否可以到达每个区域？
比例检查：相对于玩家大小（约 5 studs），环境的比例是否合理？
层级结构：所有部件是否都归属于
```
MapRoot
```
文件夹层级内？
锚定状态：已通过上述脚本确认。