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 ファイルのビルド、アップロード、ソースマップ作成、同期の取り込みを行います。
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. ディスク上のファイルを編集し、同期されることを確認します。1 回限りの place ファイルには rojo build -o build.rbxlx を使用します。

インストール方法の一覧と CLI フラグについては、references/installation-and-cli.md を参照してください。

スクリプトファイル → インスタンスの対応付け（デフォルト）

.lua と .luau の両方に対応しています。デフォルトのルール（Rojo のソース／同期ドキュメントに基づく）は次のとおりです。

ファイルパターン	インスタンス（emitLegacyScripts が true の場合。デフォルト）	インスタンス（emitLegacyScripts が false の場合）
*.server.lua(u)	Script（レガシーの RunContext）	RunContext = Server の Script
*.client.lua(u)	LocalScript	RunContext = Client の Script
*.plugin.lua(u)	RunContext = Plugin の Script	同じ
その他の *.lua(u)	ModuleScript	同じ

Init による置き換え（親フォルダーをスクリプトで置き換えます）：init.server.lua(u)、init.client.lua(u)、init.plugin.lua(u)、init.lua(u)。フォルダーごとに使用できる init スクリプトの種類は 1 つだけです。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 Scripts を使用します。
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 はデフォルトでループバックにバインドされます。ネットワークから到達可能なアドレスにバインドすると、セッションが公開されます。最近の 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 を参照してください。

エージェント向けチェックリスト

• 推奨：CLI とプラグインのメジャーバージョンを同じにします（Rojo 7 プラグインと Rojo 7 CLI）。
• 推奨：CLI をアップグレードした後に rojo plugin install を実行します。
• 推奨：共有モジュールは ReplicatedStorage のパスに、サーバー側の権限を持つコードは ServerScriptService に配置します。
• 推奨：.luau を使用します（Rojo の init テンプレートでは 7.4 以降 .luau が使用されます）。
• 推奨：チームが最新の RunContext スクリプト（およびクライアントのファイルが LocalScript ではなく Script+Client になること）を理解している場合に限り、emitLegacyScripts: false を設定します。
• 禁止：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 が生成される場合、Git の追跡対象外になっていること（最近のリリースでは、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：既存の place を移行する、Studio の変更をエクスポートする、または CI でビルドする方法を説明します。