scenario-roblox-expert

Roblox 专家（技术总监与 Agent 协议）

目标：在 macOS 上使用 Roblox Studio（2026 年 10 月构建版本），通过 scenario-roblox-expert 工具包进行操作。

专业的 Roblox 工作是一种基于证据的循环：设定预算，构建一个阶段，测量、查看、修复，然后推进。没有鼠标的 Agent 可通过 Studio 内置的 MCP 服务、离线检查和文本文件完成这一流程；只有解析后的结果才能作为通过依据，绝不能仅凭单一信号判断。本技能包含这套协议、所有 scenario-roblox-* 技能调用的共享工具包（scripts/）以及团队地图。如果此处提到的同级技能不在你可用的技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具架构继续操作并标记此缺口。

状态（2026-10-18）： 工具包已在 Studio 0.743 中运行，36 项实时测试和 16 项离线测试全部通过（references/procedures.md）。run_headless 仍待实际运行：它需要一台没有交互式 Studio 的机器。

立场（专家差异）

1. 依据解析后的结果判定通过，绝不依据工具文本。 execute_luau 只返回第一个返回值，打印内容会进入 Output 日志（已观察到）。rbx_run.run 会返回 ok、result、error、output，并附上代码块的行号。通过 MCP 对 Agent 创建的任何内容都要“审查结果”（Roblox IAS Q&A，KnFJl6z5UN0 [00:21:23]）。
2. 每个 Agent 使用一个场景，只打开一次，绝不由 Agent 关闭。 绝不要在你没有打开的窗口中运行代码；服务器会在修改用户的游戏前要求你向用户确认。对场景发送 SIGTERM 会导致其窗口卡住，并使服务器无法看到所有 Studio 实例（已观察到）。关闭场景应由编排器负责，并须征得用户同意。
3. 在目标设备上，以预算衡量帧时间。 稳定的帧时间比平均 FPS 更重要（Andrew，XLCZfGEm9tU [00:02:12]）。排查顺序：能否正常运行、真实设备、帧率、Stats，然后是 MicroProfiler（McNeill，rwLEnBtXr30 [00:29:19]）。Studio 的内存数据“不准确”（McNeill，cWDNVvOh4o0 [00:28:25]）：这里一个小型试玩测试就显示了 3,800 MB。
4. 既要查看，也要检查。 每次视觉改动都要从固定摄像机位置截图，使用 image_checks，对比改动前后的 compare 结果，并打开联系表。感受无法自动化（RDC 2026，vumAuOqSmNA [00:29:36]）；AI“不会自动拥有审美”（SmartyRBX，da-wHJpNhBo [00:07:35]）。
5. 小步推进，先红后绿。 每个提示词只处理一个功能（SmartyRBX，0ENeVVC9QT0 [00:10:26]）。在可行的答案后进行安全审查，并测试死亡与重生（SimTek，-0H6JRtrA2Y [00:03:53, 00:06:42]）。先编写 Spec 测试，并观察它失败。
6. 使用文本文件、Git，并在进入 Studio 前设置门禁。 针对类型和 lint 错误的 CI 门禁可捕获“导致游戏故障的问题中 90%”（CJ_Oyer，gapG2tH-etI [00:12:50]）；Git 是安全网（Roblox Learn，v8r1d80DxOY [00:00:45]）。使用 rbx_check（附带 Roblox 定义的 luau-lsp）设置门禁，不要只用原始的 luau-analyze。
7. 了解哪些内容会持久保存。 Edit 模式下的改动会保留在当前打开的会话中，直到有人保存；没有 MCP 工具会执行保存。停止游戏后，Server 模式中的写入会消失（L24，L25）。若没有 $ignoreUnknownInstances，Rojo 重新连接时会删除仅存在于 Studio 中的实例（Distracted Games，Zhl_NAPMztY [00:44:28]）。
8. 如实说明只能通过 GUI 使用的工具。 Animation Editor、terrain brushes、Avatar Setup、Accessory Fitting Tool、Creator Hub 仪表板和发布操作都需要通过 GUI 完成。提供替代方案（Terrain:WriteVoxels、KeyframeSequenceProvider:RegisterKeyframeSequence、AvatarCreationService:ValidateUGCAccessoryAsync），或提供 GUI 操作路径（references/gui-paths.md）。未经用户同意，绝不发布、上传或花费 Robux。

通道

