rojo-pro

Rojo Professional

Rojo 在文件系统与 Roblox Studio 之间搭建桥梁：在外部编辑器中编写代码，通过插件实时同步到 Studio，构建 .rbxl/.rbxm 文件以供部署，并将所有内容纳入 Git 管理。

快速参考

必备命令

# Initialize new project
rojo init my-game

# Start dev server (connects to Studio plugin)
rojo serve

# Serve specific project file
rojo serve dev.project.json

# Build standalone file
rojo build -o game.rbxl
rojo build deploy.project.json -o game.rbxl

# Generate sourcemap (for luau-lsp type checking)
rojo sourcemap default.project.json -o sourcemap.json

# Install Studio plugin
rojo plugin install

文件命名约定

文件模式	Roblox 实例
*.server.luau	Script（在服务端运行）
*.client.luau	LocalScript（在客户端运行）
*.luau 或 *.lua	ModuleScript
init.server.luau	目录会变为 Script
init.client.luau	目录会变为 LocalScript
init.luau	目录会变为 ModuleScript
*.model.json	自定义模型定义
*.meta.json	同级文件/文件夹的元数据
*.rbxm / *.rbxmx	二进制/XML 模型文件
*.txt	StringValue
*.csv	LocalizationTable

项目文件结构

{
  "name": "MyGame",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "$className": "ReplicatedStorage",
      "Shared": { "$path": "src/Shared" },
      "Packages": { "$path": "Packages" }
    },
    "ServerScriptService": {
      "$className": "ServerScriptService",
      "Server": { "$path": "src/Server" }
    },
    "ReplicatedFirst": {
      "$className": "ReplicatedFirst",
      "Client": { "$path": "src/Client" }
    },
    "StarterPlayer": {
      "$className": "StarterPlayer",
      "StarterPlayerScripts": {
        "$className": "StarterPlayerScripts",
        "$path": "src/StarterPlayerScripts"
      }
    }
  }
}

树节点属性

• $className - Roblox 类（服务必需；使用 $path 时可选）
• $path - 要同步的文件系统路径
• $properties - 实例属性
• $ignoreUnknownInstances - 不删除未跟踪的实例（适用于地形）
• 其他任意键 - 子实例名称

可选项目设置

{
  "servePort": 34872,
  "servePlaceIds": [123456789],
  "placeId": 123456789,
  "gameId": 987654321,
  "globIgnorePaths": ["**/*.spec.luau", "**/test/**"],
  "emitLegacyScripts": true
}

项目设置和多环境模式：references/patterns.md。同步故障排查：references/sharp_edges.md。

常见模式

多项目设置（开发/生产）

project/
├── default.project.json    # Development (rojo serve)
├── deploy.project.json     # Production build
├── src/
├── Packages/
└── ...

库/软件包分发

分发独立模块的最简配置：

{
  "name": "my-library",
  "tree": {
    "$path": "src"
  }
}

设置实例属性

{
  "$className": "Part",
  "$properties": {
    "Anchored": true,
    "Size": [4, 1, 2],
    "Color": [1, 0, 0],
    "BrickColor": { "BrickColor": "Bright red" },
    "Material": { "Enum": "Material.Neon" }
  }
}

保留在 Studio 中创建的实例

{
  "Workspace": {
    "$className": "Workspace",
    "$ignoreUnknownInstances": true,
    "GameContent": { "$path": "src/Workspace" }
  }
}

与工具链集成

Aftman（工具管理）

# aftman.toml
[tools]
rojo = "rojo-rbx/[email protected]"
wally = "UpliftGames/[email protected]"
stylua = "JohnnyMorganz/[email protected]"
selene = "Kampfkarren/[email protected]"
luau-lsp = "JohnnyMorganz/[email protected]"

Wally（软件包管理）

# wally.toml
[package]
name = "author/my-game"
version = "1.0.0"
realm = "shared"
registry = "https://github.com/UpliftGames/wally-index"

[dependencies]
Promise = "evaera/[email protected]"
Signal = "sleitnick/[email protected]"

软件包会安装到 Packages/，并且必须在项目文件中进行映射。

类型检查设置

# Generate sourcemap for luau-lsp
rojo sourcemap default.project.json -o sourcemap.json

# Generate Wally package types
wally-package-types --sourcemap sourcemap.json Packages

克隆仓库后

如果缺少 Packages/，或者看到“path does not exist”错误：

wally install                                           # Install packages from wally.toml
rojo sourcemap default.project.json -o sourcemap.json   # Regenerate sourcemap

Packages/ 被 gitignore 忽略；每次克隆后都必须重新生成。

反模式

不要：

• 在 Rojo 连接时于 Studio 中编辑文件（更改会被覆盖）
• 在文件/文件夹名称中使用空格（使用 PascalCase 或 snake_case）
• 忘记为 Roblox 服务指定 $className
• 不一致地混用 .lua 和 .luau 扩展名
• 将服务端代码放在 ReplicatedStorage 中（有安全风险）
• 将 Packages/ 提交到 git（它由 wally install 生成）
• 克隆后忘记运行 wally install（否则不会有 Packages/）

要做：

• 始终使用 .luau 扩展名（Roblox 官方的 Lua 方言）
• 更改项目结构后更新 sourcemap
• 使用 init.luau 实现文件夹作为模块的模式
• 将 Packages/ 添加到 .gitignore
• 为不同环境使用多项目设置