Unity Build Layout Viewer — Addressablesのビルド結果を可視化するセルフホスト型Webツール - Akatsuki Hackers Lab

1. ツールの概要

Addressables を本格運用していると、こういった問題が日常的に出てきます

「このビルド、なんかバンドルが大きくなってるけど原因は？」
「本番に混入してはいけないアセットが入ってないか確認して」
「前回と今回で何が変わったか教えて」

Addressables ではアセットをバンドルという単位にまとめて配布します。バンドル内のアセットが変更・追加・削除されたり、依存先の構成が変わったりするとバンドルのハッシュが変わり、ユーザーへの再配布（＝ダウンロードサイズの増加）につながります

この「どのアセットが変わってバンドルに影響したのか」を追うのが、BuildLayout.json だけでは大変で…

これらの問題を解決するためにブラウザから手軽にアセットの検索や複数ビルド・バンドル間の差分比較、アセットの依存関係の調査ができるツールを作りました

Unity Build Layout Viewer は、Addressables がビルド時に出力する BuildLayout.json を取り込んで

アセット一覧の検索・フィルタ
スナップショット間の差分比較（Diff）
アセットの上流依存関係グラフの可視化

をブラウザから行える、セルフホスト型の Web アプリです

2. 主な機能

2-1. アップロードとスナップショット管理

ブラウザ、または REST API 経由で BuildLayout.json をアップロードが可能
スナップショットにタグ・コメントを付けて管理

2-2. アセット検索

スナップショットを選択してアセット一覧を表示
クラス名・ファイル拡張子・名前・GUID でフィルタ
右クリック → Dependency Viewer で依存グラフへ遷移

2-3. スナップショット Diff

2 つのスナップショットを選んで差分を表示します

A vs B ビュー : アセット単位で Added / Missing / Hash or Size Changed を一覧

hash / missing / add / size のタグで変化の種類ごとにフィルタリングできる

Bundle ビュー : バンドル単位で内包アセットの変化を詳細表示（Moved / Added RefTo / Added RefBy なども分類）

2-4. 依存関係ビューア（Dependency Viewer）

選択したアセットから「上流（誰がこのアセットを参照しているか）」をグラフ表示
探索深さ・ノード上限をインタラクティブに変更可能
逆隣接リスト（revAdj）をメモリキャッシュして高速化

3. 仕組みの解説

3-1. BuildLayout.json のパース

BuildLayout.json は大きなファイルになりがちなので、全体をメモリに展開せずストリーミングパースを採用しています

stream-json の chain / pick / streamArray を組み合わせて
references.RefIds 配列だけを逐次処理

各エントリは rid（参照 ID）を持ち、依存関係は from_id → to_id のリンクとして別テーブルに正規化して保存しています

3-2. 依存グラフの構築

DB から全リンクを取得 → 逆隣接リストを構築 → DFS で上流チェーンを計算しています
逆隣接リストはスナップショット ID をキーにインメモリキャッシュしており、同一スナップショットへの 2 回目以降のアクセスを高速化しています

3-3. Diff アルゴリズム

両スナップショットのアセットを name をキーに Map 化
A にあって B にない → isMissing、B にあって A にない → isAdd、両方あってハッシュ違い → hash_diff
バンドル単位では DFS でバンドル配下のアセットを収集し、同名アセットの移動・追加・削除を分類

4. セットアップ方法

ローカル起動もできますが、Dockerも用意してあります

Docker

cp .example.env .env
docker compose -f compose.prod.yml build
docker compose -f compose.prod.yml run --rm app npm run prisma:deploy
docker compose -f compose.prod.yml up -d
# → http://localhost:3435

ローカル

npm install
cp .example.env .env   # DATABASE_URL を設定
npm run prisma:deploy
npm run prisma:generate
npm run dev

5. 使い方のフロー

Unity でビルドを実行して BuildLayout.json を出力
ブラウザで http://localhost:3435 へアクセス
Upload タブから BuildLayout.json をアップロード
1. タグ・コメントを付けると管理しやすくなります
Search タブでアセット一覧を確認・検索
1. 右クリック → Dependency Viewer でアセットの依存関係を調査
Diff タブで 2 つのスナップショットを選択して差分を確認

6. 実際に役立ったシーン

混入してはいけないアセットの調査

本来含まれるはずのないアセットがビルドに混入していないか確認する作業が格段に楽になりました

Search タブでアセット名を直接検索して、含まれているかどうかをすぐに確認できます
Diff タブで「前回のビルドには存在しなかったのに今回から追加された」アセットを一目で発見できます

以前はビルドログや生の JSON を目視確認していましたが、今は数秒で判断できるようになりました

バンドルサイズの増加原因の特定

「なぜかバンドルが大きくなった」という状況に対して、従来は原因の特定に時間がかかっていました

このツールを使うと：

バンドル単位の Diff でどのアセットが追加・削除・移動したのかをすぐに確認できます
アセットが別のバンドルに移動したことでサイズ増減が発生したケースも検出できます
新規追加・削除・ハッシュ変化・サイズ変化でそれぞれ分類されているので、原因を絞り込みやすくなっています

意図しない参照連鎖の発見

Dependency Viewer でアセットを選択すると、「誰がこのアセットを参照しているか」を上流方向にグラフで追えます

これにより、意図していない参照チェーン（例：共通アセットが思わぬ場所から引っ張られている）を視覚的に発見できるようになりました

チーム内の意思決定がしやすくなった

ゲームアプリにおいてダウンロードサイズが大きくなると、ユーザーがインストールや更新を敬遠して継続プレイから離れてしまうリスクがあります

「次回は小規模アップデートなのでダウンロードサイズの増加は許容できない、修正が必要」
「大型イベントを控えた大規模アップデートなので、一定のサイズ増加は問題ない」

数値の根拠があることで、感覚ではなくデータで話し合えるようになりました

まとめ

Addressables のビルド管理で同じような課題を抱えている方にぜひ使ってみていただきたいです
もし使ってみて良さそうと思っていただけたら、GitHub のスターを押してもらえると励みになります！

github.com

Akatsuki Hackers Lab | 株式会社アカツキ（Akatsuki Inc.)

Akatsuki Hackers Labは株式会社アカツキゲームスが運営しています。

Unity Build Layout Viewer — Addressablesのビルド結果を可視化するセルフホスト型Webツール