AvatarRecovery — VRChat アバター/ワールド復元ツール

VRChat の .vrca / .vrcw AssetBundle を Unity プロジェクトに復元するための Editor 拡張です。 SARS の技術的手法を参考にした独自実装の復元補助処理と AssetRipper.exe を組み合わせ、 Missing Script・ピンクマテリアル・Broken PPtr エラーの切り分けと復旧を支援します。

動作要件

必須

項目	内容
Unity	2022.3.x (VCC 推奨バージョン)
VRChat SDK	`com.vrchat.base` 必須。Avatar プロジェクトは `com.vrchat.avatars`、World プロジェクトは `com.vrchat.worlds` を VCC 経由で利用
AssetRipper.exe	Dean2k/SARS の `Release.zip` から取得
OS	Windows 10/11

Avatar Recovery 1.0.3 以降は、既存 World / Avatar Project の SDK 構成を壊さないように com.vrchat.base の依存範囲を広く取っています。 VRChat SDK - Base と VRChat SDK - Worlds / VRChat SDK - Avatars は VCC 上で同じバージョン系列に揃えてください。例: Worlds 3.7.6 + Base 3.10.3 のような混在は VRCWorldBuilder 初期化エラーの原因になります。

推奨 (見た目復元のため)

項目	内容
Poiyomi Toon Shader	https://poiyomi.com/
lilToon	https://lilxyzw.github.io/lilToon/

これらが無い場合、復元したマテリアルは Standard シェーダーにフォールバックされます (機能的には動作しますが見た目が変わります)。

インストール

1. AssetRipper.exe を配置

Dean2k/SARS から Release.zip をダウンロードし、お好きな場所に展開してください。配置パスは 自由に選べます — 以下の 2 つの方法のいずれかで指定できます。

方法 A: UI から手動指定 (どこに置いても OK)

任意の場所に AssetRipper.zip を展開
Unity で Tools → Avatar Recovery を開く
「設定」タブを選択
「AssetRipper.exe パス」欄に AssetRipper.exe のフルパスを入力
- または「参照…」ボタンでファイル選択ダイアログから指定
入力すると即座に EditorPrefs に保存され、「✓ 検出済み: [パス]」と表示されます

方法 B: 自動検出されるパスに配置 (UI 設定不要)

以下のいずれかに AssetRipper.exe を置けば、ツールが自動検出します:

パス	説明
`%USERPROFILE%\Tools\AssetRipper\AssetRipper.exe`	ユーザーフォルダー直下 (推奨)
`%USERPROFILE%\Downloads\AssetRipper\AssetRipper.exe`	ダウンロードフォルダー
`%USERPROFILE%\Desktop\AssetRipper\AssetRipper.exe`	デスクトップ
`%LOCALAPPDATA%\AssetRipper\AssetRipper.exe`	ローカルアプリデータ
`%PROGRAMFILES%\AssetRipper\AssetRipper.exe`	Program Files
`%PROGRAMFILES(X86)%\AssetRipper\AssetRipper.exe`	Program Files (x86)
`C:\Tools\AssetRipper\AssetRipper.exe`	C ドライブ Tools フォルダー
`D:\Tools\AssetRipper\AssetRipper.exe`	D ドライブ Tools フォルダー
`E:\Tools\AssetRipper\AssetRipper.exe`	E ドライブ Tools フォルダー
`C:\Tools\ARC\Assets\AssetRipper\AssetRipper.exe`	ARC 互換配置

設定タブを開くと「✓ 検出済み: [パス]」と表示されれば成功です。検出されない場合は警告メッセージと共に配置候補が表示されます。

見つからない場合、ツールは自動的に AssetRipper モードを無効化します (Unity API のみで展開する旧モードで動作)。 AssetRipper モードでないと VRCAvatarDescriptor 等の Missing Script を解決できないため、必ず配置することを推奨します。

2. Unity プロジェクトを準備

VCC で新規 / 既存プロジェクトを開き、以下のパッケージをインストール:

✅ VRChat SDK - Base (com.vrchat.base)
✅ Avatar Project では VRChat SDK - Avatars (com.vrchat.avatars)
✅ World Project では VRChat SDK - Worlds (com.vrchat.worlds)
✅ (推奨) Poiyomi または lilToon シェーダー

3. AvatarRecovery.unitypackage をインポート

Unity でプロジェクトを開く
メニュー: Assets → Import Package → Custom Package…
AvatarRecovery.unitypackage を選択
全てチェックされた状態で Import をクリック
インポート後、Packages/com.nickel-jp.avatar-recovery/ 配下にツール本体が配置されます

4. 動作確認

メニュー: Tools → Avatar Recovery を選択。ウィンドウが開けば成功です。「設定」タブを開いて「AssetRipper.exe パス」欄が ✓ になっていることを確認してください。

基本的な使い方

単一ファイルの復元

Tools → Avatar Recovery でウィンドウを開く
「ファイル指定」タブを選択
「ファイルを選択…」ボタンで .vrca ファイルを 1 つ選ぶ
「展開する」ボタンをクリック
完了後、Assets/AvatarRecovery/Restored Avatar data/[ファイル名]/[ファイル名].prefab に復元
Project ウィンドウから Prefab をシーンにドラッグ&ドロップ

複数ファイルの一括復元

方法 A — フォルダー指定

「フォルダーから一括追加…」ボタンをクリック
.vrca / .vrcw を含むフォルダーを選択 (直下のファイルを自動収集)
リストを確認 (不要な行は ✕ ボタンで削除可能)
「N 件を一括展開する」ボタンをクリック

方法 B — ドラッグ&ドロップ

エクスプローラーから複数の .vrca / .vrcw ファイルを選択
ウィンドウの「ここにドラッグ&ドロップ」エリアにまとめてドロップ
一括展開を実行

方法 C — VRChat キャッシュからスキャン

「キャッシュスキャン」タブを選択
「スキャン実行」ボタンで VRChat キャッシュ (%LocalAppData%\..\LocalLow\VRChat\VRChat\Cache-WindowsPlayer) を自動スキャン
各行のチェックボックスで対象を選択
「全選択」「Avatar のみ」「World のみ」ボタンで一括選択も可能
「N 件を一括展開する」ボタンをクリック

