CollabSync

リリースバージョン: ver.0.3.18

CollabSync は、Unity Editor 上で「今だれが何を触っているか」を共有し、競合を減らすための共同編集サポートツールです。オンライン状況、編集対象、ロック、メモ、作業履歴、管理者権限を 1 つの UI で扱えます。

対応している共有方式は次の 3 つです。

Firebase Realtime Database
Supabase
Local JSON

推奨は cloud backend です。 Root Admin が一度だけ接続先を設定し、各メンバーは自分の PC でサインインして使います。

特徴
まず知っておくこと
1. インストール
2. 共有方式の選び方
3. 初回セットアップ
4. ふだんの使い方
5. ロックの考え方
6. 権限
7. Settings / Doctor / Sandbox
8. よくある質問
9. JSON 構造の例
10. トラブルシューティング
リリースノート
ライセンス

特徴

Unity メニュー Tools > CollabSync から使えます。
Firebase / Supabase / Local JSON を同じ UI で切り替えられます。
自動ロックと手動ロックの両方に対応しています。
メモは Markdown 表示、既読、ピン留め、対象への紐付けに対応しています。
Local JSON は各 PC のローカルパス設定で扱い、Git 管理対象の project フォルダ内パスは拒否します。
cloud provider の key は Root Admin 以外には実値を見せません。
User ID ベースで管理するため、表示名を変えても別ユーザー扱いになりません。
Doctor で接続、認証、保存先、共有状態の診断ができます。
Sandbox で複数ユーザーの見え方を Unity 内で確認できます。

まず知っておくこと

迷ったら Firebase Realtime Database か Supabase を使ってください。Local JSON は共有フォルダ運用向けです。
cloud backend では、Root Admin が接続先を保存したあと、各メンバーは自分の email / password または Google でサインインします。
cloud 設定を変えたあとは Apply Cloud Settings を押し、必要ならサインインし直してから Reconnect を押します。
Reconnect は「最後に保存した設定」で再接続します。入力中の値は Apply するまで使われません。
Firebase の State Root を変える場合、Realtime Database rules 側のパスも同じ名前に合わせる必要があります。
Local JSON の JSON Path は project 共通設定ではなく、各 PC のローカル設定です。GitHub で共有されません。
Sandbox は Root Admin 専用です。Sandbox panel の操作は実 backend に書き込まれるため、本番データで試す場合は注意してください。

1. インストール

必要環境

Unity 2021.3 以降
macOS または Windows
cloud backend を使う場合はインターネット接続
Local JSON を使う場合は全員がアクセスできる共有フォルダ

推奨: Package Manager で追加する

Unity で Window > Package Manager を開きます。
左上の + を押します。
Add package from git URL... を選びます。
次の URL を入力します。

https://github.com/IGNORANZ-PROJECT/CollabSync.git

追加後、再コンパイルが終わるのを待ちます。
Tools > CollabSync が表示されることを確認します。

代替: 手動で配置する

Editor と Runtime を Unity project 内へ置きます。

Assets/
└─ IGNORANZ-PROJECT/
   └─ CollabSync/
      ├─ Editor/
      └─ Runtime/

注意:

Git URL 導入と手動配置を同時に行わないでください。
CollabSync-main のような展開フォルダ名でも、中にある Editor と Runtime を使えば問題ありません。

`Tools` メニューの場所

macOS: 画面上部メニューバーの Tools > CollabSync
Windows: Unity ウィンドウ上部の Tools > CollabSync

埋め込み package を更新したい場合

Unity project の Packages/com.ignoranz.collabsync へ repo 内容を埋め込む script も入っています。

./scripts/embed-collabsync-into-unity-project.sh <UnityProjectPath>

この script は Packages/manifest.json の dependency を file:com.ignoranz.collabsync に切り替えます。

2. 共有方式の選び方

共有方式の比較

方式	向いている用途	設定者	各メンバーが行うこと
`Firebase Realtime Database`	まず動かしたい、構成を単純にしたい	Root Admin	サインイン
`Supabase`	SQL / RLS を使いたい	Root Admin	サインイン
`Local JSON`	OneDrive / NAS / 共有フォルダ運用	各メンバー	同じ共有ファイルを指すローカルパス設定