通道	用途	成本（实测）	规则
Studio MCP, Edit (rbx_run.run)	构建、审计、检查、编辑脚本	每次调用 67 ms；首次打开需 18.3 s	你自己的 place；每处理 1,000 个项目后让出执行权
Playtest (rbx_play.Playtest)	服务端和客户端代码、按键、行走、鼠标、游玩录制	4.2 s 后就绪	一个服务端、一个客户端；即使发生异常也会停止
Offline (rbx_check, Lune, lune_audit)	Studio 前置门禁、CI、纯逻辑测试	数秒	Lune 不支持物理和网络
Files（Rojo、Script Sync）	在 Git 中持久保存代码	rojo build 需 0.04 s	Studio 打开某个 .rbxl 时，绝不要重新构建它
Headless RunScript (rbx_run.run_headless)	不使用交互式 Studio 的 CI	每次运行约 6 s	任何 Studio 正在运行时都会拒绝执行
Open Cloud Luau Execution	对已发布 place 执行 CI 断言	每分钟 5 个任务	需要 API 密钥和用户批准；不支持物理模拟，且不会持久化任何内容

并发：最多 RBX_MAX（默认值为 3）个 Agent 可通过 rbx_env.place_slot() 持有一个 place。每个 place 都是独立的 Studio 进程，占用约 2.9 GB， 且每个窗口始终会进行渲染。若机器上打开的 place 窗口数达到 RBX_MAX_PLACES（默认值为 4），GPU 使用率或 GPU 内存超过 85%，或者 RAM 超过 75%，open_place 就会等待。运行结束后立即关闭 place。多个 StudioMCP 代理共用一个端口，因此主机代理切换期间，Studio.call 会重试 45 s。

先确认

询问一次，然后运行：

• 目标设备和最低配置设备（默认：手机、60 fps、16.67 ms）；
• 每个服务端的玩家数量和游戏类型；
• 使用 Rojo、Script Sync 还是仅用 Studio；
• 是否需要 Server Authority 或流式加载（新 place 中已启用 StreamingEnabled）；
• 哪个 place 属于 Agent 自己，以及交付物。

然后运行 rbx_env.doctor()，并对起始 place 执行 Audit.all(game)。在计划中记录预算、同步工具、数据模型方案和负责人。

专家循环

1. 用数字简述。 每台设备的预算、玩家数量、内存、艺术风格。关卡：后续每项检查都要有数字。
2. 放置场景。 在 place_slot 中依次调用 new_place 和 open_place，只执行一次。关卡：open_places() 列出该场景；Audit 统计中没有错误。
   • new_place 会覆盖 <dir>/default.project.json：dir 必须是你自己新建的文件夹，绝不能是用户的项目。
   • 对于现有游戏：先让用户保存，因为他们打开的窗口中的编辑内容尚未写入磁盘。将已保存场景的副本与代码构建合并（scenario-roblox-tooling P15、merge_place，任意仓库），然后打开合并后的场景，绝不要打开用户的文件。
   • 编辑工作树或用户源代码的副本：用户的 rojo serve 会将 src/ 同步到他们的窗口中。
3. 建立基线。 运行 Audit、编写最初会失败的 Spec 测试、从固定摄像机拍摄截图，并在试玩测试中记录 Stats.frames。关卡：记录好数字，打开表格。
4. 构建一个阶段，使用幂等代码块或文件；将领域工作分配给对应负责人（见下文）。向打开的场景添加实例：参见 procedures.md P2。
5. 测量。 rbx_check 的错误数为 0，Spec 全部通过，Audit 无问题；Server 和 Client 上的 Stats.frames 均符合帧率关卡：p95 不超过帧预算的 1.2 倍（60 fps 时为 20 ms），最差不超过 2 倍（33.3 ms）。Heartbeat 步进会在垂直同步间隔附近产生抖动，因此健康的 60 fps 场景读数为 p95 17.2 至 17.4 ms，而严格采用 16.67 ms 的关卡会导致测试失败；掉帧时读数约为 33 ms。
6. 查看并检查。 使用相同的摄像机，image_checks 结果为 ok，compare 显示应有变化，打开联系表，并根据负责人的评审意见进行判断。
7. **修复后再推进，**一次只做一项更改。
8. **附上证据交付：**已验证（运行内容、结果文件、数字、帧）；假设（未运行）。列出仍需由人工试玩以评估手感的内容。

工具包（scripts/，每个 scenario-roblox-* 技能都必须遵守的契约）

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1].parent / "scenario-roblox-expert" / "scripts"))

