どうも、めかぶです。

VRChat用のアバタープロジェクトは、衣装やギミックを追加していくうちにファイルが増え、「どこに何を置いたのか分からない」「変更前の状態を残しておけばよかった」といったことが起こりがちです。

そこで、アバターごとの作業領域を用意し、Gitによる変更の記録をUnity上から行えるEditor拡張「VRC Git Manager」を作りました。

この記事では、VRC Git Manager 0.1.0の導入方法と、アバター改変やUnityPackageを管理する基本的な流れを紹介します。

VRC Git Managerとは⌗

VRC Git Managerは、VRChat用のアバタープロジェクトをローカルのGitとGit LFSで管理するためのUnity Editor拡張です。

Gitは、ファイルの変更内容を「コミット」という単位で記録する仕組みです。Git LFSは、画像、3Dモデル、UnityのSceneなど、通常のGitでは扱いにくい大きなバイナリファイルを管理するための拡張機能です。

VRC Git Managerでは、コマンドを直接入力しなくても、次の操作をUnity上から行えます。

  • GitとGit LFSを初期化し、最初のコミットを作成する
  • Assets/_Project/AvatarsとAssets/Vendorだけを管理対象にする
  • アバターごとの作業用フォルダーと初期Sceneを作成する
  • 選択したアバターの変更だけを確認してコミットする
  • UnityPackageをAssets/Vendorへインポートし、Vendorだけをコミットする
  • 直前に行った管理対象のUnityPackageインポートを取り消す
  • 管理対象のアバターSceneをHierarchyから切り替える
  • Gitの履歴とGit LFSのデータを検証済みZIPとしてバックアップする

このツールは、Unityプロジェクト全体をGitへ保存するものではありません。アバターの改変データと、インポートしたアセットを対象ごとに分けて記録することを目的としています。

Gitを知らなくても使えるようにした理由⌗

Gitは便利ですが、最初からコマンドや専門用語をすべて覚えようとすると、アバター改変よりGitの操作に時間を取られてしまいます。

VRC Git Managerでは、普段の操作を次の3つに絞っています。

  • 作業ツリー：最後に記録した状態と比べて、現在のファイルに変更があるかを示す
  • 変更内容を確認：これから記録するファイルの一覧を見る
  • コミット：現在の変更へ名前を付け、あとから区別できる保存ポイントとして記録する

画面に「作業ツリー 変更なし」と表示されていれば、管理対象の変更はすべてコミット済みです。「変更あり」になったら、アバターまたはVendorの変更内容を確認し、作業の区切りでコミットします。

flowchart LR
    A["作業前<br/>変更なし"] --> B["衣装や設定を変更<br/>変更あり"]
    B --> C["変更内容を確認"]
    C --> D["コミット<br/>保存ポイントを作成"]
    D --> E["次の作業へ<br/>変更なし"]

実際のGitには、記録するファイルを選ぶ「ステージ」という操作があります。VRC Git Managerは、選択したアバターのフォルダー、またはVendorのフォルダーだけを対象にすることで、この選別を肩代わりします。

そのため、最初は「作業前に変更なしを確認する」「ひとつの作業が終わったら内容を確認してコミットする」という使い方だけでも、ざっくりとした履歴を残せます。

なお、コミットは通常のファイル保存を置き換えるものではありません。UnityでSceneやPrefabを保存したうえで、そのファイルの状態をGitへ記録する操作です。

動作確認環境⌗

  • Windows 11 x64 25H2
  • Unity 2022.3.22f1
  • VRChat SDK v3.10.4
  • ALCOM 1.1.8
  • VRC Git Manager 0.1.0

VRC Git Manager自体は、VRChat SDKのランタイムAPIには依存していません。

UnityPackageのインポート先を固定する機能はUnity Editor内部の仕組みを利用しており、Unity 2022.3.22f1で確認しています。別のUnityバージョンでは警告が表示されたり、必要な機能を確認できない場合は安全のためインポート機能が無効になったりすることがあります。

導入前にGitとGit LFSを準備する⌗

導入前に、次のものを用意します。

インストール後、PowerShellやコマンドプロンプトで次のコマンドを実行します。

git --version
git lfs version