機能詳細

タブ構成

📁 ファイル指定タブ

単一ファイル選択 (.vrca / .vrcw)
フォルダー一括追加
ドラッグ&ドロップ対応 (複数ファイル / フォルダー対応)
重複自動排除
v2.1 追加: 各行に「👁 プレビュー」ボタン — Unity 内で展開前に確認可能
v1.7 追加: 展開成功したファイルはリストから自動削除

📋 キャッシュスキャンタブ

VRChat キャッシュフォルダーの自動スキャン
スキャンモード: __data ファイルスキャン / .vrca/.vrcw 拡張子スキャン
各行にチェックボックス (バッチ選択用)
フィルター: 全選択 / 全解除 / Avatar のみ / World のみ
暗号化済みファイル (新型 VRChat キャッシュ) の検出と警告表示
v2.1 追加: 選択ファイルに「プレビュー」ボタン

🔍 MissingScriptSearch タブ (v1.3 以降)

Hierarchy 全体スキャン / ドラッグ&ドロップで対象選択
Missing Script 行の個別 ON/OFF (Shift/Ctrl 修飾キー対応)
一括削除 (Undo 対応)

🧪 診断タブ (v3.2 以降)

選択中のアバター / Prefab / 復元フォルダを読み取り専用で診断
Blueprint ID 残存、Missing Script、Expression Menu 未解決参照、Material / Shader 問題、Poiyomi auto-lock 対象を検出
Dope Shader 2.3.1 の instanceID 既知ビルドエラーを Critical として表示
診断結果は Console 出力またはテキスト保存可能

⚙️ 設定タブ

アバター/ワールドの出力フォルダー指定
.unitypackage 出力先指定
AssetRipper.exe パス指定 + 自動検出ステータス表示
動作オプション:
- AssetRipper + SARS パイプラインで展開 (推奨・デフォルト ON)
- Shader 自動再割り当て (SARS) (v1.6 追加・デフォルト OFF)
- ピンクマテリアル修正 (フォールバック) (旧: シェーダー再割り当て)
- .unitypackage として出力 (展開後に Package 出力)
- 展開後にシーンへ配置 (デフォルト OFF — 復元時は不要)
- 展開時の Missing Script 削除 (v1.5: 自動 / 確認 / スキップの 3 値)
- 展開後に自動診断 (v3.2: 読み取り専用のアップロード前診断)
背景画像設定 (v1.8 追加): PNG/JPEG 背景、不透明度、描画モード、プレビュー

🖼️ VRCA Preview ウィンドウ (v2.1 以降)

.vrca / .vrcw を展開せずに Unity 内で即プレビュー:

PreviewRenderUtility で隔離シーンにレンダリング (外部ツール不要)
統計表示: Renderer / Vertex / Material / Bone 数
Scene View ViewTool 互換マウス操作 (v2.2)
- 左ドラッグ=パン、右ドラッグ=回転、ホイール=ズーム
Skybox マテリアル選択 (v2.3) — 背景を Skybox マテリアルで差し替え

🛠️ 追加ユーティリティ (v3.0)

トップレベルメニュー: AvatarRecovery → ウィンドウを開く (v1.7)
AvatarRecovery → PhysBone・Contact 参照チェック (v3.0) — 選択 GameObject 配下の VRC コンポーネントの参照切れを検出
AvatarRecovery → アップロード前診断 (v3.2) — 選択 GameObject の SDK / Shader / Material 問題を診断

進捗表示・キャンセル

一括展開時はキャンセル可能なプログレスバーで進捗表示
v1.6.1 以降: AssetRipper 実行中でも 200ms 粒度でキャンセル反応
個別ファイルが失敗しても残りのファイル処理は継続
完了後にサマリー表示 (成功/失敗/スキップ件数 + 修正統計)
v3.2 追加: 展開後自動診断を ON にすると、Critical / Warning / Info 件数をサマリーへ追記
v3.0 追加: [SARS][計測] ログで各フェーズの処理時間を Console 出力

SARS 復元パイプラインの仕組み

「AssetRipper + SARS パイプライン」モードを ON にした場合、以下の処理が自動実行されます:

.vrca ファイル選択
  ↓
[1] AssetRipper.exe を外部プロセスとして起動
  ├─ 一時ディレクトリに ExportedProject 出力
  └─ ダミーの Scripts/.cs と Shader/.shader が含まれる
  ↓
[2] ScriptGuidFixer (SARS FixScripts の手法を参考にした独自実装)
  ├─ 一時ディレクトリ内の .cs.meta から (stub GUID → 型名) を抽出
  ├─ TypeCache でプロジェクト内の本物の MonoScript を検索
  └─ .prefab/.controller/.asset/.unity/.anim 内の m_Script: を書き換え
  ↓
[3] ShaderGuidFixer (SARS EasyShaderReassign の手法を参考にした独自実装)
  ├─ ダミー .shader ファイルから元シェーダー名を読み取る
  ├─ プロジェクト内の Poiyomi/lilToon/Standard を自動検索
  └─ .mat 内の m_Shader: を書き換え
  ↓
[4] ダミーの Scripts/Shader フォルダーを一時ディレクトリから削除
  ↓
[5] クリーンなアセットを Unity プロジェクトの target フォルダーへコピー
  ├─ .meta ファイルも一緒にコピー (GUID 整合性のため必須)
  └─ シンボリックリンク / パストラバーサル攻撃を防ぐガード付き
  ↓
[6] AssetDatabase.Refresh
  ↓
[7] MissingScriptCleaner
  └─ Prefab に残った Missing Script コンポーネントを削除
  ↓
[8] PoseResetter
  ├─ SkinnedMeshRenderer.sharedMesh.bindposes から本来のボーン位置を計算
  └─ 全ボーンを T ポーズ (バインドポーズ) に戻す
  ↓
完了 — Console に統計サマリー出力

このアプローチの利点