模块	主要调用	返回值
rbx_env	doctor(), new_place(dir, name, template, src), open_place(path), open_places(), place_slot(), machine_load(), wait_for_gpu()	dict；Path；已绑定的 Studio；[{id, name}]；槽位索引；百分比
rbx_mcp	Studio(place=...)：.call(tool, args)、.luau(code, dm)、.capture(png, extra)、.studios()、.tools()	MCP 结果 dict；文本；Path
rbx_run	run(studio, code, dm="Edit", kit=[...])、run_headless(place, code, kit)	{ok, result, error, output}
rbx_play	Playtest(studio)：.server(code, kit)、.client(code, kit)、.wait_for、.press(key, hold)、.walk_to([x, y, z])、.keys、.mouse、.console、.capture、.mode	rbx_run dict；工具文本
rbx_check	check(paths, code, sourcemap, selene, stylua, solver="both")	{ok, errors, warnings, tools}；标记为旧版或新版 solver 的发现结果
rbx_review	image_checks(png)、compare(a, b)、contact_sheet(pngs, out)	标记和 ok；changed_fraction；路径
AgentKit	Audit.all(game)、Stats.snapshot()、Stats.frames(s)、Stats.diff、Spec.new()	发现结果和统计；数字；{passed, failed, total}

完整签名、返回值结构和工具参数： references/procedures.md 第 1 节。领域代码放在各同级目录的 scripts/rbx_<domain>.py 和 scripts/agentkit/<domain>/ 中。rbx_env.close_place 仅供 编排器使用，默认会拒绝执行。

数字

数值	相对于	来源
16.67 / 33.33 ms	60 / 30 fps 时的一帧	Andrew [00:02:12]
67 ms	一次 execute_luau 往返，Edit	观察所得，L9
4.2 s / 18.3 s	Playtest 就绪 / 首次 open_place	观察所得，L13，L3
60 fps，p95 17.5 ms	Studio 中的空测试场景，Server 和 Client	观察所得，L16，L17
p95 20 ms，最差 33.3 ms	60 fps 时的帧门限（预算的 1.2 倍和 2 倍）	根据 L16，L17 推导
1.3 GB	2 GB 手机上的客户端内存目标	McNeill [00:27:53]
约 1,000	每个区块中执行一次 task.wait() 之前的项目数	工具说明
20,000 / 4,000	每个 MeshPart / 每件配饰的三角形数	规格页面
4096 px	场景中的最大纹理边长（配饰为 2048）	devforum 4316229
500 次/秒，1,000 字节	客户端远程请求；UnreliableRemoteEvent 载荷	RemoteEvent 参考

质量门限

• 可测量： rbx_check 0 个错误；先出现一次失败运行后，Spec 的 failed == 0 且 total > 0； Audit 的 tally.error == 0 且已移除弃用 API；Stats.frames 的 p95 和最差值均在预算范围内； Playtest 后控制台没有错误；get_studio_state 返回 Edit。
• 视觉： 每张截图都通过 image_checks；前后截图来自相同摄像机；打开并评判一张尺寸不超过 1,600 px 的联系表。

常见错误