どちらもバージョン情報が表示されれば準備完了です。VRC Git Managerの画面にも診断結果が表示されるため、導入後に問題がある場合はそちらから確認できます。

VRC Git Managerを導入する⌗

VPMリポジトリを追加する⌗

VRC Git Manager 0.1.0は、MekabuのVPMリポジトリから導入できます。

VCCまたはALCOMで、次のリポジトリURLを追加します。

https://vpm-repo.mekabu.io/index.json

リポジトリを追加すると、パッケージ一覧に「VRC Git Manager」が表示されます。Gitで管理したいアバタープロジェクトを選び、VRC Git Managerを追加してください。

VPMを使わない場合は、GitHubのReleaseページからUnityPackageも入手できます。

UnityからVRC Git Managerを開く⌗

導入後は、Sceneビュー右上に表示されるVRC Gitボタンからウィンドウを開けます。

ボタンが見つからない場合は、SceneビューのOverlayメニューで表示状態を確認してください。予備の起動方法として、Unity上部のMekabu > VRC Git Managerからも開けます。

Gitを初期化する⌗

VRC Git Managerを開いたら、最初に「初期設定」を開きます。初期コミットメッセージは、既定のInitial commitのままで問題ありません。

Gitを初期化して最初のコミットを作成を押すと、次の処理がまとめて行われます。

  1. Assets/_Project/AvatarsとAssets/Vendorを作成する
  2. プロジェクト内でGitとGit LFSを初期化する
  3. .gitignore、.gitattributes、push拒否用のhookを用意する
  4. 管理対象のファイルを最初のコミットとして記録する

初期化時に作成される基本構成は、次のようになります。

Unityプロジェクト/
├── .gitattributes
├── .gitignore
├── .githooks/
│   └── pre-push
└── Assets/
    ├── _Project/
    │   └── Avatars/
    └── Vendor/

Unityが使用する.metaファイルもコミット対象に含まれますが、普段ユーザーが意識する必要はないため、VRC Git Managerの変更一覧では非表示になります。

管理対象は、Gitの設定ファイルとAssets/_Project、Assets/Vendorに限定されています。Packages、ProjectSettings、そのほかのAssetsは記録されません。Unityプロジェクト全体を復元できる構成ではない点に注意してください。

初期化が成功したら、画面上部の状態が「作業ツリー 変更なし」になっていることを確認します。GitやGit LFSなどに問題がなければ、診断の正常な項目は折り畳まれます。

アバターごとの作業領域を作成する⌗

「アバター・Scene管理（必要なとき）」を開き、「アバターを追加」でアバター名を入力します。ここでは例としてManukaを入力し、アバターを追加（初期Scene付き）を押します。

次のフォルダーと、Main Camera・Directional Lightを含む初期Sceneが作成されます。

Assets/_Project/Avatars/Manuka/
├── Animations/
├── Expressions/
├── Materials/
├── Prefabs/
├── Scenes/
│   └── Manuka.unity
└── Textures/

作成後はScene切り替えが自動的に有効になり、管理対象のSceneがHierarchyへ追加されます。

同じアバターで着せ替え用などのSceneを分けたい場合は、「Sceneを追加・管理」でScene名を入力し、Sceneを追加を押します。追加したSceneも同じアバターのコミット対象です。

HierarchyでアバターSceneを切り替えるを有効にしている間は、Hierarchyから管理対象のSceneを開けます。別のアバターSceneへ切り替えたときは、ほかの管理対象Sceneだけが閉じられ、管理対象外のSceneはそのまま残ります。未保存の変更がある場合は、Unity標準の保存確認が表示されます。

共有用の領域が必要な場合、Shared専用の特別な仕組みはありません。アバター名にSharedと入力して通常の対象として作成すれば、ほかのアバターと同じ方法でコミットできます。

フォルダー構成をどう使い分けるか⌗

VRC Git Managerでは、_ProjectとVendorの役割を分けることが大切です。

flowchart TB
    Assets["Assets"] --> Project["_Project<br/>自分の改変を置く場所"]
    Assets --> Vendor["Vendor<br/>外部パッケージを置く場所"]
    Project --> Avatars["Avatars"]
    Avatars --> A["Manuka<br/>マヌカ用の変更"]
    Avatars --> B["Shinra<br/>森羅用の変更"]
    Avatars --> S["Shared<br/>必要な場合だけ作成"]
    A --> Scenes["Scenes"]
    A --> Prefabs["Prefabs"]
    A --> Materials["Materialsなど"]
    Vendor --> PackageA["アバター本体"]
    Vendor --> PackageB["衣装・ツール・シェーダー"]

