roblox-rojo

roblox-rojo

官方来源：

• https://rojo.space/docs/v7/（文档索引；当前主版本为 v7）
• https://rojo.space/docs/v7/getting-started/installation/
• https://rojo.space/docs/v7/getting-started/new-game/
• https://rojo.space/docs/v7/getting-started/existing-game/
• https://rojo.space/docs/v7/project-format/
• https://rojo.space/docs/v7/properties/
• https://rojo.space/docs/v7/sync-details/
• https://rojo.space/docs/v7/upgrade/
• https://github.com/rojo-rbx/rojo/releases（最新 CLI/插件发布版本；推荐安装固定版本前请核实版本）
• https://github.com/rojo-rbx/rojo（文档滞后时，CLI 标志和更新日志以此为准）

Rojo 会将文件系统项目映射为 Roblox 实例，让你可以使用外部工具（VS Code、Git、代码检查工具、格式化工具）进行编辑，并实时同步，或构建为 Studio/place 文件。本技能涵盖 rojo.space 文档所述并由当前 rojo-rbx/rojo 发布系列实现的 Rojo 7。

心智模型

部件	作用
Rojo CLI	读取项目文件和文件系统；提供实时同步服务、构建 place/model 文件、上传、生成 sourcemap、执行 syncback。
Studio 插件	连接到本地服务会话，并将补丁应用到已打开的 place 中。
项目文件	*.project.json / *.project.jsonc，用于描述实例树和选项。
文件系统树	$path 节点下的脚本、模型、JSON/TOML/YAML/CSV/文本文件会变为实例。

实时同步时，Rojo 的方向是文件系统 → Studio（一个主要方向）。插件中的可选双向同步仍属实验性功能，尚未完善。不要围绕它设计生产工作流。要从 place 同步到文件，请使用 rojo syncback（Rojo 7.7+）或外部移植工具。

快速开始

1. 安装 CLI（推荐项目使用 Rokit；也支持 GitHub 二进制文件或 cargo install rojo --version ^7）。
2. 使用 rojo plugin install 安装 Studio 插件（也可使用适配对应主版本的 GitHub rbxm / Roblox.com 插件）。
3. 运行 rojo init my-game（或打开文件夹 + VS Code“Rojo: Open Menu”）。
4. 在项目文件夹中运行 rojo serve。
5. 在 Studio 中：打开 Rojo 插件面板 → Connect。
6. 编辑磁盘上的文件，并观察同步情况。使用 rojo build -o build.rbxlx 一次性生成 place 文件。

完整安装矩阵和 CLI 标志参见：references/installation-and-cli.md。

脚本文件 → 实例映射（默认）

支持 .lua 和 .luau。默认规则（依据 Rojo 源码 / 同步文档）：

文件模式	实例（当 emitLegacyScripts 为 true，这是默认值时）	实例（当 emitLegacyScripts 为 false 时）
*.server.lua(u)	Script（legacy RunContext）	Script，且 RunContext = Server
*.client.lua(u)	LocalScript	Script，且 RunContext = Client
*.plugin.lua(u)	Script，且 RunContext = Plugin	相同
其他 *.lua(u)	ModuleScript	相同

Init usurpers（用脚本替换父文件夹）：init.server.lua(u)、init.client.lua(u)、init.plugin.lua(u)、init.lua(u)。每个文件夹只能有一种 init 脚本类型。包含 default.project.json / default.project.jsonc 的目录会被视为嵌套项目，而不是普通文件夹。

其他默认映射：.rbxm/.rbxmx 模型、.model.json(c)、普通 .json(c) → 返回表的 ModuleScript，.toml / .yml/.yaml 同理，.csv → LocalizationTable，.txt → StringValue。

详情、元文件和限制参见：references/sync-details.md。

项目文件要点

最简场景树结构（已知服务无需 $className，即可推断）：

{
  "name": "MyGame",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "$path": "src/ReplicatedStorage"
    },
    "ServerScriptService": {
      "$path": "src/ServerScriptService"
    },
    "StarterPlayer": {
      "StarterPlayerScripts": {
        "$path": "src/StarterPlayerScripts"
      }
    }
  }
}

重要顶层字段（文档 + 当前 CLI）：

字段	用途
name	项目／实例名称（default.project.json 中可选；未指定时使用文件夹名称）。
tree	根实例描述（必填）。
servePort	rojo serve 的默认端口（默认值为 34872）。
serveAddress	CLI 未指定 --address 时的默认绑定地址。
servePlaceIds / blockedPlaceIds	按 place ID 允许／拒绝实时同步目标。
placeId / gameId	连接时设置 Studio place／universe ID。
serveAllowedHosts	serve 的额外 Host／Origin 值（主机名访问）；CLI 的 --allowed-hosts 会覆盖此设置。
globIgnorePaths	要忽略的 glob 模式（近期版本支持 gitignore 风格的否定规则）。
emitLegacyScripts	默认值 true = Script／LocalScript；false = 服务器／客户端文件使用带 RunContext 的 Script。
syncRules	自定义文件→中间件匹配模式。
syncbackRules	控制 rojo syncback 行为。

