roblox-studio

Roblox Studio

使用 roblox-studio MCP 工具，对 Studio 中当前打开的场景进行操作。将新内容放在 Workspace/MapDrafts 下。

预检

1. 确认 MCP 工具可用。如果缺少这些工具，或 studio_ping 报告离线，请阅读 setup.md。
2. 每次工作会话前运行 studio_ping。
3. 使用 studio_get_tree 检查相关层级；使用 studio_find_instances 和 studio_get_properties 定向读取。
4. 修改任何内容前，说明场景和目标根节点。桥接离线时，绝不暗示 Studio 已发生更改。

选择工作流

• 新地图或大规模重建：阅读 scene-spec.md，拟定一个 SceneSpec，然后使用 map_apply_scene_spec。
• 快速灰盒搭建：使用 map_create_blockout，然后在进行视觉细化前验证路线。
• 修复现有的生成地图：先检查，再使用 studio_patch_instances 批量处理相关编辑。
• 进行大规模修复前，使用 studio_export_model 保存一份私有的本地模型备份。
• 针对特定属性进行编辑：使用 studio_set_properties；仅在受管理的根节点内使用 studio_create_instance。
• 仅涉及地形的任务：使用 terrain_generate，并明确指定有界尺寸。
• 输出 Luau 和 Rojo：将 codegen.target 设为 both，并在应用前审查每个脚本。
• 不确定工具选择或参数：阅读 tools.md。

构建循环

1. 将请求转换为具名区域、玩家路线、比例、风格、交互和验收检查项。
2. 保留现有内容，除非用户明确要求替换或编辑。
3. 对 SceneSpec，使用 dryRun=true 运行 map_apply_scene_spec。
4. 检查目标根节点、对象数量、涉及的服务、文件系统写入、脚本、地形和报告的风险。
5. 用户要求构建或明确批准试运行后，使用 dryRun=false 应用。
6. 对返回的确切地图根节点运行 map_validate，并设置 strictGeometry=true。
7. 对可游玩地图运行 map_readiness_check；仅当使用其指定的 house 合约时才设置 profile="house"。
8. 使用 studio_focus_instance、studio_set_camera 和 studio_visual_probe 从有用的角度进行检查。
9. 当行为很重要时，审查返回 function(args) 的受管理测试 ModuleScript。失败时抛出错误，成功时返回可序列化为 JSON 的值。调用 studio_run_test 时设置 confirmToken="RUN_STUDIO_TEST"，可选参数 mode（run 或 play）和 timeoutSeconds（整数，范围为 1-120，默认 30）。测试会执行普通项目代码，并非沙盒环境。使用工作副本，并禁用或模拟持久化/外部写入。
10. 修复具体故障并重复验证。优先采用范围明确的补丁，而不是重建状况良好的地图。

质量标准

• 可游玩地图应包含 SpawnLocation、清晰易读的路线、安全的着陆点和明确的目的地。
• 为关卡、建筑、路线和系统使用独特且语义明确的名称及模型/文件夹。
• 普通地图使用 layout.grounding.mode="raycast" 贴合地面；已知海拔时使用 manual；仅有意设计为空中或虚空地图时才使用 none。
• 将门、按钮、电梯、传送器和检查点放入 functionalObjects。尽可能使用 target，将行为绑定到现有的可见几何体。
• 将有关地形相交、门被阻挡、楼梯净空不足、着陆点无法到达或实体重叠的验证警告视为待修复问题。
• 不要仅凭对象数量或 map_validate 就判定地图已达到视觉就绪状态。
• 获得原生权限后，使用 studio_capture_viewport 获取真实视口证据。仅限后台运行的任务中，绝不可用桌面截图代替、虚构画面或触发权限对话框。分享图片前，先检查游戏内文字。

防护措施

• 绝不索取 Roblox 凭据、Cookie 或 .ROBLOSECURITY。
• 除本地 Studio 插件外，绝不将桥接令牌发送到任何地方。
• 未经用户提供允许列表，绝不使用外部资源 ID。
• 将直接编辑和删除限制在受管理的根目录内。删除操作需要配置的确认令牌和用户明确授权。
• 不要启用 studio_execute_luau 来绕过声明式工具。如果确实需要启用，请先说明具体代码和风险。
• 在生成的 Luau 中避免使用远程代码、HTTP、require(assetId)、loadstring 和隐藏加载器。

交接

报告确切的地图根目录、清单路径、Rojo 文件、验证／就绪结果、试玩结果、遗留警告，以及下一项需要在 Studio 中手动检查的内容。将已验证的结果与视觉判断分开说明。