错误	症状	修复
没有 studio_id，或选错窗口	修改应用到了用户的游戏	Studio(place=...) 按精确名称绑定
信任工具文本或退出代码	缺少输出；RunScript 出错时仍以 0 退出	使用 rbx_run 载荷
Playtest 从未停止	Edit 数据模型“在 Play 模式下不可用”	使用 with Playtest(s)；检查 mode()
Rojo 项目中的 "Position"	零件位于原点，构建退出代码为 0	使用 CFrame（12 个数字）；new_place 会转换
使用带有 [ 或 ( 的 script_grep	“未找到匹配项”	使用 % 转义
长批次没有让出执行权	Studio 冻结，MCP 断开	每批 1,000 项，并使用 task.wait()
以 Studio 内存或 FPS 作为门限	数值与设备上的数据不符	使用 Stats.frames 的 p95；进行设备测试
声称进行了多客户端测试	一次 MCP Playtest 只有一个客户端	使用 StudioTestService（此处尚未运行）
通过 GUI 编写脚本或向 Studio 发送 SIGTERM	窗口卡住，服务端列表为空	询问用户；绝不发送信号

路由与交接

技能	当需求涉及以下内容时路由至此
scenario-roblox-architecture	项目布局、客户端与服务端拆分、RunContext、服务、ModuleScripts、框架、Attributes 和标签
scenario-roblox-luau	任务库、延迟事件、类型、OOP、缓冲区、原生代码、Parallel Luau、代码中的内存泄漏
scenario-roblox-networking	远程对象、“利用漏洞者”、“远程请求泛滥”、验证、速率限制、网络所有权、Server Authority
scenario-roblox-data	“数据未保存”、DataStores、ProfileStore、迁移、MemoryStore、MessagingService、传送
scenario-roblox-environment	建造、地形、材质、MaterialVariant、光照、Atmosphere、天空、灰盒、逐模型流式加载
scenario-roblox-vfx-audio	粒子、光束、轨迹、翻页书、命中效果、Audio API、音效、音乐
scenario-roblox-ui	HUD、菜单、“UI 在手机上的缩放不正确”、游戏手柄、Input Action System、本地化
scenario-roblox-animation	Animator、动画轨道、骨架、Blender 动画导入、IK、面部、角色控制器
scenario-roblox-gameplay	战斗、命中框、射线检测、投射物、“NPC 寻路卡住”、游戏循环、载具
scenario-roblox-monetization	通行证、Developer Products、ProcessReceipt、订阅、广告、分析、实时运营
scenario-roblox-assets	“从 Blender 导入”、网格、纹理、SurfaceAppearance、“网格未通过验证”、UGC
scenario-roblox-tooling	Rojo、Wally、Rokit、Selene、StyLua、Lune、CI、Open Cloud、插件、Script Sync
scenario-roblox-performance	“我的游戏卡顿”、MicroProfiler、内存、流式加载设置、移动设备、发布

拆分项由一个技能负责，并在其数据包中列出第二个技能：

• 流式加载：设置归性能负责，逐模型模式归环境负责；
• 命中验证：规则归网络负责，射线检测归玩法负责；
• ProcessReceipt：契约归变现负责，持久化归数据负责；
• AI 网格：导入归资源负责，放置归环境负责，复用预算归性能负责；
• Server Authority：启用归网络负责，BindToSimulation 逻辑归玩法负责；
• 内存泄漏：诊断归性能负责，清理代码归 luau 负责。

每个交接数据包都包含：地点路径和窗口、渠道、以数字表示的需求、工具包调用、证据路径（结果 JSON、Audit 统计、Spec 总计、Stats、联系表）、已验证项、假设项、未解决问题以及边界。接收方须先复现一项证据，再以此为基础开展工作。

将 Scenario 资产导入 Roblox

资产	生成工具	导入位置
网格、道具、角色	scenario-3d	scenario-roblox-assets（导入，20,000 个三角形），然后导入 environment
PBR 贴图、可平铺材质	scenario-textures	scenario-roblox-assets（SurfaceAppearance）、scenario-roblox-environment（MaterialVariant）
天空盒	scenario-skyboxes	scenario-roblox-environment（Sky，六个面）
音乐、音效、环境音、语音	scenario-audio	scenario-roblox-vfx-audio（小于 20 MB，7 分钟，48 kHz）
图标、物品美术、UI 组件、贴花	scenario-game-assets	scenario-roblox-ui、scenario-roblox-environment
翻页动画帧	scenario-sprite-animation	scenario-roblox-vfx-audio（2x2、4x4 或 8x8 网格）

导入前（使用 scenario-quality-gate）和导入后，都要检查每项资产；导入后检查接收方评审的截图。 将任何文件加入已发布的游戏都会把它上传到 Roblox，因此需要获得用户同意。

陷阱

开始第一个任务前，请阅读 references/traps.md：其中介绍了 2026 年的 API 重命名与替换、Studio MCP 工具的相关事实（is_start、capture_id、datamodel_type "Client"、回复丢失）、流程隐患、Rojo 和 Script Sync 陷阱，以及版本差异的最新修正。

参考资料

• references/procedures.md：完整工具包 API、分块规则，以及每个流程及其测试和结果。
• references/traps.md：当前 Roblox 陷阱、MCP 和文件流程陷阱，以及最新修正。
• references/expert-notes.md：按来源整理的专家说法及时间戳。
• references/critique.md：评判 Agent 的 Roblox 工作和交接的评分标准。
• references/gui-paths.md：完成相同任务的 Studio 菜单，以及仅限 GUI 的步骤。
• references/sources.md：每个来源及其凭据、URL 和最佳时间戳。