实例节点使用 $className、$path、$properties、$attributes、$ignoreUnknownInstances 以及子项键。优先使用隐式属性语法。完整格式：references/project-format.md。

日常命令

# New project (place | model | plugin)
rojo init my-game
rojo init --kind model
rojo init --kind plugin --skip-git

# Live sync (default localhost:34872)
rojo serve
rojo serve --port 34872 --address 127.0.0.1

# Build place/model
rojo build -o build.rbxlx
rojo build -o build.rbxl
rojo build --plugin MyPlugin.rbxm
rojo build -o out.rbxlx --watch

# Sourcemap for editor tooling
rojo sourcemap --output sourcemap.json
rojo sourcemap --watch --absolute

# Upload (prefer dedicated deploy account; never commit cookies/keys)
rojo upload --asset_id PLACE_ID --cookie "..."
rojo upload --asset_id PLACE_ID --api_key "..." --universe_id UNIVERSE_ID

# Place file → filesystem into an existing project tree
rojo syncback . --input place.rbxl
rojo syncback . --input place.rbxlx --dry-run --list

# Plugin management / docs / format
rojo plugin install
rojo plugin uninstall
rojo doc
rojo fmt-project

实时同步限制

并非所有属性类型都能实时应用（受 Studio 插件 API 限制）。以下常见情况可能需要完整的构建 + 打开，而非实时同步：

• 二进制数据（Terrain、CSG）
• MeshPart.MeshId
• HttpService.HttpEnabled

构建与实时同步所支持的属性类型列于 Properties 页面和 rbx-dom 的覆盖率图表中。实时同步遇到类／属性问题时，请使用 rojo build 重新构建并打开 place。

rojo serve 默认绑定到 loopback。绑定到可通过网络访问的地址会暴露会话：近期 Rojo 版本会验证 Host／Origin、限制部分 API 仅供本地客户端使用，并对非本地绑定发出警告。优先使用 localhost；如果必须对外开放，请谨慎配置 serveAllowedHosts / --allowed-hosts。

移植现有游戏

1. 移植前，将 Studio 代码重构到更少的服务根目录位置（ReplicatedStorage、ServerScriptService、StarterPlayer，以及通过 CollectionService 使用标签）。
2. 优先使用**rojo syncback**，并确保项目已列出要填充的服务／路径（rojo syncback path/to/project --input place.rbxl）。只有项目树中已有节点的后代才会被写入。
3. 官方文档中提到的替代方案：rbxlx-to-rojo、用于自定义流水线的 Lune。
4. 随时可以停止使用 Rojo：Rojo 会构建普通的 place／model 文件；你可以停止使用文件系统树，改为仅在 Studio 中编辑。

工作流和 syncback 规则：references/workflows-and-syncback.md。

Agent 检查清单

• 应该让 CLI 和插件使用相同的主版本（Rojo 7 插件搭配 Rojo 7 CLI）。
• 应该在升级 CLI 后运行 rojo plugin install。
• 应该将共享模块放在 ReplicatedStorage 路径下，并将服务器权限逻辑放在 ServerScriptService 下。
• 应该使用 .luau（从 7.4 开始，Rojo 的 init 模板使用 .luau）。
• 应该仅在团队了解现代 RunContext 脚本时才设置 emitLegacyScripts: false（并了解客户端文件会变成 Script+Client，而不是 LocalScript）。
• 不要臆造 CLI 标志或项目键。如有疑问，请运行 rojo --help / rojo <cmd> --help，或重新查看文档／变更日志。
• 不要提交与 rojo upload 配合使用的 .ROBLOSECURITY cookie 或 Open Cloud API 密钥。
• 不要将实验性的双向同步视为可靠的源代码管理方式。
• 不要将 Rojo 与 Roblox 的 Script Sync 或 Studio MCP 混为一谈。它们是不同的工具，可以共存（参见 roblox-mcp）。

验证

• rojo --version 显示与预期固定版本匹配的 7.x 版本。
• Studio 显示 Rojo 7 插件；连接 rojo serve 成功。
• 编辑映射到 $path 下的 .server.luau 文件后，Studio 中的正确服务会更新。
• rojo build -o build.rbxlx 生成的文件可在 Studio 中正常打开。
• 如果生成了 sourcemap.json，请确保它已加入 gitignore（近期版本中的 Rojo 默认 gitignore 模板已包含该文件）。

后续步骤

1. 确认安装路径：references/installation-and-cli.md。
2. 设置树结构：references/project-format.md。
3. 正确命名文件：references/sync-details.md。
4. 关于团队协作、移植和部署：references/workflows-and-syncback.md。

参考索引

• installation-and-cli.md：安装 Rojo，或选择 CLI 命令和标志。
• project-format.md：编写项目树、属性、路径或嵌套项目。
• sync-details.md：将文件映射到实例，或诊断实时同步无法应用的更改。
• workflows-and-syncback.md：移植现有场景、导出 Studio 更改，或在 CI 中构建。