役割を簡単にまとめると、次のようになります。

場所役割主に置くもの
Assets/Vendor外部から導入したものをまとめるアバター本体、衣装、ツール、シェーダーなどのUnityPackage
Assets/_Project/Avatars/<アバター名>自分が行った改変をアバター単位でまとめる作業用Prefab、Scene、調整したMaterial、Texture、Animationなど

たとえばマヌカ用の衣装を追加する場合、衣装のUnityPackageはAssets/Vendorへインポートします。そのあと、マヌカ用のSceneやPrefab、アバター専用に調整したMaterialなどはAssets/_Project/Avatars/Manukaへ置きます。

こうして分けておくと、「購入したパッケージを追加した記録」と「マヌカへ衣装を着せた記録」を別々のコミットにできます。どちらの作業で問題が起きたのかも判断しやすくなります。

アバター内の各フォルダー⌗

アバター追加時に作られるフォルダーは、次のような用途を想定しています。

  • Scenes：そのアバターを改変・確認するUnity Scene
  • Prefabs：作業用のアバターPrefabやPrefab Variant
  • Materials：色やシェーダー設定を調整したMaterial
  • Textures：自分で編集したTextureやマスク画像
  • Animations：AnimationClipやAnimator Controllerなど
  • Expressions：Expressions MenuやExpression Parametersなど、表情・メニュー関連のアセット

これは整理しやすくするためのテンプレートであり、すべてのフォルダーを必ず使う必要はありません。アバター名のフォルダー内に置かれたファイルは、サブフォルダーにかかわらず、そのアバターのコミット対象になります。

外部パッケージのファイルをアバター専用に編集したい場合は、可能であればMaterialなどを対象アバターのフォルダーへ複製してから調整すると、Vendorの元データと自分の変更を区別しやすくなります。Vendor内のファイルを直接編集した場合、その変更はアバターではなくVendor側の変更として扱われます。

ただし、Prefabやツールによっては複製ではなく元アセットの参照が必要なこともあります。無理にファイルを移動せず、利用しているアセットの説明に沿って配置してください。

アバターの変更をコミットする⌗

Gitでは、ある時点の変更内容を履歴として保存する操作を「コミット」と呼びます。

アバターを追加した直後や、衣装・ギミックの設定がひと区切りついたときは、次の手順でコミットします。

  1. 「アバターの変更をコミット」で対象のアバターを選ぶ
  2. 変更内容を確認を押す
  3. 表示されたファイルが今回の作業内容と合っているか確認する
  4. コミットメッセージを入力する
  5. このアバターの変更をコミットを押す

コミットされるのは、選択したAssets/_Project/Avatars/<アバター名>内の変更だけです。別のアバターやVendorの変更は含まれません。

コミットメッセージには、次のように作業内容が分かる言葉を付けておくと、あとから履歴を探しやすくなります。

マヌカに新しい衣装を追加

.metaファイルは変更一覧に表示されませんが、対応するアセットと一緒にコミットされます。

また、アバターがVendor内のアセットを参照している場合は警告が表示されます。アバターのコミットにはVendorの変更が含まれないため、必要であれば後述の手順でVendorも別にコミットしてください。

UnityPackageをVendorへインポートする⌗

購入した衣装やツールなどのUnityPackageは、「UnityPackage・Vendor」からインポートできます。

UnityPackageを選んでインポートを押し、UnityPackageを選択します。標準のインポート画面が開きますが、新しく追加するAssets配下の項目はAssets/Vendorへ配置されます。

すでに同じGUIDのアセットがVendor外に存在する場合、その項目はVendor外のファイルを上書きせず除外されます。PackagesやProjectSettingsなど、Assets外を対象にした項目も除外されます。通常どおり、Unityのインポート一覧を確認してからImportを実行してください。

インポートが終わったら、次の手順でVendorだけをコミットします。

  1. Vendorの変更内容を確認を押す
  2. 表示された追加・更新・削除を確認する
  3. vendor: import パッケージ名などのコミットメッセージを入力する
  4. Vendorの変更をコミットを押す