Missing Script を完全解決: VRCAvatarDescriptor / PipelineManager 等の SDK スクリプト参照が正しく解決される
Broken PPtr エラー 0 件: 全ての MonoScript / Mesh / Material 参照が GUID レベルで正しくリンクされる
マテリアルが正しく表示: ピンクマテリアル問題を自動解決
T ポーズで復元: バンドル構築時のおかしなポーズも自動修正

出力フォルダー構造

復元結果は拡張子に応じて自動振り分けされます:

Assets/AvatarRecovery/
├── Restored Avatar data/        ← .vrca の復元先
│   ├── キプフェル/                    ← 元ファイル名でサブフォルダー
│   │   ├── AnimationClip/
│   │   ├── AnimatorController/
│   │   ├── AudioClip/
│   │   ├── Avatar/
│   │   ├── AvatarMask/
│   │   ├── Material/
│   │   ├── Mesh/
│   │   ├── MonoBehaviour/
│   │   ├── Texture2D/
│   │   └── キプフェル.prefab           ← メイン Prefab
│   ├── アリス/
│   └── ...
└── Restored World data/         ← .vrcw の復元先
    ├── ぼくの神社/
    │   ├── Mesh/
    │   ├── Material/
    │   └── ぼくの神社.prefab
    └── ...

サブフォルダー名の決定ロジック

優先度	使用する名前	例
1	元 `.vrca` のファイル名 (拡張子なし)	`キプフェル.vrca` → `キプフェル`
2	Blueprint ID (キャッシュ `__data` 展開時)	`avtr_xxxxx-xxxx-xxxx`
3	`Unknown` (最終フォールバック)	—

トラブルシューティング

`AssetRipper.exe が見つかりません` エラー

原因: AssetRipper.exe が想定パスに無く、UI でもパス指定されていない

対処 (どちらか):

設定タブの「AssetRipper.exe パス」欄で 「参照…」ボタン から AssetRipper.exe を直接指定
自動検出パス (%USERPROFILE%\Tools\AssetRipper\ 等) のいずれかに展開

復元したアバターが Missing Script のまま

原因: VRChat SDK がプロジェクトにインストールされていない

対処:

VCC で VRChat SDK - Avatars パッケージをインストール
アバターを再展開 (既存の Restored Avatar data/[名前]/ フォルダーを削除してから実行)

原因: AssetRipper/SARS 展開時点で VRCExpressionsMenu asset 本体を Unity asset として復元できず、Prefab に未解決GUIDだけが残っている可能性があります。0000000deadbeef... のようなGUIDは、参照先を解決できなかったことを示すプレースホルダーとして扱われます。

対処:

元の UnityPackage、購入アバターのプロジェクト、バックアップ等から VRCExpressionsMenu を再割り当て
Missing 表示だけを消す場合は、空の VRCExpressionsMenu asset を作成して Avatar Descriptor に割り当て
元のメニュー階層、表示名、アイコン、並び順は、Menu asset 本体がない場合は完全復元できません

マテリアルがピンク色

原因: Poiyomi / lilToon シェーダーがプロジェクトにインストールされていない

対処:

VCC または各シェーダーの公式サイトからインストール
インストール後、Avatar Recovery で再展開
または、設定タブの「シェーダーを再割り当て」をオンにして部分的に修正

`Broken text PPtr GUID 00000000... fileID -XXXXX is invalid!` エラー

原因: SARS パイプラインが OFF になっているか、AssetRipper が認識されていない

対処:

設定タブで「AssetRipper + SARS パイプラインで展開」がオンになっているか確認
「AssetRipper.exe パス」欄が ✓ になっているか確認
既存の復元結果を削除して再展開

Hierarchy にドロップした Prefab が空っぽ

原因: AssetDatabase の非同期インポートとのタイミング問題

対処:

Project ウィンドウから Prefab を 再ドラッグ してシーンに置き直す
または Prefab をダブルクリックして Prefab Stage で開いてから保存し直す
設定タブの「展開後にシーンへ配置」はデフォルトで OFF にしてあります

アバターのポーズがおかしい (背中が曲がっている等)

原因: バンドル構築時のアニメーションポーズが Transform に焼き付けられている

対処: PoseResetter が自動的に T ポーズに戻すので、Console に「ボーンリセット: N 個」のログが出ていれば修正済みです。出ていない場合は SkinnedMeshRenderer の bindposes が壊れている可能性があるため、コンソールエラーを確認してください。

バッチ展開でメモリ不足

原因: 大量のアバターを連続展開して GPU メモリが枯渇

対処:

数件ずつ分割して実行
Unity を再起動してメモリをリセット

暗号化されたキャッシュが検出される

原因: 2024 年以降の VRChat はキャッシュを暗号化しているため復元不可

対処:

暗号化以前 (2023 年以前) に保存されたキャッシュのみ復元可能
自分のアバターを復元したい場合は VRChat SDK でローカルテスト時に出力される未暗号化バンドルを使用してください

既知の制限

制限	内容
対応 OS	Windows のみ (AssetRipper.exe 依存)
Unity バージョン	2022.3.x で動作確認済み。2019.4 のバンドルもパッチ可能だが major version が異なるとブロックされる
暗号化キャッシュ	復元不可 (VRChat 2024 年以降のキャッシュ)
ヒューマノイド以外の Rig	T ポーズリセットが SkinnedMeshRenderer.bindposes ベースなので一応動作するが、HumanPoseHandler による補正は humanoid アバター限定
PhysBone の Rest 位置	復元後に Inspector で「Reset」ボタンを手動で押すことを推奨
AssetRipper のライセンス	GPL — 外部プロセスとして呼び出すため AvatarRecovery 本体のライセンスとは独立

ライセンス

Avatar Recovery Unity 本体は MIT License で配布しています。詳細は同梱の LICENSE を参照してください。

本パッケージは AssetRipper 本体を同梱していません。AssetRipper はユーザーが個別に取得・配置する外部ツールであり、AssetRipper 側のライセンスは GPL-3.0 です。

SARS 本体のソースコード・バイナリは同梱していません。SARS の技術的手法を参考に、復元補助処理を Avatar Recovery Unity 側で独自実装しています。

法的・倫理的注意

⚠️ 必ずお読みください

このツールは データバックアップ・自分の作品復元 を目的としています。以下の利用は VRChat の利用規約および各国の著作権法に違反する可能性があります:

用途	可否
✅ 自分が作成 / 購入したアバターの復元	OK
✅ ローカルテスト用バンドルからのデータ救出	OK
✅ 失った Unity プロジェクトの復元	OK
❌ 他人のアバターを抽出して再アップロード	NG (著作権侵害)
❌ 販売アバターを未購入で抽出	NG (著作権侵害)
❌ フレンドのキャッシュからアバターを盗用	NG (TOS 違反)
❌ 抽出したアセットを再配布	NG (著作権侵害)

VRChat はリッピング検知の仕組みを強化しており、検知された場合 アカウント BAN の対象になります。このツールを使用したことによって生じたいかなるトラブルについても、開発者は責任を負いません。

クレジット

参考にした技術的手法

SARS (Dean2k/SARS) by Dean2k and SARS Contributors
- FixScripts の手法を参考に ScriptGuidFixer を独自実装
- EasyShaderReassign の手法を参考に ShaderGuidFixer を独自実装
- RemoveMissingScripts の手法を参考に MissingScriptCleaner を独自実装
- SARS 本体のソースコード・バイナリは同梱していません

外部依存ツール

AssetRipper by ds5678 (GPL ライセンス)
- https://assetripper.github.io/
- .vrca / .vrcw バイナリの解析とプロジェクトエクスポート

Unity API

HumanPoseHandler — humanoid アバターのポーズリセット
MonoScript.FromMonoBehaviour — スクリプト型解決
PrefabUtility.LoadPrefabContents / SaveAsPrefabAsset — Prefab 操作
AssetDatabase.TryGetGUIDAndLocalFileIdentifier — GUID 解決

アップデート履歴

凡例: 🆕 新機能 / 🐛 バグ修正 / 🔒 セキュリティ / 📦 内部改善 / ⚙️ UX 改善 / 🧪 デバッグ

🧪 診断タブで Expressions > Menu の未解決GUIDを Warning として検出
⚙️ AssetRipper + SARS 展開完了時に、Expression Menu が未解決の場合は Console Warning を自動出力
📦 Warning には、AssetRipper/SARS 展開時点で VRCExpressionsMenu asset 本体を復元できなかった可能性と、元Menu assetなしでは完全復元できない理由を記載

v3.2 (2026-05-12) — アップロード前診断と復元堅牢化

🧪 アップロード前診断

新規: Core/AvatarRecoveryDiagnostics.cs + UI/AvatarDiagnosticsPanel.cs

診断タブを追加し、選択中アバター / Prefab / 復元フォルダを読み取り専用で検査
PipelineManager.blueprintId 残存、VRC_AvatarDescriptor 欠落/複数、Missing Script、Expression Menu 未解決参照を検出
null Material、InternalErrorShader、unsupported shader、Editor.log 上の shader compile error を検出
Poiyomi/ThryEditor auto-lock 対象 Material を Warning として表示
Dope Shader 2.3.1 の invalid subscript 'instanceID' 既知エラーを Critical として表示
MenuItem AvatarRecovery/アップロード前診断 を追加

⚙️ 展開後自動診断

設定タブに 「展開後に自動診断」 を追加 (デフォルト OFF)
ON の場合、展開成功 Prefab を保存せず読み取り診断し、バッチサマリーに Critical / Warning / Info 件数を追記

📦 Prefab 選定の堅牢化

AssetRipper 出力後、FindAssets("t:Prefab") の先頭を無条件採用しない
VRC_AvatarDescriptor、PipelineManager、Renderer 数、ファイル名一致でメイン Prefab 候補をスコアリング

v3.0 (2026-04-19) — 本番環境デバッグプロンプト v3.2 準拠

🧪 環境チェッカー追加 (Phase 1.1)

新規: Utils/AvatarRecoveryEnvChecker.cs

ウィンドウ起動時に以下を自動チェックし、Console に [SARS] ログを出力:

Unity バージョン (2022.3.22f1 と不一致なら警告)
VRC SDK バージョン — Avatar Project では Packages/vpm-manifest.json から com.vrchat.avatars 抽出 (新旧両形式に対応)。World Project では Avatar 専用チェックをスキップ
VRAM 容量 — 7500 MB 未満で警告 (8GB VRAM ドライバ誤差対応)

🧪 ファイルロック対策 (Phase 2.1)

VrcaLoader.cs の TryLoadBundle に追加:

200ms × 3 リトライ でファイルロックを検出 → VRChat 起動中でも安全
リトライ全失敗時は「SARS 読み込みエラー」ダイアログ + 例外伝搬
LoadFromFile null 時も詳細ダイアログ (既存 return false 動作は不変)

🧪 GUID 衝突検出 (Phase 2.2)

AssetRipperBridge.cs の CopyExportedAssets 直後に追加:

.meta 群を Regex で走査し、既存プロジェクトと重複する GUID を Console に警告
処理ブロックなし (検出のみ、ユーザーに確認を促す)

🆕 PhysBone / Contact 参照チェッカー (Phase 3.2)

新規: Core/AvatarRecoveryValidators.cs + MenuItem AvatarRecovery/PhysBone・Contact 参照チェック

Hierarchy で選択中の GameObject 配下の VRC コンポーネントを検査
VRCPhysBone.rootTransform == null → ℹ️ Info (SDK 3.10.0 で正常動作のため誤検知防止)
VRCPhysBoneCollider.rootTransform == null → ⚠️ Warning (参照切れの可能性)
VRCContactReceiver/Sender.collisionTags 空 → ℹ️ Info
SDK 未導入環境でもコンパイル可能 (型名文字列 + SerializedObject リフレクション)

🧪 処理時間計測 (Phase 4.1)

try-finally で既存コードをラップし、処理時間を [SARS][計測] ログに出力:

VrcaExtractor.Extract
AssetRipperBridge.Extract
AvatarRecoveryWindow.RunBatchExtraction

🔒 SECTION 0 ルール厳守

全変更は以下の制約下で実施:

既存メソッドの削除・シグネチャ変更・内部ロジック変更なし
既存 UI レイアウト・ボタン配置変更なし
許可パターン (B/C/D/E/F/G/H) のみ使用

