SyncはRoblox Studioの状態とローカルファイルを連携させ、AIがプロジェクト全体のコンテキストを安定して読み込み・変更できるようにする機能です。

なぜSyncが重要か

Syncがなければ、AIは会話に貼り付けたコードの一部だけを見て判断することになります。Syncをオンにするとプロジェクト全体を基準に作業するため、以下が容易になります。

複数スクリプトにまたがるリファクタリングを一貫して適用
変更履歴を基に危険な変更だけを素早くレビュー
StudioとローカルのどちらをBasic準とするか方向を明確に維持

基本的な動作

Syncワークフロー — StudioツリーがローカルファイルにSyncされた様子

Full Sync: Studioツリーとインスタンスをローカルミラーに初期同期
Incremental Sync: 変更監視でその後の変更分だけ反映
History/Status追跡: どの変更がいつどの方向で反映されたか確認

Syncデータは {projectRoot}/weppy-project-sync/place_{placeId}/explorer 以下に生成されます。WEPPYはさらにプレイス別のsourcemapを {projectRoot}/weppy-project-sync/place_{placeId}/sourcemap.json に記録し、推奨ルート代表ファイルを {projectRoot}/weppy-project-sync/sourcemap.json に保持します。

プロジェクトディレクトリ構造とマルチプレイス

WEPPY Syncはプロジェクトルート以下に weppy-project-sync/ ディレクトリを作成し、プレイスごとに分離されたミラーツリーを保管します。

weppy-project-sync/
├── sourcemap.json             # ルート代表sourcemap（luau-lsp推奨パス）
├── .sync-config.json          # グローバル設定（全プレイスで共有）
├── place_123456/              # プレイス別ディレクトリ
│   ├── explorer/              # ミラーワークスペース（v2ネスト形式）
│   │   ├── Workspace/
│   │   │   ├── _tree.json
│   │   │   ├── Part/
│   │   │   │   └── Part.props.json
│   │   │   └── MyScript/
│   │   │       └── MyScript.server.luau
│   │   └── ServerScriptService/
│   │       └── _tree.json
│   ├── sourcemap.json         # プレイス別sourcemap
│   ├── .sync-meta.json        # プレイスメタデータ
│   └── .sync-index.json       # ハッシュインデックス（version: 2）
└── place_789012/              # 別のプレイス
    └── ...

各プレイスは固有の place_XXXXX/ ディレクトリを持ちます。Proティアでは最大3つのプレイスを同時に同期でき、LRUポリシーによってメモリ内で使用頻度の低いプレイスがevictされます（ディスクデータは保持）。この構造により、同じプロジェクトルートで複数ゲームを行き来しても、同期状態が混在しません。

VSCodeでSyncデータを探索する

WEPPY Roblox Explorer拡張をインストールすると、同期済みインスタンスツリーをRoblox Studioと同じ形でVSCode内で探索できます。ExplorerはここにあるSyncファイルを読み込み、ローカルMCPサーバーが起動中であればリアルタイムのSync状態とdirection情報も追加表示します。

WEPPY Roblox Explorer — 同期済みインスタンスツリーをVSCodeで探索

サービス / インスタンスツリーをRobloxクラスアイコンと共に表示
スクリプトファイルをクリックするとすぐ編集可能
Sync状態バッジで変更・競合を確認

Explorerガイド →

Basic vs Pro

項目	Basic	Pro
同期方向	Studio → Local	双方向
タイプ別Direction	未対応	対応（Scripts / Values / Containers / Data / Services）
タイプ別Apply Mode	未対応	対応（Auto / Manual）
状態・履歴照会API	未対応	対応（`status_current_place`、`history`、`progress`）
`manage_sync`ツール	未対応	対応
マルチプレイスSync	未対応	対応（最大3プレイス）

同期対象とデフォルト除外ルール

デフォルトの同期対象サービス:

Workspace
Lighting
ReplicatedStorage
ServerStorage
ServerScriptService
StarterGui
StarterPlayer
StarterPack
ReplicatedFirst
SoundService
Chat
LocalizationService

デフォルト除外項目:

クラス: Terrain、Camera
セキュリティ上の禁止パス: CoreGui、CorePackages、RobloxScript、RobloxScriptSecurity

DirectionとApply Mode

Direction（タイプ別同期方向）

forward: Studio → Local
reverse: Local → Studio
bidirectional: 双方向