この操作ではAssets/Vendorの変更だけがコミットされ、アバター側の変更は含まれません。

直前のインポートを取り消す⌗

VRC Git Managerから行った直前のUnityPackageインポートは、直前のインポートを取り消すから取り消せます。

新しく追加されたアセットは削除され、既存のVendorアセットが上書きされていた場合はインポート前の状態へ復元されます。インポート後に対象ファイルを変更していた場合は、変更も含めて削除または復元するか確認が表示されます。

取り消し後もVendorには削除や復元の差分が残るため、Vendorの変更内容を確認で内容を確認し、問題がなければ通常どおりコミットします。

取り消せるのは、VRC Git Managerから行った直前の完了済みインポート1件です。別のツールが画面を介さず実行したインポートは、配置先の変更や取り消しを安全に記録できません。また、対象アセットをVendor外へ移動した場合は、取り消す前にVendorへ戻す必要があります。

普段の作業の流れ⌗

僕は、アバターを改変するときに次の流れで使う想定です。

flowchart TD
    Start["作業を始める"] --> Clean{"作業ツリーは<br/>変更なしか"}
    Clean -- "変更あり" --> Previous["前回の変更を確認し<br/>先にコミットする"]
    Previous --> Clean
    Clean -- "変更なし" --> Import{"UnityPackageを<br/>追加するか"}
    Import -- "追加する" --> Vendor["Vendorへインポート<br/>変更確認・コミット"]
    Vendor --> Modify
    Import -- "追加しない" --> Modify["目的をひとつ決めて<br/>アバターを改変"]
    Modify --> Test["Unityへ保存し<br/>動作を確認"]
    Test --> Avatar["アバターの変更を確認<br/>コミット"]
    Avatar --> Finish["作業ツリー 変更なし<br/>必要ならバックアップ"]

1. 作業前に「変更なし」を確認する⌗

作業を始める前に、画面上部の「作業ツリー」を確認します。

「変更なし」であれば、前回までの作業はすべてコミット済みです。「変更あり」のまま次の改変を始めると、前回と今回の変更が混ざってしまいます。残っている変更がある場合は、対象アバターまたはVendorの「変更内容を確認」を押し、先に記録しておきます。

変更が意図したものか分からない場合は、無理にコミットや削除をせず、どのファイルが変わっているか確認してください。

2. UnityPackageは先にVendorへ記録する⌗

衣装などのUnityPackageを使う作業では、先にパッケージをVendorへインポートし、Vendorだけをコミットします。

たとえばManuka_Dress.unitypackageを追加した場合、コミットメッセージは次のようにします。

vendor: import Manuka Dress

この時点では、まだアバターへ衣装を着せる作業は含めません。「素材をプロジェクトへ追加した」という保存ポイントを先に作るイメージです。

3. アバターをひとつの目的に絞って改変する⌗

Vendorのコミットが終わったら、対象アバターのSceneを開き、衣装の設定を行います。

このとき、「衣装を着せる」「色を調整する」「メニューへ切り替えを追加する」など、できるだけひとつの目的ごとに作業を区切ると履歴が分かりやすくなります。すべてを一度に終わらせる必要はありません。

たとえば次のように分けられます。

作業の区切りコミットメッセージの例
衣装を着せて動作確認したマヌカに新しい衣装を追加
Materialの色だけを調整した衣装の色を青に調整
Expressions Menuへ切り替えを追加した衣装切り替えメニューを追加
PhysBoneの揺れ方を調整した髪のPhysBone設定を調整

「修正」「更新」のような短いメッセージでもコミットはできますが、何をしたか分かる言葉にしておくと、あとから問題が起きた時点を探しやすくなります。

4. 動作確認してからアバターをコミットする⌗

改変が終わったら、Unity上でConsoleエラーや参照切れがないか確認します。必要に応じてVRChat SDKのBuild & Testなども行います。

問題がなければ、VRC Git Managerで対象アバターを選択し、変更内容を確認を押します。表示された内容が今回の作業と合っていることを確認してから、コミットメッセージを入力し、このアバターの変更をコミットを押します。

