こんにちは、Unityエンジニアのオオバです。
Addressablesを使ったUnityでゲームを開発中、新しくAssetGroupを追加しました。
エディタで再生すると、問題なく動いたのですが、ビルドして実機で確かめると、そのグループのアセットだけがロードできませんでした。
「エディタでは動いていたのに、なんで？」
こういうの、本当に焦りますよね。
調べてみると、追加したグループがまるごとビルド対象から外れていたという事件のお話です。
AssetGroupの.assetファイルは追加だけでは登録されない
Addressablesのグループは、グループの .asset ファイルを置くだけでは成り立ちません。
AddressableAssetSettings.asset の m_GroupAssets に、そのグループが登録されている必要があります。
今回は、この登録行がコミットから漏れていました。
- グループ追加時はAddressableAssetSettings.assetのm_GroupAssetsの変更もコミットする
- Settingsの差分がHash行だけならコミットしなくてよい
- エディタの検証はUse Asset Databaseだけで済ませない
今回起きたこと
新しいAddressablesグループ（AssetGroups/Xxx.asset）を追加するコミットを作りました。
エディタ上では、グループに入れたアセットも問題なくロードできていましたが、ビルドすると、そのグループがまるごとビルド対象から外れました。
結果として、実機ではそのグループのアセットがロードできなかったということです。
グループの中身が一部欠けているわけではなく、グループそのものが、最初から存在しないかのような扱いになっていたという状況です。
原因：m_GroupAssetsへの登録行が漏れていた
コミットを見直すと、入っていたのはグループの .asset ファイルだけでした。
AddressableAssetSettings.asset 側の変更、つまり m_GroupAssets に新しいグループを足す行が入っていなかったのです。
Addressablesがビルド対象として扱うのは、AddressableAssetSettings.asset に登録されているグループ。
フォルダにグループの .asset があっても、Settings側に登録が無ければビルドでは拾われません。
ローカルでグループを作った時点では、エディタがSettingsにも登録してくれています。
なので僕の手元では正しく動いていました。
根本原因は、コミットに含めていなかった単純な自分のミスということになります。
なぜ登録行を落としてしまったのか
AddressableAssetSettings.asset は、差分のノイズが多いファイルです。
特に m_currentHash の Hash行だけが変わる差分 が頻繁に出ます。
中身は何も変えていないのに、毎回のように変更ファイルとして上がってくる。
そこで「Settingsの差分はコミットしない」という運用にしていました。
なぜなら、ノイズを毎回コミットするのは避けたかったからです。
ただ、この運用には落とし穴がありました。
グループを追加したときは、同じファイルに意味のある差分が入ります。
m_GroupAssets に足された + 行です。
「Settingsの差分はいつものノイズだろう」と流したことで、意味のある行までまとめて落としていました。
ノイズを避けるためのルールが、肝心の変更まで捨てさせていたわけです。
エディタで気付けなかった理由
もう1つ厄介だったのが、エディタでは問題が見えなかったことです。
エディタのPlay Mode Scriptが「Use Asset Database」の場合、アセットはAssetDatabaseから直接読み込まれます。
このモードは、グループの登録が漏れていても動いてしまいます。
つまり、エディタで確認しただけでは、登録漏れに気付く手段がありません。
ビルドして実機で動かして、初めて表に出る不具合でした。
「エディタで動いたからOK」と判断しがちですが、Addressablesではその確認が通用しない場面があります。
対策：コミットのルールと確認のしかた
再発防止として、次の3つを決めました。
AddressableAssetSettings.assetの差分の中身を見る
Settingsの差分がHash行だけなら、これまでどおりコミットしません。
ただし m_GroupAssets や m_LabelTable に + 行があるなら、Hash行ごとコミットします。
コミットするかどうかは、差分の中身を見て判断するようにしました。
グループを追加するPRでは登録行を確認する
グループを追加するPRでは、AddressableAssetSettings.asset の m_GroupAssets に行が足されているかを確認します。
グループの .asset が追加されているのにSettingsの差分が無いPRは、登録漏れを疑うサインです。
エディタの検証はモードを意識する
エディタでの検証は、Use Asset Databaseだけで済ませないことにしました。
ビルド済みのbundleを使うモードでも確認します。
ただ、このモードにも注意点があります。
ビルド済みのbundleを読むので、古いbundleが残っていると、エディタで直した内容が反映されません。
「直したはずなのに変わらない」と悩む原因になります。
検証のたびに、今どのモードで動かしているかを意識するようにしています。
まとめ
本記事では、Addressablesのグループを追加したのにビルドに入らなかった原因が、AddressableAssetSettings.asset の登録行のコミット漏れだったという話をしてきました。
簡単に全体をまとめます。
- グループはm_GroupAssetsに登録されて初めてビルド対象になる
- Settingsの差分がHash行だけならコミットしない
- m_GroupAssetsやm_LabelTableに+行があればHash行ごとコミットする
- Use Asset Databaseでは登録漏れに気付けないのでbundleを使うモードでも確かめる
- bundleを使うモードは古いbundleを読むことがあるので検証時はモードを意識する
ノイズを避けるためのルールは便利です。
それでも、ルールで機械的に捨てていると、たまに混ざる大事な変更まで見落とします。
差分が出たファイルは、中身を一度だけでも眺める。
地味ですが、いちばん効く対策だと思います。
同じようにAddressablesで「エディタでは動くのに実機でロードできない」と悩んでいる方の参考になればうれしいです。
筆者のXをフォローしよう
- Unity 6000.3 / Addressables 2.x