roblox-studio

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Roblox Studio

Roblox Studio

Use the
roblox-studio
MCP tools to work against the place currently open in Studio. Keep new work under
Workspace/MapDrafts
.
使用
roblox-studio
MCP 工具操作当前在 Studio 中打开的 place。所有新工作都应放在
Workspace/MapDrafts
下。

Preflight

预检

  1. Confirm the MCP tools are available. If they are missing or
    studio_ping
    reports offline, read setup.md.
  2. Run
    studio_ping
    before every work session.
  3. Inspect the relevant hierarchy with
    studio_get_tree
    ; use
    studio_find_instances
    and
    studio_get_properties
    for targeted reads.
  4. State the place and target root before changing anything. Never imply that Studio changed when the bridge is offline.
  1. 确认 MCP 工具可用。如果工具缺失或
    studio_ping
    报告离线,请阅读 setup.md。
  2. 每个工作会话开始前运行
    studio_ping
    。
  3. 使用
    studio_get_tree
    检查相关层级结构;使用
    studio_find_instances
    和
    studio_get_properties
    进行定向读取。
  4. 进行任何更改前,说明当前 place 和目标根节点。bridge 离线时,绝不能暗示 Studio 已发生更改。

Choose a Workflow

选择工作流

  • New map or major rebuild: read scene-spec.md, draft one SceneSpec, then use
    map_apply_scene_spec
    .
  • Fast graybox: use
    map_create_blockout
    , then validate the route before visual refinement.
  • Existing generated map repair: inspect first and batch related edits with
    studio_patch_instances
    .
  • Before a substantial repair, use
    studio_export_model
    to keep a private local model backup.
  • Focused property edit: use
    studio_set_properties
    ; use
    studio_create_instance
    only inside a managed root.
  • Terrain-only task: use
    terrain_generate
    with an explicit bounded size.
  • Luau plus Rojo output: set
    codegen.target
    to
    both
    and review every script before apply.
  • Tool choice or argument uncertainty: read tools.md.
  • 新建地图或重大重建:阅读 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。

Build Loop

构建循环

  1. Translate the request into named areas, player route, scale, style, interactions, and acceptance checks.
  2. Preserve existing content unless the user explicitly asked to replace or edit it.
  3. For a SceneSpec, run
    map_apply_scene_spec
    with
    dryRun=true
    .
  4. Review target root, object count, services touched, filesystem writes, scripts, terrain, and reported risks.
  5. Apply with
    dryRun=false
    when the user requested the build or explicitly approved the dry run.
  6. Run
    map_validate
    on the exact returned map root with
    strictGeometry=true
    .
  7. Run
    map_readiness_check
    for playable maps; use
    profile="house"
    only for its named house contract.
  8. Inspect from useful angles with
    studio_focus_instance
    ,
    studio_set_camera
    , and
    studio_visual_probe
    .
  9. When behavior matters, review a managed test ModuleScript returning
    function(args)
    . Raise an error on failure and return a JSON-serializable value on success. Call
    studio_run_test
    with
    confirmToken="RUN_STUDIO_TEST"
    , optional
    mode
    (
    run
    or
    play
    ), and
    timeoutSeconds
    (integer 1-120, default 30). Tests execute ordinary project code, not a sandbox. Use a working copy and disable or mock persistent/external writes.
  10. Repair concrete failures and repeat validation. Prefer a scoped patch over rebuilding a sound map.
  1. 将请求转化为命名区域、玩家路线、尺度、风格、交互和验收检查。
  2. 除非用户明确要求替换或编辑现有内容,否则应保留现有内容。
  3. 对于 SceneSpec,运行
    map_apply_scene_spec
    ,并设置
    dryRun=true
    。
  4. 审查目标根节点、对象数量、涉及的服务、文件系统写入、脚本、地形和报告的风险。
  5. 当用户请求构建或明确批准 dry run 后,使用
    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. 当行为逻辑重要时,审查一个受管理的测试 ModuleScript,其返回值为
    function(args)
    。失败时抛出错误,成功时返回可进行 JSON 序列化的值。调用
    studio_run_test
    时,设置
    confirmToken="RUN_STUDIO_TEST"
    ,并根据需要设置
    mode
    (
    run
    或
    play
    )和
    timeoutSeconds
    (整数 1-120,默认 30)。测试执行常规项目代码,而不是在沙箱中执行。使用工作副本,并禁用或模拟持久化写入和外部写入。
  10. 修复具体失败项并重复验证。优先采用限定范围的补丁,而不是重建一个本身正常的地图。

