roblox-studio-workflow

Roblox Studio 开发工作流（Rojo + selene + Studio MCP）

适用于基于 Rojo 的 Roblox 项目的可靠循环。在磁盘上编写代码，通过 Rojo 同步，并通过 Studio MCP 测试。

黄金规则

• 所有 Luau 代码都在磁盘上编写（src/），绝不要通过 MCP 在 Studio 中编写。Rojo 是唯一事实来源。在 Studio 中编辑脚本会导致 Rojo 重新同步时产生重复实例（模块会有两个副本；孤立副本会变得过时）。MCP 仅用于编辑地图/实例，以及测试和检查。
• 缩进使用 --!strict + 制表符（严格遵循项目的既定风格）。如果 Edit 工具的 old_string 因空白字符不匹配而失败，说明文件使用了制表符——请复制完全一致的前导制表符。
• 每次更改后都运行 lint，并保持无问题： 项目通常使用 selene（selene src 或 ~/.rokit/bin/selene src）。目标是 0 个错误 / 0 个警告 / 0 个解析错误。selene 无法发现两个重要的运行时陷阱——见下方的注意事项。

同步周期（关键——出错就会测试过时的代码）

Rojo 只会在 Studio 处于编辑模式时应用补丁，游玩期间不会。 游玩时进行的更改会排队，等游玩结束后才会生效。因此，要测试磁盘上的更改：

1. start_stop_play → 停止（is_start: false）
2. 等待约 10–15 秒，让 Rojo 完成补丁同步（不要跳过这一步——快速重启会运行过时的代码）
3. start_stop_play → 启动（is_start: true）
4. get_console_output → 确认启动过程无异常后再测试

如果 Rojo 插件的 websocket 静默断开（控制台中出现 [Rojo-Warn] Disconnected），在用户重新连接插件之前，任何内容都不会同步。如果出现重复实例：在 Rojo 插件中选择 Disconnect → 删除已同步的根节点（例如 ReplicatedStorage.Shared、ServerScriptService.Server、StarterPlayerScripts.Client）→ 重新连接一次，以干净地重建。

测试正在运行的游戏（通过 Studio MCP）

通过 MCP 操控游戏——有关工具及其注意事项（datamodel_type、独立 VM 规则、捕获/输入方面的问题、死链接修复），请参阅 roblox-studio-mcp 技能。测试策略：

• 通过游戏自身的远程对象操控游戏，而不是读取模块状态。 execute_luau 在独立的 Lua VM 中运行，因此 require 的模块是新副本，在该环境中调用 PlayerData.get(plr) 会返回 nil。应改为调用游戏的 RemoteFunctions/Events（Net.func("X"):InvokeServer(...)、Admin/调试远程对象），或直接读取/写入实例。FireAllClients 必须从 Server 数据模型运行。
• 通过可观察到的副作用验证，而不是检查模块内部状态。 对标签的 .Text、配饰数量，以及遍历 PlayerGui:GetDescendants() 时的 ImageLabel.Image 进行断言。纯辅助函数可以使用合成输入在 execute VM 中进行单元测试。
• 让会产生副作用的循环遵守实际冷却时间——服务器冷却中的操作会拒绝快速调用，这会看起来像是测试失败。请拉开调用间隔。
• 先用 get_console_output 确认启动过程无异常，再相信测试结果（这可以发现诸如超出 200 个局部变量上限或卡在 WaitForChild 等静默故障）。

引擎／语言注意事项（selene 检查不到这些问题——它们会在运行时引发故障）

• 大型主代码块中的局部变量上限为 200 个（例如 init.client）：添加顶层 local 会在运行时抛出 "Out of local registers: exceeded limit 200"（selene 检查不到，启动会悄无声息地失败）。解决方法：将相关状态打包到一个表局部变量中（local ui = {}，然后使用 ui.x、ui.y），将模块引用挂到表字段上（ui.mod = require(...)），用 do … end 包住一组代码，或内联只使用一次的局部变量。函数体／闭包中的局部变量不计入主代码块。
• selene 与较新的类： 如果某个类不在 selene 的列表中（例如非常新的 Instance 类型），Instance.new("SomeNewClass") 会未通过 selene 的标准库检查。如果该实例由其服务自动创建，请改用 FindFirstChildOfClass／FindFirstChild 查找实例并设置属性，而不是使用 Instance.new。
• UI 专属陷阱见 roblox-ui-hud 技能——字体字形（✕→X，不要使用旗帜 emoji）、点击外部区域关闭、水平 UIListLayout 顺序、UDim2.fromScale lint，以及布尔值可见性 bug。进行任何 UI／HUD 工作时都应加载该技能。

PlayerData 持久化检查清单（静默数据丢失的常见原因）

对于每个保存的字段，确认以下各项全部齐备：类型注释 · 默认值（初始化）· 序列化 · 加载 · 重置。字段已保存却未加载，会在玩家重新加入时悄悄重置；随后下一次自动保存会将重置后的值写回，造成永久性数据丢失。添加新的属性／升级键时，请 grep 加载函数，确保它会恢复该键（最好遍历已保存的子表，让新键也能自动兼容）。

（直接操作 Studio——运行 Luau、截图、生成资源、上传图片、修复失效的 MCP 链接——请使用 roblox-studio-mcp 技能。）