Back to Details

roblox-tooling

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Roblox tooling

Roblox 工具链

Pick a sync model

选择同步模型

NeedUse
Edit scripts in an external editor / git for code only; keep Studio as source of truth; Team CreateStudio Script Sync (built in: right-click a folder → Sync to…)
Whole project as files, file system is the source of truth, CI builds, packagesRojo (
rojo serve
+ Studio plugin)
Script Sync syncs only 
Script
/
LocalScript
/
ModuleScript
/
Folder
(≤ 10,000 scripts per synced root, ≤ 128 roots); don't sync scripts that carry attributes/tags (they're not written to disk). Pair either with the Luau Language Server VS Code extension + its Luau Language Server Companion Studio plugin (sends the DataModel tree so requires and instance paths type-check).
需求使用方式
仅在外部编辑器/git 中编辑脚本代码；以 Studio 为事实来源；Team CreateStudio Script Sync（内置：右键单击文件夹 → Sync to…）
将整个项目以文件形式管理；以文件系统为事实来源；使用 CI 构建和包Rojo（
rojo serve
+ Studio 插件）
Script Sync 仅同步 
Script
/
LocalScript
/
ModuleScript
/
Folder
（每个已同步根目录 ≤ 10,000 个脚本，≤ 128 个根目录）；不要同步带有 attributes/tags 的脚本（它们不会写入磁盘）。 任一方案都可搭配 Luau Language Server VS Code 扩展及其 Luau Language Server Companion Studio 插件（该插件会发送 DataModel 树，使 require 和实例路径能够通过类型检查）。

Rokit: pinned toolchain

Rokit：固定版本工具链

toml
undefined
toml
undefined

rokit.toml (commit it; run 
rokit install
)

rokit.toml (commit it; run 
rokit install
)

[tools] rojo = "rojo-rbx/rojo@7.7.0" wally = "UpliftGames/wally@0.3.2" lune = "lune-org/lune@0.10.5" stylua = "JohnnyMorganz/StyLua@2.5.2" selene = "Kampfkarren/selene@0.31.0" luau-lsp = "JohnnyMorganz/luau-lsp@1.70.1" darklua = "seaofvoices/darklua@0.19.0"

Install Rokit: `curl -sSf https://raw.githubusercontent.com/rojo-rbx/rokit/main/scripts/install.sh | bash`
(Windows: `install.ps1`). Add tools with `rokit add owner/repo`. Versions above are current as of
September 2026; bump deliberately. (Aftman and Foreman are older equivalents.)
[tools] rojo = "rojo-rbx/rojo@7.7.0" wally = "UpliftGames/wally@0.3.2" lune = "lune-org/lune@0.10.5" stylua = "JohnnyMorganz/StyLua@2.5.2" selene = "Kampfkarren/selene@0.31.0" luau-lsp = "JohnnyMorganz/luau-lsp@1.70.1" darklua = "seaofvoices/darklua@0.19.0"

安装 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 project

Rojo 项目