v2.3.1 (2026-04-19) — 本番環境向けデバッグパス 2 (v2.x 差分精査)

🐛 HIGH バグ修正 3 件

ID	症状	修正
#4	ドメインリロード時 AssetBundle リーク — 再コンパイル後に「another AssetBundle already loaded」エラー	`AssemblyReloadEvents.beforeAssemblyReload` で事前 Unload
#1	hotControl が解除されない — MouseDown 内のみの `GetControlID` で ID ズレ	固定ヒント `"AvatarRecovery.VrcaPreviewWindow.Drag".GetHashCode()` で毎フレーム安定 ID
#2	別ボタン MouseUp で左ドラッグが誤終了	`_dragButton` で開始ボタン記録、対応ボタンでのみ終了

🐛 MEDIUM バグ修正 2 件

ID	症状	修正
#6	Skybox ObjectField に focus 中 F/0 キーで視点リセット	`KeyDown && rect.Contains` チェック追加
#13	`File.Replace` が長日本語パスで失敗	新ヘルパー `LongPathIO.TryAtomicReplace` (両パスに `\\?\` 自動付与)

v2.3 (2026-04-19) — Skybox 背景対応

🆕 VRCA Preview で Skybox マテリアル選択

VrcaPreviewWindow.cs — 「視点リセット」ボタンの左隣に ObjectField 配置:

PNG / Cubemap / Procedural 等の Skybox マテリアルで背景を差し替え
Camera.gameObject.AddComponent<Skybox>() 方式 (ユーザーの Scene 非汚染)
EditorPrefs に選択パスを永続化 (次回復元)
未指定時は暗色背景 (#1F1F23) にフォールバック

v2.2 (2026-04-19) — Unity Scene View 互換マウス操作

⚙️ VRCA Preview のカメラ操作を Scene View ViewTool 準拠に

操作	動作
左ドラッグ	パン (平行移動、縦方向=高さ変更)
右ドラッグ	視点回転 (Orbit)
中ドラッグ	パン (バックアップ)
スクロール	ズーム
F キー	(補助) アバター全体にフォーカス
0 キー	(補助) 初期視点リセット

修飾キー不要、マウスのみで完結。

v2.1 (2026-04-19) — VRCA Preview ウィンドウ

🆕 ARC の “Preview VRCA” 相当機能 (Unity 内完結)

新規: UI/VrcaPreviewWindow.cs

PreviewRenderUtility で隔離シーンにレンダリング (外部ツール不要)
AssetBundle メモリロードのみ → Assets/ 非汚染
Renderer / Vertex / Material / Bone 統計表示
ピンクマテリアルは内部で ShaderRemapper 自動フォールバック

v2.1.1 バグ修正

絵文字 👁 がフォントにグリフが無く豆腐表示される問題 → Unity 標準アイコン (ViewToolOrbit 等) + 和文「プレビュー」に差し替え (GetEyeIcon() で複数名をフォールバック試行)

v2.0 (2026-04-19) — SARS v25.5.27 互換改善

SARS v25.5.27 系で確認した重要改善の考え方を参考に、AvatarRecovery 側で独自実装:

#	改善	実装ファイル
N1	`\\?\` 長パス対応 StreamReader/Writer	新規 `Utils/LongPathIO.cs`
N2	`ObjectFactory.AddComponent` + `RequireComponent` 自動解決	新規 `Core/ComponentDependencyResolver.cs`
N4	`tempComp` を明示 `DestroyImmediate`	`ScriptGuidFixer.cs` 修正

実害改善:

長い日本語パスで StreamReader が DirectoryNotFoundException → 32767 文字まで対応
VRCPhysBone 等 [RequireComponent] 持ち型で MonoScript 解決失敗 → 依存を先に追加して再試行で解決率向上

v1.9 (2026-04-18) — 本番環境向け総合デバッグ

全 15 ファイルを精査し 10 件の HIGH/MEDIUM バグを修正:

ID	ファイル	問題	修正
C1	VrcaLoader.cs	`info == null` で NRE	null 早期 return に分離
C2	PoseResetter.cs	エラー時に壊れた Prefab を上書き	`ErrorMessage` ガード
H1	VrcaCacheScanner.cs	ルート直下 `__data` で NRE	`blueprintId` null チェック
H2	VrcaCacheScanner.cs	空リストでゼロ除算	`Math.Max(1, count)` ガード
H3	ShaderRemapper.cs	`sharedMaterials` 代入後 `SetDirty` 抜け	明示的に `SetDirty` 呼び出し
H4	Styles.cs	Texture2D リーク (ドメインリロード時)	`HideFlags.HideAndDontSave`
H5	VrcaLoader.cs	`fs.Read` 戻り値無視で未初期化バイト解析	`Array.Resize` で読取分のみ使用
M1	MissingScriptSearchPanel.cs	走査中 Transform 破棄で `MissingReferenceException`	null チェック追加
M2	VrcaLoader.cs	同名バンドル複数時に 1 件しかアンロード	`break` 削除
M3	ScriptGuidFixer.cs	`AddComponent` 失敗を完全サイレント	警告ログ追加

さらに 7 件の見落とし追加修正:

A1: 背景画像ロード失敗時に毎フレーム File.ReadAllBytes 実行 → finally で _loadedTexturePath 記録
A2: DrawSettingsTab 例外で labelWidth が戻らず他 UI に影響 → try-finally 保証
A3-A5: EnsureUnityFolder / EnsureFolderExists / ShaderListWriter で絶対パス silent 失敗 → 先頭 “Assets” 検証
A6: DrawBackgroundImage が Layout イベントでも動作 → Repaint のみに限定
A7: 展開中にウィンドウを閉じると ProgressBar が残留 → OnDisable で ClearProgressBar

v1.8 (2026-04-19) — 背景画像機能

🆕 ツールウィンドウ背景に PNG/JPEG を設定可能

設定タブに「背景画像 (v1.8)」セクション追加:

不透明度スライダー (0〜1、デフォルト 0.3)
描画モード (StretchToFill / ScaleAndCrop / ScaleToFit)
プレビュー表示 (v1.8.1 で GUI.DrawTexture に変更して歪み解消)
GPU リーク対策 (HideFlags.HideAndDontSave + OnDisable で明示破棄)

v1.7 (2026-04-18) — UX 改善 2 点

⚙️ 成功ファイル自動削除

展開成功した .vrca / .vrcw は:

ファイル指定タブの選択リストから自動削除
キャッシュスキャンタブでチェックを自動解除
二重展開ミス防止

⚙️ Unity メニュー直下に `AvatarRecovery` 追加

Tools → AvatarRecovery (互換) に加え、新たに AvatarRecovery → ウィンドウを開く をトップレベルに追加。

v1.6 (2026-04-18) — List of Shaders + Shader 自動再割り当てトグル

🆕 List of Shaders/Shaders.txt 出力

新規: Core/ShaderListWriter.cs

復元結果フォルダ内に List of Shaders/Shaders.txt を自動生成:

元バンドルに含まれていた全シェーダー名
stub GUID / プロジェクト内解決結果 / 置換先 GUID
自動置換 ON/OFF どちらでも出力

🆕 Shader 自動再割り当てトグル (デフォルト OFF)

設定タブに 「Shader 自動再割り当て (SARS)」 トグル追加:

OFF (デフォルト・推奨): マテリアルは書き換えず Shaders.txt のみ出力 → 手動割り当て想定
ON: v1.5 以前と同じ自動書き換え

📦 内部改善

ShaderGuidFixer を 3 段階 API に分解 (CollectShaderMappings / ResolveMappingsPublic / ApplyMappings)
EditorPrefsHelper に AutoReassignShaders / BackgroundImagePath / BackgroundOpacity / BackgroundScaleMode / PreviewSkyboxPath 等の永続化キー追加

v1.6.1 - v1.6.3 逐次バグ修正

v1.6.1: キャンセルボタン無反応 → DisplayCancelableProgress ヘルパー + RunAssetRipper ポーリングで 200ms 粒度キャンセル実現
v1.6.2: AssetRipper 出力構造が .vrcw で異なるケース → FindExportedAssetsDir で BFS 再帰探索
v1.6.3: 絶対パス D:/... 指定時に ExportPackage が「No assets to export」 → NormalizeToAssetsPath で Assets/... に正規化

v1.5 (2026-04-14) — Missing Script 削除ポリシーの 3 値化

🐛 バグ修正 — v1.4 の二重実行を解消

v1.4 で追加した「展開完了後の Missing Script 削除確認ポップアップ」は、SARS パイプライン内の MissingScriptCleaner と二重に実行 される設計上の欠陥がありました (SARS 経由の場合は既に削除済みになっており、ポップアップでは常に 0 件)。

🆕 新機能 — Missing Script 削除ポリシー (3 値 enum)

v1.4 の bool トグルを 3 値の選択肢 に変更し、ユーザーが SARS パイプラインの Missing Script 削除ステップを完全にコントロールできるようにしました。

設定タブ → 動作オプション内に「展開時の Missing Script 削除」プルダウンを追加:

値	動作
自動削除 (推奨) ← デフォルト	展開時に常に削除 (v1.0〜v1.3 と同じ動作)
展開後にポップアップで確認	展開時はスキップ → 完了後に OK/NO を確認
削除しない	完全スキップ → MissingScriptSearch タブから手動削除可能

この設定で制御されるのは MissingScriptCleaner のみ

SARS パイプラインの他のステップ (FixScripts / FixShaders / PoseResetter / Prefab リネーム) は 常に自動実行 されます。Missing Script 削除だけが選択可能です。

用途別の使い分け

自動削除: ほとんどのユーザーはこれで OK (現状の挙動と同じ)
確認する: 復元結果を都度確認しながら作業したい場合
削除しない: Missing Script の理由を後で解析したい / カスタムスクリプトの行方を追跡したい場合

📦 自動マイグレーション

v1.4 の bool キー (AutoMissingScriptPrompt) を保存していたユーザーは自動的に新ポリシーに変換されます:

v1.4 で true (ポップアップ ON) → v1.5 で Ask
v1.4 で false (デフォルト) → v1.5 で Always

📦 内部改善

MissingScriptDeletePolicy enum を MissingScriptCleaner.cs に追加
AssetRipperBridge.Extract / VrcaExtractor.Extract に missingScriptPolicy パラメータ追加
AssetRipperBridge 内の MissingScriptCleaner 呼び出しを policy == Always で条件化

v1.4 (2026-04-14) — 展開後 Missing Script 自動削除確認

🆕 新機能 — 展開完了後の Missing Script 削除確認ポップアップ

.vrca / .vrcw を展開した直後に、復元 Prefab に対して Missing Script の自動削除を実行するかをユーザーに確認 するポップアップを表示する機能を追加。

動作

一括展開が完了したタイミングで以下のダイアログを表示:

展開完了した N 件の Prefab に対して、Missing Script の自動削除を実行しますか?

[OK (削除実行)]  [NO (スキップ)]

OK → 全ての成功した Prefab に対して MissingScriptCleaner.CleanPrefabAsset を実行 (進捗バー表示)
NO → 何もせずスキップ
実行結果はステータスバー / Console に「Missing Script 自動削除 (展開後): X 個」として表示

設定

設定タブ → 動作オプション に「展開完了後に Missing Script 削除確認を表示」トグルを追加
デフォルト OFF (誤操作防止のため安全側、ユーザー要望)
ON にした場合のみポップアップが表示される

用途

SARS パイプライン経由でも稀に残る Missing Script の最終クリーンアップ
Unity API ベースの旧経路 (SARS パイプライン OFF) で展開した時の補完
復元データを配布前に確実にクリーンな状態にしたい場合

📦 内部改善

EditorPrefsHelper に LoadAutoMissingScriptPrompt / SaveAutoMissingScriptPrompt 追加
RunBatchExtraction で成功した Prefab パスを successPrefabPaths リストに収集
新ヘルパー PromptAndRunAutoMissingScriptCleanup を実装

v1.3 (2026-04-14) — Missing Script 検索タブ追加

🆕 新機能 — MissingScriptSearch タブ

復元アバターやシーンに残っている Missing Script (型解決できなくなったコンポーネント) を検出して一括削除する新タブを追加しました。タブ構成は ファイル指定 / キャッシュスキャン / MissingScriptSearch / 設定 の 4 つに拡張されました。

スキャン

Hierarchy 全体スキャン — 開いている全シーン + Prefab Stage を一括チェック
D&D スキャン — 任意の GameObject / Prefab をエリアにドロップして部分スキャン
大規模スキャン対応 — 500 GameObject 超でキャンセル可能なプログレスバー

一覧表示と選択

検出した Missing Script を 縦に一覧表示 (フラットリスト)
行ごとに チェックボックス で個別 ON/OFF
全選択 / 全解除 ボタン
複数選択操作 (Windows エクスプローラー / Unity Hierarchy 互換):
- Shift + クリック — 直前のクリックから現在位置までを範囲選択
- Ctrl + クリック — 個別 ON/OFF (トグル)
- 修飾なしクリック — 単一選択 (他をクリア)
フィルター検索 — GameObject 名 / Hierarchy パスで絞り込み
選択済みハイライト + ストライプ表示 + Prefab タグ
スクロールビュー対応

削除処理

選択した Missing Script を 一括削除 (確認ダイアログあり)
Undo 完全対応 — Ctrl+Z で削除前の状態に復帰可能
Prefab インスタンス対応 — RecordPrefabInstancePropertyModifications で Prefab 側にも変更を記録
削除後に自動再スキャン

v1.2 (2026-04-14) — 既知の問題対応

🆕 新機能

復元 Prefab の自動リネーム — AssetRipper のデフォルト名 (prefab-id-v1_avtr_xxx_NNN.prefab) を [元ファイル名].prefab (例: キプフェル.prefab) に自動変換
- キャッシュ __data 展開時は BlueprintId にフォールバック
- 同名衝突時は連番 (2), (3) を付与
非ヒューマノイド (Generic) rig のポーズリセット精度向上
- TRS 完全分解 (Position / Rotation / Scale を独立に抽出)
- 反射 (mirror) 検出 — 行列式判定で左右反転を補正
- スケール適用 — bone.localScale を親スケール考慮で計算
- 動物 / ロボット型アバターでも humanoid 同等の精度で復元

📦 内部改善

asmdef 名の一意化 — AvatarRecovery.Editor → EditorTools.AvatarRecovery.Editor (namespace と統一、他パッケージとの衝突リスク排除)
診断統計の追加 — Console ログに Generic=N, 非単位スケール=M を表示

v1.1 (2026-04-12) — 配布前検証 + UI 大改修

🆕 新機能

AssetRipper.exe パスを UI から自由指定 — 「設定」タブの新規フィールド + 「参照…」ボタン
- EditorPrefs に保存され、リアルタイム検出ステータス表示 (✓ 検出済み: [パス])
- デフォルト検索パスを 2 → 10 箇所 に拡充 (%USERPROFILE%, %LOCALAPPDATA%, %PROGRAMFILES% 等の環境変数を自動展開)
複数ファイルの一括復元 (バッチ展開)
- 「ファイルを選択…」ボタン (1 件ずつ追加)
- 「フォルダーから一括追加…」ボタン (フォルダー内の全 .vrca/.vrcw を一括)
- 複数ファイルの ドラッグ&ドロップ 対応 (フォルダーも可)
- 重複自動排除 + 削除ボタン (✕)
キャッシュスキャンタブにチェックボックス
- フィルター: 「全選択」「全解除」「Avatar のみ」「World のみ」
- チェック済み件数を常時表示
キャンセル可能な進捗バー — バッチ展開中に途中中断可能
完了サマリー表示 — 成功 / 失敗 / スキップ件数 + SARS パイプライン累計統計
出力フォルダー構造の改善
- デフォルト: Restored Avatar data/[名前]/ / Restored World data/[名前]/
- 拡張子 (.vrca / .vrcw) で自動振り分け
- ファイル名でサブフォルダーを自動作成
EditorPrefs マイグレーション — 旧デフォルトパス (Extracted/, Worlds/) を保存しているユーザーは自動的に新デフォルトに更新
README.md を unitypackage に同梱 — Packages/com.nickel-jp.avatar-recovery/README.md

🐛 バグ修正

ファイル選択ダイアログが 2 枚開く問題 → ボタンを 2 つに分離

🔒 セキュリティ強化 (配布前検証で 12 件)

ID	重要度	修正内容
H1	HIGH	StreamReader/Writer に UTF-8 エンコーディング強制 (日本語ファイル名対策)
H2	HIGH	`File.Delete + File.Move` → `File.Replace` (atomic) に変更
H3	HIGH	RenderTexture リーク修正 (`try-finally` で `ReleaseTemporary` 保証)
H4	HIGH	`_checkedIndices` のスキャン再実行時クリア漏れを修正
M1	MEDIUM	パストラバーサル / symlink / junction 対策 (3 重ガード)
M3	MEDIUM	メジャーバージョン不一致パッチを警告 → エラーで中止
M4	MEDIUM	`.meta` 拡張子チェックを `EndsWith` ベースに
L1	LOW	260 文字超のパスに `\\?\` プレフィックス自動付与
L2	LOW	一時ディレクトリ削除をリトライ付き (5 回 × 200ms)
L3	LOW	Texture2D 作成前に `width/height <= 0` ガード
L4	LOW	SerializedObject を `using` パターンに (Unity 2022.3+ で IDisposable)

v1.0 (2026-04 早期) — 初回完成

🆕 主要機能の実装

SARS の手法を参考にした復元パイプライン実装
- ScriptGuidFixer — .prefab/.controller/.asset/.unity/.anim の m_Script: を YAML テキストレベルで書き換え
- ShaderGuidFixer — .mat の m_Shader: をプロジェクトシェーダーへ自動マッチング (Poiyomi / lilToon / Standard 優先順位)
- MissingScriptCleaner — Prefab 内の Missing Script コンポーネント自動削除
- PoseResetter — SkinnedMeshRenderer.bindposes ベースで全ボーンを T ポーズ (バインドポーズ) に復元
AssetRipper.exe との連携 — 外部プロセスとして起動 (GPL ライセンス分離)
VRChat キャッシュ自動スキャン
- __data ファイルスキャン (新型キャッシュ構造)
- .vrca / .vrcw 拡張子スキャン
- 暗号化済みキャッシュの自動検出と警告
Unity API ベース展開 (旧式) と SARS パイプライン (推奨) の 2 経路
Unity バージョンクロスパッチ — 同一メジャー / マイナー間 (例: 2022.3.6f1 ↔ 2022.3.22f1) のロードを可能に
3 タブ UI — ファイル指定 / キャッシュスキャン / 設定

🐛 重大バグの解決 (v1.0 で根本対応)

ピンクマテリアル + None Mesh 問題 — .meta ファイルもコピーするように修正 (AssetRipper の GUID 整合性を尊重)
VRCAvatarDescriptor の Missing Script — AvatarRecovery の ScriptGuidFixer によるテキスト書き換えで解決
999+ 件の Broken text PPtr GUID 00000000 エラー — MonoScript 参照を本物の MonoScript に自動置換
アクセス拒否でキャッシュスキャンが全停止 — Directory.GetFiles(AllDirectories) を手動再帰スキャンに変更し、フォルダーごとに try-catch でスキップ可能に
アバターポーズが歪む (背中が曲がる等) — bindposes ベースの T ポーズリセットを実装

🔍 配布前検証 (品質保証)

v1.1 以降、配布前に以下のセキュリティ・品質検証を実施しています:

✅ セキュリティ: パストラバーサル / symlink / コマンドインジェクション / 長パス対策
✅ データ整合性: 原子的ファイル置換 (File.Replace) / UTF-8 エンコーディング強制
✅ リソース管理: RenderTexture / SerializedObject / 一時ディレクトリの確実な解放
✅ クロスバージョン安全性: メジャーバージョン不一致時のロード拒否
✅ コンパイル確認: Unity 2022.3.22f1 batchmode で build error 無く完了

サポート / 不具合報告

このツールはそのままの状態で提供されます (AS-IS)。動作不良があった場合は Console ログ ([AvatarRecovery] プレフィックス付き) を確認の上、復元元 .vrca の Unity バージョン・SDK バージョン・エラーメッセージを添えてご報告ください。

Happy Recovery! 🎨

AvatarRecovery — VRChat アバター/ワールド復元ツール

目次

動作要件

必須

推奨 (見た目復元のため)

インストール

1. AssetRipper.exe を配置

方法 A: UI から手動指定 (どこに置いても OK)

方法 B: 自動検出されるパスに配置 (UI 設定不要)

2. Unity プロジェクトを準備

3. AvatarRecovery.unitypackage をインポート

4. 動作確認

基本的な使い方

単一ファイルの復元

複数ファイルの一括復元

方法 A — フォルダー指定

方法 B — ドラッグ&ドロップ

方法 C — VRChat キャッシュからスキャン

機能詳細

タブ構成

📁 ファイル指定タブ

📋 キャッシュスキャンタブ

🔍 MissingScriptSearch タブ (v1.3 以降)

🧪 診断タブ (v3.2 以降)

⚙️ 設定タブ

🖼️ VRCA Preview ウィンドウ (v2.1 以降)

🛠️ 追加ユーティリティ (v3.0)

進捗表示・キャンセル

SARS 復元パイプラインの仕組み

このアプローチの利点

出力フォルダー構造

サブフォルダー名の決定ロジック

トラブルシューティング

AssetRipper.exe が見つかりません エラー

復元したアバターが Missing Script のまま

Expressions > Menu が Missing になる

マテリアルがピンク色

Broken text PPtr GUID 00000000... fileID -XXXXX is invalid! エラー

Hierarchy にドロップした Prefab が空っぽ

アバターのポーズがおかしい (背中が曲がっている等)

バッチ展開でメモリ不足

暗号化されたキャッシュが検出される

既知の制限

ライセンス

法的・倫理的注意

クレジット

参考にした技術的手法

外部依存ツール

Unity API

アップデート履歴

v1.0.4 (2026-06-11) — Expression Menu 未解決参照の警告追加

v3.2 (2026-05-12) — アップロード前診断と復元堅牢化

🧪 アップロード前診断

⚙️ 展開後自動診断

📦 Prefab 選定の堅牢化

v3.0 (2026-04-19) — 本番環境デバッグプロンプト v3.2 準拠

🧪 環境チェッカー追加 (Phase 1.1)

🧪 ファイルロック対策 (Phase 2.1)

🧪 GUID 衝突検出 (Phase 2.2)

🆕 PhysBone / Contact 参照チェッカー (Phase 3.2)

🧪 処理時間計測 (Phase 4.1)

🔒 SECTION 0 ルール厳守

v2.3.1 (2026-04-19) — 本番環境向けデバッグパス 2 (v2.x 差分精査)

🐛 HIGH バグ修正 3 件

🐛 MEDIUM バグ修正 2 件

v2.3 (2026-04-19) — Skybox 背景対応

🆕 VRCA Preview で Skybox マテリアル選択

v2.2 (2026-04-19) — Unity Scene View 互換マウス操作

⚙️ VRCA Preview のカメラ操作を Scene View ViewTool 準拠に

v2.1 (2026-04-19) — VRCA Preview ウィンドウ

🆕 ARC の “Preview VRCA” 相当機能 (Unity 内完結)

v2.1.1 バグ修正

v2.0 (2026-04-19) — SARS v25.5.27 互換改善

v1.9 (2026-04-18) — 本番環境向け総合デバッグ

v1.8 (2026-04-19) — 背景画像機能

🆕 ツールウィンドウ背景に PNG/JPEG を設定可能

v1.7 (2026-04-18) — UX 改善 2 点

⚙️ 成功ファイル自動削除

⚙️ Unity メニュー直下に AvatarRecovery 追加

v1.6 (2026-04-18) — List of Shaders + Shader 自動再割り当てトグル

`AssetRipper.exe が見つかりません` エラー

`Broken text PPtr GUID 00000000... fileID -XXXXX is invalid!` エラー

⚙️ Unity メニュー直下に `AvatarRecovery` 追加