roblox-tooling

Roblox 工具链

选择同步模型

需求	使用
在外部编辑器 / git 中仅编辑代码脚本；以 Studio 为唯一事实来源；Team Create	Studio Script Sync（内置：右键点击文件夹 → Sync to…）
将整个项目作为文件，以文件系统为唯一事实来源，CI 构建，包管理	Rojo（rojo serve + Studio 插件）

Script Sync 仅同步 Script/LocalScript/ModuleScript/Folder（每个同步根目录 ≤ 10,000 个脚本， ≤ 128 个根目录）；不要同步带有属性/标签的脚本（它们不会写入磁盘）。 将上述任一方案与 Luau Language Server VS Code 扩展及其 Luau Language Server Companion Studio 插件搭配使用（它会发送 DataModel 树，以便对 require 和实例路径进行类型检查）。

Rokit：固定工具链

# rokit.toml (commit it; run `rokit install`)
[tools]
rojo = "rojo-rbx/[email protected]"
wally = "UpliftGames/[email protected]"
lune = "lune-org/[email protected]"
stylua = "JohnnyMorganz/[email protected]"
selene = "Kampfkarren/[email protected]"
luau-lsp = "JohnnyMorganz/[email protected]"
darklua = "seaofvoices/[email protected]"

安装 Rokit：curl -sSf https://raw.githubusercontent.com/rojo-rbx/rokit/main/scripts/install.sh | bash （Windows：install.ps1）。使用 rokit add owner/repo 添加工具。以上版本为 2026 年 9 月的最新版本； 请谨慎升级。（Aftman 和 Foreman 是较旧的等效工具。）

Rojo 项目

{
  "name": "my-game",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "Shared": { "$path": "src/shared" },
      "Packages": { "$path": "Packages" }
    },
    "ServerScriptService": {
      "Server": { "$path": "src/server" },
      "ServerPackages": { "$path": "ServerPackages" }
    },
    "StarterPlayer": {
      "StarterPlayerScripts": {
        "Client": { "$path": "src/client" }
      }
    },
    "Workspace": {
      "$properties": { "StreamingEnabled": true }
    }
  }
}

文件映射：Foo.luau → ModuleScript，Foo.server.luau → Script，Foo.client.luau → LocalScript， 包含 init.luau/init.server.luau/init.client.luau 的文件夹 → 该脚本及其子项， *.meta.json → 属性/特性，*.model.json/.rbxm/.rbxmx → 实例，*.json/*.toml/*.txt → 返回数据的 ModuleScript / StringValue。命令：rojo serve、rojo build -o game.rbxl、 rojo sourcemap default.project.json -o sourcemap.json（用于 luau-lsp）、rojo upload / Open Cloud 用于 发布。将地图/美术资源保留在 Studio（或 .rbxm 文件）中，将代码放在 Rojo 中 — 部分托管的树也可以。

包管理

• Wally（wally.toml，wally install → Packages/，ServerPackages/ 用于 realm = "server"）：

  [dependencies]
  React = "jsdotlua/[email protected]"
  ReactRoblox = "jsdotlua/[email protected]"
  [server-dependencies]
  ProfileStore = "lm-loleris/[email protected]"
  

  Wally 的 thunk 会丢失类型：安装后运行 wally-package-types --sourcemap sourcemap.json Packages/。 在 wally.run 上查看每个包的页面以获取其确切名称/版本。
• pesde（pesde.toml）：较新的管理器，适用于 Roblox/Lune/Luau，也可以依赖 Wally 包。
• 提交 wally.lock/pesde.lock；不要提交 Packages/。

代码质量

• luau-lsp（编辑器 + 命令行）— 根据 Roblox 定义进行类型检查。命令行： luau-lsp analyze --definitions=@roblox=globalTypes.d.luau --sourcemap=sourcemap.json --base-luaurc=.luaurc src/ （定义文件：https://raw.githubusercontent.com/JohnnyMorganz/luau-lsp/main/scripts/globalTypes.d.luau）。 在编辑器中启用新的求解器（luau-lsp.fflags.enableNewSolver）以与 Studio 保持一致。
• StyLua — 格式化工具。stylua.toml：indent_type = "Tabs"，column_width = 120。stylua --check src。
• selene — 代码检查工具。selene.toml：std = "roblox"（使用 selene generate-roblox-std 生成/刷新）。
• darklua — 代码转换（例如转换字符串 require、打包），用于发布流水线。
• .luaurc — 按目录的类型检查模式和 require 别名：

  { "languageMode": "strict", "aliases": { "Shared": "src/shared", "Packages": "Packages" } }
  

  Roblox 相对于 DataModel 解析字符串 require（./、../、@self、@game）；自定义 .luaurc 别名需要能理解你的映射的工具（luau-lsp/darklua）。

Lune

用于 Roblox 之外脚本的独立 Luau 运行时：构建步骤、place 文件操作 （@lune/roblox 读取/写入 .rbxl/.rbxm）、资源流水线、运行纯 Luau 单元测试、使用 @lune/net 调用 Open Cloud。lune run scripts/build。

roblox-ts

如果仓库包含 tsconfig.json、带有 roblox-ts 和 @rbxts/types 的 package.json，则编写 TypeScript： npx rbxtsc -w 将 src/*.ts 编译为 out/*.luau，Rojo 同步 out/。使用来自 npm 的 @rbxts/services、 @rbxts/* 包。不要手动编辑生成的 Luau。

Git 与 CI

.gitignore：*.rbxl.lock、*.rbxlx.lock、Packages/、ServerPackages/、sourcemap.json、构建产物。 一个开箱即用的 GitHub Actions 工作流（安装工具、格式检查、lint、类型检查、构建、通过 Open Cloud 发布）：references/ci-workflow.md。

相关技能

roblox-testing（在 CI 中运行测试）、roblox-open-cloud（发布、Luau 执行）、 roblox-studio-mcp（从 Agent 驱动 Studio）、roblox-luau。