building-maps

在 Roblox 中构建地图

此技能提供使用 mcp__roblox__run_code 工具在 Roblox Studio 中生成可靠、连贯的大型环境所需的程序化知识。

权威性：此 SKILL.md 文件优先于 docs/ 文件夹中的任何说明。

MCP 的限制与变通方法（重要）

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

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

-- 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 查询 workspace，并在计算新的偏移量前打印现有部件的准确 CFrame。
• 避免在一次调用中构建整张地图：大型脚本很容易因字符串长度限制或执行超时而失败。按阶段和区域拆分构建。
• 避免对子区域使用硬编码的世界坐标：定义一个中央“Origin”锚点（例如，在 0,0,0 处放置一个 1x1 的不可见部件）。所有区域偏移量都必须相对于此 Origin.CFrame。
• 避免区域雷同：通过不同的主要材质、点缀色或轮廓地标来区分各个区域。
• 避免道路狭窄：宽度小于 6 studs 的道路会迫使玩家排成单列通行。主路宽度应达到 10 studs 或以上。
• 避免几何体悬空：所有结构都必须与地平面或地形相连。

构建流程（6 个阶段）

不要尝试在一次运行中构建复杂地图。请依次遵循以下阶段。

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

收到构建地图的请求时，编写任何代码前都必须严格遵循此评估流程。“宽敞（広い）”“西式（洋風）”或“酷（かっこいい）”等词是模糊修饰语，不是结构要求。

步骤 1：强制思考与清单评估 调用 mcp__roblox__run_code 前，必须输出一个 <thinking> 块，根据以下必选清单评估用户的提示词：

1. [规模/范围] 是否明确了总尺寸？（例如，100x100 的小型竞技场，还是 2000x2000 的城市）。
2. [玩法类型] 是否明确了结构拓扑？（例如，平坦的社交大厅，还是垂直跑酷障碍赛）。
3. [区域划分] 是否列出了具体区域？（例如，“一座城镇”不合要求；“一座包含出生广场、3 栋房屋和一家商店的城镇”则符合要求）。

步骤 2：选择执行路径 在 <thinking> 块中，对每项回答“是”或“否”。

重要规则：如果任意一项为“否”或“含糊不清”，就必须停止。不得继续构建。不得“合理推断”任何内容。严禁猜测结构。

• 路径 A：执行与原型 只有在清单中的 3 项全部明确为“是”时，才可以继续构建。
• 路径 B：询问用户（任何一项为“否”时必须执行） 如果任意一项为“否”或“含糊不清”，必须立即停止并向用户询问澄清信息。不得编写代码。不得阅读文档。停止并询问用户。 使用自然语言或 question 工具，只提出一个简洁且包含具体选项的问题。

阶段 2：地面与边界

生成主地面平面和边界墙。创建 Origin 锚点部件和 MapRoot 文件夹层级。每次调用的部件数量目标：10–20。

阶段 3：区域外壳

为每个区域生成指定的地面部分、主要墙体和隔断。相对于 Origin 计算偏移量。每次调用的部件数量目标：20–40。

阶段 4：地标

建造塔楼、喷泉、显眼的树木或关键建筑。这些能帮助玩家辨识方位。每次调用的部件数目标：每个地标 20–30 个。

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

阶段 5：区域填充

在各区域中布置道具、家具和植被。每次调用的部件数目标：每个区域 20–30 个。

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

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

不要只使用实例级光源。 还应考虑：

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

文件夹组织

始终按层级组织。切勿将部件平铺在工作区中。

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

构建后验证

地图在视觉上构建完成后，通过 mcp__roblox__run_code 运行验证脚本。根据地图的文件夹名称调整 MAP_ROOT_NAME 变量。

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]，请修复问题并重新验证。

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

1. 可通行性：每个区域都能从出生点到达吗？
2. 比例检查：相对于玩家身高（约 5 studs），环境比例是否合适？
3. 层级结构：所有部件都已放入 MapRoot 文件夹层级中吗？
4. 锚定：已由上述脚本确认。