json
{
  "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 }
    }
  }
}
File mapping: 
Foo.luau
→ ModuleScript, 
Foo.server.luau
→ Script, 
Foo.client.luau
→ LocalScript, folder with 
init.luau
/
init.server.luau
/
init.client.luau
→ that script with children, 
*.meta.json
→ properties/attributes, 
*.model.json
/
.rbxm
/
.rbxmx
→ instances, 
*.json
/
*.toml
/
*.txt
→ ModuleScript returning data / StringValue. Commands: 
rojo serve
, 
rojo build -o game.rbxl
, 
rojo sourcemap default.project.json -o sourcemap.json
(for luau-lsp), 
rojo upload
/ Open Cloud for publishing. Keep maps/art in Studio (or 
.rbxm
files) and code in Rojo — partially managed trees are fine.
json
{
  "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
→ properties/attributes，
*.model.json
/
.rbxm
/
.rbxmx
→ 实例，
*.json
/
*.toml
/
*.txt
→ 返回数据/StringValue 的 ModuleScript。命令：
rojo serve
、
rojo build -o game.rbxl
、 
rojo sourcemap default.project.json -o sourcemap.json
（供 luau-lsp 使用）、
rojo upload
/ Open Cloud 用于发布。在 Studio（或 
.rbxm
文件）中保留地图/美术资源，在 Rojo 中保留代码——允许只管理部分树。

Packages

包管理

  • Wally (
    wally.toml
    , 
    wally install
    → 
    Packages/
    , 
    ServerPackages/
    for 
    realm = "server"
    ):
    toml
    [dependencies]
React = "jsdotlua/react@17.2.1"
ReactRoblox = "jsdotlua/react-roblox@17.2.1"
[server-dependencies]
ProfileStore = "lm-loleris/profilestore@1.0.3"
    Wally thunks lose types: run 
    wally-package-types --sourcemap sourcemap.json Packages/
    after install. Check each package's page on wally.run for its exact name/version.
  • pesde (
    pesde.toml
    ): newer manager for Roblox/Lune/Luau that can also depend on Wally packages.
  • Commit 
    wally.lock
    /
    pesde.lock
    ; don't commit 
    Packages/
    .
  • Wally（
    wally.toml
    、
    wally install
    → 
    Packages/
    ；对于 
    realm = "server"
    → 
    ServerPackages/
    ）：
    toml
    [dependencies]
React = "jsdotlua/react@17.2.1"
ReactRoblox = "jsdotlua/react-roblox@17.2.1"
[server-dependencies]
ProfileStore = "lm-loleris/profilestore@1.0.3"
    Wally thunk 会丢失类型信息：安装后运行 
    wally-package-types --sourcemap sourcemap.json Packages/
    。 请在 wally.run 上查看每个包的准确名称和版本。
  • pesde（
    pesde.toml
    ）：用于 Roblox/Lune/Luau 的较新包管理器，也可以依赖 Wally 包。
  • 提交 
    wally.lock
    /
    pesde.lock
    ；不要提交 
    Packages/
    。

Code quality

代码质量

  • luau-lsp (editor + CLI) — type checking against Roblox definitions. CLI: 
    luau-lsp analyze --definitions=@roblox=globalTypes.d.luau --sourcemap=sourcemap.json --base-luaurc=.luaurc src/
    (definitions: 
    https://raw.githubusercontent.com/JohnnyMorganz/luau-lsp/main/scripts/globalTypes.d.luau
    ). Enable the new solver in the editor (
    luau-lsp.fflags.enableNewSolver
    ) to match Studio.
  • StyLua — formatter. 
    stylua.toml
    : 
    indent_type = "Tabs"
    , 
    column_width = 120
    . 
    stylua --check src
    .
  • selene — linter. 
    selene.toml
    : 
    std = "roblox"
    (generate/refresh with 
    selene generate-roblox-std
    ).
  • darklua — code transforms (e.g. convert string requires, bundle) for publishing pipelines.
  • .luaurc
    — per-directory type-check mode and require aliases:
    json
    { "languageMode": "strict", "aliases": { "Shared": "src/shared", "Packages": "Packages" } }
    Roblox resolves string requires relative to the DataModel (
    ./
    , 
    ../
    , 
    @self
    , 
    @game
    ); custom 
    .luaurc
    aliases need tooling (luau-lsp/darklua) that understands your mapping.
  • luau-lsp（编辑器 + CLI）——根据 Roblox 定义执行类型检查。CLI： 
    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
    ）。 在编辑器中启用新的 solver（
    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、bundle）。
  • .luaurc
    ——按目录配置类型检查模式和 require 别名：
    json
    { "languageMode": "strict", "aliases": { "Shared": "src/shared", "Packages": "Packages" } }
    Roblox 会相对于 DataModel 解析字符串形式的 require（
    ./
    、
    ../
    、
    @self
    、
    @game
    ）；自定义 
    .luaurc
    别名需要 luau-lsp/darklua 等能够理解映射关系的工具。

Lune

Lune

Standalone Luau runtime for scripts outside Roblox: build steps, place file manipulation (
@lune/roblox
reads/writes 
.rbxl
/
.rbxm
), asset pipelines, running pure-Luau unit tests, calling Open Cloud with 
@lune/net
. 
lune run scripts/build
.
用于在 Roblox 之外运行脚本的独立 Luau runtime：构建步骤、place 文件操作 （
@lune/roblox
读取/写入 
.rbxl
/
.rbxm
）、资源管线、运行纯 Luau 单元测试，以及通过 
@lune/net
调用 Open Cloud。
lune run scripts/build
。

roblox-ts

roblox-ts

If the repo has 
tsconfig.json
, 
package.json
with 
roblox-ts
and 
@rbxts/types
, write TypeScript: 
npx rbxtsc -w
compiles 
src/*.ts
to 
out/*.luau
, and Rojo syncs 
out/
. Use 
@rbxts/services
, 
@rbxts/*
packages from npm. Don't hand-edit generated Luau.
如果仓库包含 
tsconfig.json
，以及包含 
roblox-ts
和 
@rbxts/types
的 
package.json
，则可编写 TypeScript： 
npx rbxtsc -w
会将 
src/*.ts
编译为 
out/*.luau
，然后由 Rojo 同步 
out/
。使用 npm 上的 
@rbxts/services
、
@rbxts/*
包。不要手动编辑生成的 Luau。

Git and CI

Git 和 CI

.gitignore
: 
*.rbxl.lock
, 
*.rbxlx.lock
, 
Packages/
, 
ServerPackages/
, 
sourcemap.json
, build outputs. A ready-to-use GitHub Actions workflow (install tools, format check, lint, type-check, build, publish via Open Cloud): references/ci-workflow.md.
.gitignore
：
*.rbxl.lock
、
*.rbxlx.lock
、
Packages/
、
ServerPackages/
、
sourcemap.json
、构建输出。 一个现成可用的 GitHub Actions 工作流（安装工具、检查格式、执行 lint、类型检查、构建并通过 Open Cloud 发布）： references/ci-workflow.md。

Related skills

相关 skill

roblox-testing
(running tests in CI), 
roblox-open-cloud
(publishing, Luau execution), 
roblox-studio-mcp
(driving Studio from an agent), 
roblox-luau
.
roblox-testing
（在 CI 中运行测试）、
roblox-open-cloud
（发布、Luau 执行）、 
roblox-studio-mcp
（由 Agent 驱动 Studio）、
roblox-luau
。