2.1 Firebase Realtime Database

必要な設定:

Database URL
Web API Key
State Root

推奨 rules 例:

{
  "rules": {
    "collabsync": {
      "$project": {
        ".read": "auth != null",
        ".write": "auth != null"
      }
    }
  }
}

重要:

上の rules は State Root = collabsync 前提です。
State Root を holo_board に変えるなら、rules 側の collabsync も holo_board に変えてください。
認証は Email/Password または Google を有効にしてください。

2.2 Supabase

必要な設定:

Supabase URL
Anon Key
Table

最低限必要な table 例:

create table if not exists public.collabsync_state (
  project_id text primary key,
  version bigint not null default 1,
  updated_at bigint not null default 0,
  payload jsonb not null default '{}'::jsonb
);

RLS 例:

alter table public.collabsync_state enable row level security;

create policy "collabsync read"
on public.collabsync_state
for select
to authenticated
using (true);

create policy "collabsync insert"
on public.collabsync_state
for insert
to authenticated
with check (true);

create policy "collabsync update"
on public.collabsync_state
for update
to authenticated
using (true)
with check (true);

2.3 Local JSON

Local JSON は共有フォルダを使う方式です。

重要:

URL ではなく、各 PC から見える実ファイルパスを指定します。
全員が「同じ内容に同期される同じ共有ファイル」を指す必要があります。
JSON Path は各 PC のローカル設定なので、CollabSync の更新や GitHub の commit に入りません。
Assets/ Packages/ ProjectSettings/ など Git 管理対象の project 内パスは拒否されます。

保存の仕組み:

.json の横に *.collabsync-store/ を作り、record 単位で分散保存します。
1 ファイル丸ごとの上書きを避けるため、OneDrive のような同期ストレージでも壊れにくくしています。
Encrypt shared state file を ON にすると、shared state は保護形式で保存されます。

2.4 Firebase 設定手順

Firebase Console で project を作成します。
Realtime Database を作成します。
Authentication で Email/Password を有効にします。
必要なら Google provider も有効にします。
Database URL と Web API Key を控えます。
Unity で Tools > CollabSync > Settings を開きます。
Storage Provider を Firebase Realtime Database にします。
Database URL、Web API Key、State Root を入力します。
Apply Cloud Settings を押します。
Reconnect を押します。
Run Doctor で接続確認します。

2.5 Supabase 設定手順

Supabase project を作成します。
Authentication で Email を有効にします。
必要なら Google provider も有効にします。
Project URL と anon public key を控えます。
table と RLS を作成します。
Unity で Tools > CollabSync > Settings を開きます。
Storage Provider を Supabase にします。
Supabase URL、Anon Key、Table を入力します。
Apply Cloud Settings を押します。
Reconnect を押します。
Run Doctor で接続確認します。

2.6 Google sign-in を使う場合

Root Admin が Google OAuth Client ID を設定します。

重要:

Desktop App 用の OAuth Client ID を使ってください。
sign-in 時は system browser が開き、ローカル loopback callback で Unity に戻ります。
Google OAuth Client ID を保存したら、Apply Cloud Settings と Reconnect を実行してください。

3. 初回セットアップ

3.1 Root Admin になる人

最初に有効な shared state へ書き込んだユーザーが Root Admin になります。

手順:

Tools > CollabSync を開きます。
Settings を開きます。
Your Name を入力します。
Storage Provider を選びます。
provider 設定を入力して Apply Cloud Settings または Apply Storage Settings を押します。
cloud を使う場合は Sign In します。
Reconnect を押します。
Run Doctor で正常を確認します。

3.2 すでにある共有へ参加する人

cloud backend の場合:

Tools > CollabSync を開きます。
Your Name を入力します。
Root Admin が設定済みの provider が表示されていることを確認します。
自分の email / password または Google でサインインします。
必要なら Reconnect を押します。
Run Doctor で接続確認します。

3.3 Local JSON を使う場合

Storage Provider を Local JSON にします。
Choose... または New... で共有 JSON を選びます。
Resolved Local JSON が意図した場所か確認します。
必要なら Encrypt shared state file を設定します。
Run Doctor で接続確認します。

3.4 User ID について