タイプは scripts、values、containers、data、services に分かれて管理されます。

Apply Mode（reverse変更の適用方式）

manual: Studio反映前にユーザーが確認してから適用
auto: 検出した変更を自動適用

ProではタイプごとにDirection/Apply Modeを異なる設定にしてワークフローをきめ細かく制御できます。

`manage_sync` アクションガイド（Pro）

アクション	説明	主なパラメーター
`status_current_place`	現在接続中のプレイスの同期状態を確認	`-`
`history`	変更履歴を照会	`placeId`、`query.limit`、`query.offset`
`directions`	タイプ別Directionを照会	`placeId`
`read_file`	同期済みファイルを読み込む	`placeId`、`instancePath`
`write_file`	同期済みファイルを書き込む	`placeId`、`instancePath`、`content`
`progress`	リアルタイムの進捗・スループットを確認	`placeId`

推奨ワークフロー

1) 安全に始める

まずFull Syncを完了させて現在の状態を基準点にします。
最初は manual 適用で運用して変更リスクを減らします。

2) AIと一緒に変更する

「Syncの状態を確認して、最近の変更履歴を基に危険な変更だけ要約して」
「ServerScriptService 側のスクリプトだけ先にリファクタリングして、変更履歴も残して」

3) 競合が発生したときに解決する

双方向同期中にStudioとローカル両方で変更が検出された場合、以下のような競合解決画面が表示されます。

Local Changes Detected — 競合解決オプション（Studio Priority / Local Priority / Per-File）

Studio Priority: Studio側の状態を基準に上書き
Local Priority: ローカルファイルを基準にStudioに反映
Per-File: ファイルごとにどちらを優先するか個別選択

4) 問題が発生したときに復旧する

history で最近の変更を追跡
必要なファイルを read_file で確認
復旧したい内容を write_file で反映後、Studio状態を再確認

ファイル形式（v2 nested directory）

各Robloxインスタンスは固有のディレクトリに保存され、そのディレクトリ内にメタファイルが配置されます:

explorer/
├── Workspace/
│   ├── _tree.json
│   ├── Part/
│   │   └── Part.props.json
│   ├── MyScript/
│   │   └── MyScript.server.luau
│   └── Coins/
│       └── Coins.value.json

ファイル命名規則:

プロパティ: {Name}/{Name}.props.json
スクリプト: {Name}/{Name}.server.luau / .client.luau / .module.luau
値: {Name}/{Name}.value.json

同名インスタンスはディレクトリに ~N サフィックスを付けて区別します（例: Part~2/Part.props.json）。名前に ~ が含まれる場合は ~~ にエスケープされます（例: Part~2 → Part~~2/）。Odd-Count Tildeルール: 末尾の ~+N でtildeの数が奇数のときのみ衝突サフィックスとして解釈されます。

luau-lsp連携

WEPPY Syncは luau-lsp が必要とするsourcemapファイルを自動生成できるため、別途Rojoプロジェクトを構成しなくてもRoblox認識エディター機能を使用できます。

Full Syncが完了するとWEPPYは以下のファイルを生成します:

プレイスsourcemap: weppy-project-sync/place_<id>/sourcemap.json
ルート代表ファイル: weppy-project-sync/sourcemap.json

luau-lsp がWEPPY sourcemapを読み込むと以下が改善されます:

game.* 自動補完
同期済みスクリプトを基準にした探索
同期済みスクリプト間の require 解析

推奨設定方法

WEPPYが weppy-project-sync/sourcemap.json を作れるよう、Full Syncを一度実行します。
エディターの luau-lsp sourcemap設定が weppy-project-sync/sourcemap.json を指すようにします。
使用しているクライアントで自動Rojo生成をオフにできるなら luau-lsp.sourcemap.autogenerate を false に設定します。

VSCode設定の例:

{
  "luau-lsp.sourcemap.enabled": true,
  "luau-lsp.sourcemap.autogenerate": false,
  "luau-lsp.sourcemap.sourcemapFile": "weppy-project-sync/sourcemap.json"
}

weppy-project-sync/sourcemap.json はプロジェクトの現在の代表プレイスに追従します。特定のプレイスを固定して使いたい場合は、luau-lsp がそのプレイスの weppy-project-sync/place_<id>/sourcemap.json を直接参照するよう設定してください。

双方向Sync