Quality Bar

质量标准

  • Include a SpawnLocation, readable route, safe landings, and an obvious destination for playable maps.
  • Use unique, semantic names and models/folders for levels, buildings, routes, and systems.
  • Ground normal maps with
    layout.grounding.mode="raycast"
    ; use
    manual
    for a known elevation and
    none
    only for intentional sky or void maps.
  • Put doors, buttons, elevators, teleporters, and checkpoints in
    functionalObjects
    . Bind a behavior to existing visible geometry with
    target
    when possible.
  • Treat validation warnings about terrain intersections, blocked doors, stair headroom, unreachable landings, or solid overlaps as repair work.
  • Do not call a map visually ready from object counts or
    map_validate
    alone.
  • Use
    studio_capture_viewport
    for real viewport evidence after native permission is granted. Never substitute a desktop capture, invent a frame, or trigger permission dialogs during a background-only task. Review in-world text before sharing an image.
  • 可游玩地图应包含 SpawnLocation、清晰可辨的路线、安全落点和明确的目的地。
  • 为关卡、建筑、路线和系统使用唯一且具有语义含义的名称,以及 models/folders。
  • 普通地图应使用
    layout.grounding.mode="raycast"
    进行落地设置;已知高度使用
    manual
    ,仅对刻意的天空或虚空地图使用
    none
    。
  • 将门、按钮、电梯、传送点和检查点放入
    functionalObjects
    。尽可能使用
    target
    将行为绑定到现有的可见几何体。
  • 将有关地形相交、门被阻挡、楼梯净空不足、落点不可达或实体重叠的验证警告视为需要修复的问题。
  • 不能仅凭对象数量或
    map_validate
    就认定地图在视觉上已准备就绪。
  • 获得原生权限后,使用
    studio_capture_viewport
    获取真实的视口证据。绝不能使用桌面截图、虚构画面,或在仅后台运行的任务中触发权限对话框。分享图片前应检查场景内的文字。

Guardrails

防护规则

  • Never request Roblox credentials, cookies, or
    .ROBLOSECURITY
    .
  • Never send the bridge token anywhere except the local Studio plugin.
  • Never use external asset IDs without a user-supplied allowlist.
  • Keep direct edits and deletes inside managed roots. Deletes require the configured confirm token and explicit user intent.
  • Do not enable
    studio_execute_luau
    to bypass declarative tools. If it is genuinely required, explain the exact code and risk first.
  • Avoid remote code, HTTP,
    require(assetId)
    ,
    loadstring
    , and hidden loaders in generated Luau.
  • 绝不请求 Roblox 凭据、cookies 或
    .ROBLOSECURITY
    。
  • 除本地 Studio 插件外,绝不能将 bridge token 发送到任何位置。
  • 未经用户提供允许列表,绝不能使用外部 asset ID。
  • 将直接编辑和删除操作限制在受管理的根节点内。删除操作必须使用已配置的确认 token,并获得用户的明确意图。
  • 不得启用
    studio_execute_luau
    来绕过声明式工具。如果确实需要使用,应事先说明具体代码和相关风险。
  • 避免在生成的 Luau 中使用远程代码、HTTP、
    require(assetId)
    、
    loadstring
    和隐藏加载器。

Handoff

交付说明

Report the exact map root, manifest path, Rojo files, validation/readiness result, playtest result, warnings left, and the next manual Studio check. Separate verified results from visual judgment.
报告准确的地图根节点、manifest 路径、Rojo 文件、验证和就绪状态检查结果、试玩测试结果、遗留警告以及下一项需要手动在 Studio 中完成的检查。应将已验证的结果与视觉判断分开报告。