CollabSync は表示名ではなく User ID でユーザーを識別します。

Firebase / Supabase では provider 側の UID が使われます。
Local JSON ではこの PC に固定保存された ID が使われます。
User ID は参照専用です。CollabSync から直接変更できません。
表示名を変えても別ユーザーにはなりません。
Admin 追加やユーザー削除は User ID ベースで行われます。

4. ふだんの使い方

メイン UI は Overview Details Memos Settings の 4 タブです。

4.1 Overview

最初に見るタブです。

Online 現在のオンライン人数と、編集中メンバーの要約を表示します。
Unread / Pinned Memos 未読メモとピン留めメモを表示します。
Active Locks 現在のロックを表示します。必要なら Request Unlock や Unlock を使います。

一覧はデフォルトで絞って表示されます。件数が多い時だけ Show all で展開します。

4.2 Details

詳しく確認したい時のタブです。

Selection Status 現在選択中の Scene / Prefab / Asset / GameObject が、だれの編集やロックの影響を受けているかを表示します。
Users オンライン状態、現在の作業、ロック数、作業履歴、User ID を確認できます。
Lock Manager All / Mine / Blocking Me の絞り込み、検索、Unlock All Mine、管理者による Force Unlock を使えます。

4.3 Memos

チームメモ用のタブです。

できること:

新規メモ追加
現在の選択への紐付け
手動の URL / asset path 紐付け
Markdown 表示
ピン留め
既読
検索
Unread only
Pinned only
Related to selection

通常削除は投稿者本人のみです。管理者は Force Delete を使えます。

4.4 Settings

接続設定、認証、管理機能をまとめたタブです。

重要な流れ:

設定を変える
Apply Cloud Settings または Apply Storage Settings
必要ならサインイン
Reconnect

5. ロックの考え方

CollabSync には 自動ロック と 手動ロック があります。

5.1 自動ロック

編集中の対象を検知し、必要最小限の範囲でロックします。

基本方針:

ふつうの Inspector 編集は object 単位を優先します。
Scene 全体設定の変更は scene 単位になることがあります。
Script を実際に編集した時は script 側も対象になります。
Play mode に入っただけでは auto-lock しません。
不要なロックが残りにくいよう、dirty 状態と heartbeat を見て管理します。

5.2 手動ロック

明示的にロックしたい時は次を使います。

Tools > CollabSync
Project ウィンドウ右クリックの CollabSync
GameObject > CollabSync

5.3 ロック表示

overlay 表示:

L 他ユーザーのロック
M 自分のロック
! 他ユーザーが編集中

5.4 スクリプト保護

他ユーザーがロックしている .cs は、自分の環境で読み取り専用に寄せます。誤編集の事故を減らすための保護です。

5.5 Git-aware Locks

Keep retained locks until merged を ON にすると、手動ロックは解除時にすぐ消えず、保護ブランチに対象 commit が入るまで Retained として残ることがあります。

向いている場面:

GitHub 中心で運用している
branch をまたいだ競合を避けたい
main 反映前にロックを消したくない

6. 権限

通常ユーザー

自分のロック解除
メモ投稿
自分のメモ削除
他ユーザーへの Request Unlock

Admin

通常ユーザーに加えて:

他ユーザーの Force Unlock
他ユーザーの Force Delete
Global Work History の切り替え

Root Admin

Admin に加えて:

Admin の追加 / 削除
ユーザー削除
削除済みユーザー一覧の閲覧
ユーザー復活
provider / endpoint など shared 設定の変更
Sandbox の有効化 / 解除

ユーザー削除

Delete User は単に一覧から消すだけではありません。

プレゼンス削除
ロック削除
Admin 権限剥奪
その User ID の再書き込みをブロック

あとで Root Admin が Deleted Users から復活できます。

7. Settings / Doctor / Sandbox

7.1 Settings で重要な項目

Your Name
Your User ID
Storage Provider
provider ごとの接続設定
Authentication
Reconnect
Notifications
Git-aware Locks

7.2 Doctor

Run Doctor は次の確認に使います。

provider 設定が正しいか
sign-in が有効か
Local JSON の path が妥当か
読み書きができるか
共有状態の基本構造が壊れていないか
現在の backend が正常に配信できているか