別のアバターやVendorの変更は含まれないため、複数のアバターを同じUnityプロジェクトで管理していても、ひとつずつ記録できます。

5. 作業の最後にもう一度確認する⌗

コミット後に画面上部が「作業ツリー 変更なし」へ戻れば、その作業はひと区切りです。大きな改変が完了したときや、PCのメンテナンス前などは、検証済みのオフラインバックアップも作成します。

VRC Git Manager 0.1.0には、コミット履歴の表示や過去の状態へ戻す機能はありません。コミットによって履歴自体はGitへ残りますが、それを確認・復元する場合はGitのコマンドやほかのGitクライアントを使います。未コミットの変更を失う操作もあるため、内容を理解してから行ってください。

オフラインバックアップを作成する⌗

コミットは同じストレージ内に記録されるため、PCやドライブの故障に備えるには別の場所へのバックアップも必要です。

作業ツリーが「変更なし」になっていることを確認し、「オフラインバックアップ（必要なとき）」を開きます。保存先を選んで検証済みZIPを作成を押し、Unityプロジェクトの外にある保存先を選びます。

バックアップが成功すると、次の2ファイルが作成されます。

プロジェクト名_git-backup_20260901-180000.zip
プロジェクト名_git-backup_20260901-180000.zip.sha256

ZIPには、Gitで追跡しているファイル、コミット履歴、.git/lfs/objects内のGit LFSデータが含まれます。作成前とZIP展開後の両方でGitとGit LFSの整合性が確認され、隣に作成される.sha256ファイルでZIP自体の破損も確認できます。

ただし、このZIPもUnityプロジェクト全体のバックアップではありません。Gitの管理対象外であるPackagesやProjectSettingsなどは含まれないため、元のUnityプロジェクトや導入済みパッケージの情報は別の方法でも残しておいてください。

リモートへ送信しない設計について⌗

VRC Git Managerは、購入したアバターや衣装などを誤って外部へ送信しないよう、ローカルでの運用を前提にしています。

リモートリポジトリ、Git LFSの接続先、submoduleのURLが設定されている間は、VRC Git Managerからコミットやバックアップを行えません。また、初期化時にpushを拒否するGit hookも用意します。GitHubなどのリモートを追加してpushする機能はありません。

ただし、これは操作ミスを減らすための仕組みであり、強制的なセキュリティ境界ではありません。リポジトリの所有者がGitの設定やhookを変更したり、別のアプリケーションでファイルをアップロードしたりすることまでは防げません。

外部への送信を確実に制限する必要がある場合は、OSやネットワーク側の管理も併用してください。

使用時の注意点⌗

VRC Git Managerを使う際は、次の点に注意してください。

  • コミットしていない変更はGitの履歴に残らない
  • Gitの管理対象はAssets/_ProjectとAssets/Vendorが中心で、Unityプロジェクト全体ではない
  • .metaファイルは画面に表示されないが、コミットには含まれる
  • Gitの履歴表示や、過去の状態へ戻す操作はツールに含まれない
  • UnityPackageの配置先固定と取り消しは、VRC Git Managerから開いた対話式インポートだけが対象になる
  • UnityPackageのインポート先固定はUnity 2022.3.22f1で確認している
  • リモートを禁止する仕組みは誤操作防止のためのもので、回避不可能な制限ではない
  • 重要なデータは、検証済みZIPに加えて別のストレージにも複製する

既存のGitリポジトリへ導入する場合は、すでにある.gitignore、.gitattributes、Git hookとの関係も確認してください。VRC Git Managerは自身が管理する範囲を追記しますが、既存の運用へ影響しないことを確認してから使うことをおすすめします。

まとめ⌗

VRC Git Managerを使うと、VRChat用アバタープロジェクトの作業場所を揃えながら、アバターとVendorの変更を分けてGitへ記録できます。

特に、複数のアバターやSceneを同じUnityプロジェクトで扱う場合でも、対象ごとに変更を確認してコミットできる点を重視して作りました。Gitのすべての操作をUnityへ持ち込むのではなく、アバター改変でよく使う範囲を分かりやすく扱うためのツールです。

VRC Git Manager 0.1.0はMIT Licenseで公開しています。ダウンロード、更新内容、ソースコードについては、VRC Git ManagerのGitHubリポジトリを確認してください。