使いどころ:

初回セットアップ直後
provider を変えた直後
Local JSON の path を変えた直後
他メンバーだけ接続できない時
何かおかしいが原因が分からない時

7.3 Sandbox

Sandbox は Root Admin 専用です。

できること:

Enable Sandbox
Open Sandbox Panel
Disable Sandbox

重要:

各 panel は別ユーザーとして動作します。
cloud backend では panel ごとに別 session を持てます。
panel からのメモ、ロック、解除依頼は実 backend に書き込まれます。
UI 確認だけでなく、実運用に近い挙動確認に使えます。

8. よくある質問

Q. まずどの共有方式を選ぶべき？

迷ったら Firebase Realtime Database か Supabase です。共有フォルダ運用の事情がある時だけ Local JSON を選ぶのが無難です。

Q. `Reconnect` はいつ押す？

provider 設定を保存したあとです。 Apply は保存、Reconnect はその保存済み設定へ切り替える操作です。

Q. `State Root` を変えたら Firebase でエラーになる

rules 側の path が一致していない可能性が高いです。 State Root を holo_board にしたなら、rules 側も holo_board/$project を許可してください。

Q. `Local JSON` の path は GitHub で共有される？

されません。 JSON Path は各 PC のローカル設定です。

Q. `Assets/` や `ProjectSettings/` に Local JSON を置ける？

置けません。 Git 管理対象に入るため拒否されます。

Q. 表示名を変えると別ユーザーになる？

なりません。内部では User ID で判定しています。

Q. 他人のロックを解除できない

通常仕様です。自分のロックだけ解除できます。強制解除は Admin 以上だけです。

Q. Sandbox で試した操作は本番データに入る？

入ります。 Sandbox は表示だけの mock ではありません。必要なら別の project / backend で試してください。

9. JSON 構造の例

これは CollabSync が論理的に扱う shared state の例です。

Firebase / Supabase では payload として保存されます。
Local JSON では保護形式や store 展開前の論理構造として対応します。

{
  "updatedAt": 1730000000000,
  "presences": [
    {
      "userId": "a3d9...",
      "user": "Alice",
      "assetPath": "Assets/Scenes/Main.unity",
      "context": "Scene",
      "heartbeat": 1730000000000
    }
  ],
  "locks": [
    {
      "assetPath": "Assets/Scripts/",
      "ownerId": "b1f2...",
      "owner": "Bob",
      "reason": "context-menu",
      "createdAt": 1730000000000,
      "ttlMs": 0
    }
  ],
  "adminUserIds": ["a3d9..."],
  "adminUsers": ["Alice"],
  "blockedUserIds": ["c8e4..."],
  "blockedUsers": ["Charlie"],
  "rootAdminUserId": "a3d9...",
  "rootAdminUser": "Alice",
  "workHistoryMode": "enabled",
  "memos": [
    {
      "id": "a1b2c3",
      "text": "新しいシーン構成を確認",
      "authorId": "a3d9...",
      "author": "Alice",
      "assetPath": "Assets/Scenes/Main.unity",
      "createdAt": 1730000000000,
      "pinned": true,
      "readByUserIds": ["b1f2..."],
      "readByUsers": ["Bob"]
    }
  ]
}

10. トラブルシューティング

症状	対処
Sign In したのに接続できない	provider 設定を保存済みか、`Reconnect` を押したか確認してください
Firebase が `401` / permission error になる	`State Root` と rules の path が一致しているか確認してください
Supabase に接続できない	`URL` `Anon Key` `Table` と RLS を確認してください
Local JSON が更新されない	`Resolved Local JSON` と共有フォルダの権限を確認してください
Local JSON の path が拒否される	Git 管理対象の project 内パスを選んでいないか確認してください
Script が read-only のまま	他ユーザーの lock がまだ残っていないか確認してください
管理機能が出ない	自分が Admin / Root Admin か確認してください
Sandbox でユーザーが増えない	Root Admin で `Enable Sandbox` したか確認してください
UI が重い	`Overview` / `Details` の一覧を開きすぎていないか確認し、不要な panel を閉じてください

リリースノート

ver.0.3.18

Hierarchy / Project overlay を見直し、見た目の変化がない heartbeat 更新だけでは repaint しないように軽量化
CollabSyncWindow の derived cache 再計算頻度を抑え、memo Markdown cache も memo 内容が変わった時だけ破棄するように改善
memo 既読表示のユーザー名解決をキャッシュベースに変更し、memo 一覧の表示負荷を削減
Sandbox の local overlay 更新は対象や identity が変わった時だけ再配信し、heartbeat だけで UI 全体を揺らしにくいように調整
Sandbox heartbeat 間隔も見直し、複数 panel 使用時の定期通信負荷を軽減

ver.0.3.17

README を全面的に整理し、導入、設定、運用、トラブルシューティングを今の実装に合わせて再構成
cloud 設定の Apply と Reconnect の流れを README に明記
Firebase の State Root と rules の一致が必要な点を README に追記
CollabSyncWindow の snapshot refresh を多重実行しにくくし、メモ Markdown 描画キャッシュと一覧表示制限で軽量化
UI を見直し、オンライン / ユーザー / ロック / Sandbox 一覧を既定で見やすく整理
Sandbox panel ごとの cloud session 分離を強化し、main session を上書きしにくいように改善

ver.0.3.4

Doctor を現行仕様に合わせて更新
Sandbox を Root Admin 専用で追加
複数の一時ユーザーパネルで UI と競合表示を確認できるように改善

ver.0.3.3

Local JSON を通常 provider として整理
JSON Path を PC ごとのローカル設定へ移動
cloud key を non-root に見せないよう改善

ver.0.3.0

Firebase Realtime Database と Supabase を cloud backend として追加
Root Admin が shared config を設定し、各メンバーは個別サインインする方式へ変更

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
Editor		Editor
Runtime		Runtime
.gitignore		.gitignore
Editor.meta		Editor.meta
LICENSE		LICENSE
LICENSE.meta		LICENSE.meta
README.md		README.md
README.md.meta		README.md.meta
Runtime.meta		Runtime.meta
package.json		package.json
package.json.meta		package.json.meta

Folders and files

Latest commit

History

Repository files navigation

CollabSync

目次

特徴

まず知っておくこと

1. インストール

必要環境

推奨: Package Manager で追加する

代替: 手動で配置する

Tools メニューの場所

埋め込み package を更新したい場合

2. 共有方式の選び方

共有方式の比較

2.1 Firebase Realtime Database

2.2 Supabase

2.3 Local JSON

2.4 Firebase 設定手順

2.5 Supabase 設定手順

2.6 Google sign-in を使う場合

3. 初回セットアップ

3.1 Root Admin になる人

3.2 すでにある共有へ参加する人

3.3 Local JSON を使う場合

3.4 User ID について

4. ふだんの使い方

4.1 Overview

4.2 Details

4.3 Memos

4.4 Settings

5. ロックの考え方

5.1 自動ロック

5.2 手動ロック

5.3 ロック表示

5.4 スクリプト保護

5.5 Git-aware Locks

6. 権限

通常ユーザー

Admin

Root Admin

ユーザー削除

7. Settings / Doctor / Sandbox

7.1 Settings で重要な項目

7.2 Doctor

7.3 Sandbox

8. よくある質問

Q. まずどの共有方式を選ぶべき？

Q. Reconnect はいつ押す？

Q. State Root を変えたら Firebase でエラーになる

Q. Local JSON の path は GitHub で共有される？

Q. Assets/ や ProjectSettings/ に Local JSON を置ける？

Q. 表示名を変えると別ユーザーになる？

Q. 他人のロックを解除できない

Q. Sandbox で試した操作は本番データに入る？

9. JSON 構造の例

10. トラブルシューティング

リリースノート

ver.0.3.18

ver.0.3.17

ver.0.3.4

ver.0.3.3

ver.0.3.0

ライセンス

About

Resources

License

Licenses found

Uh oh!

Stars

Watchers

Forks

Releases 21

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`Tools` メニューの場所

Q. `Reconnect` はいつ押す？

Q. `State Root` を変えたら Firebase でエラーになる

Q. `Local JSON` の path は GitHub で共有される？

Q. `Assets/` や `ProjectSettings/` に Local JSON を置ける？

Packages