Google Play Asset Delivery のリファレンス

Google Play Asset Delivery (GooglePAD) は、デバイスにアプリケーションをインストールした後でアセット パックを配信する Google Play ストアのソリューションです。このソリューションは Android App Bundle 配布形式と一緒に使用することを前提にしています。App Bundle がカスタマイズ済みの .apk をエンド ユーザーに配布して、初期インストールでコードやバイナリの処理するのに対して、Play Asset Delivery システムは、モデル、テクスチャ、サウンド、シェーダ、その他の大きなアセット ファイルを .apk とは別に提供します。この機能により Google Play で配布されるアプリは、必要に応じてコンテンツを配信することでコンテンツが占めるスペースを管理できます。

Google Play Asset Delivery の一般情報については、Android 公式ドキュメント を参照してください。

Unreal Engine 以降はプラグインで GooglePAD 統合を提供しており、このシステムを作成したプロジェクトに簡単に実装することが可能です。このプラグインが提供する関数ライブラリにより、ダウンロードを管理して Play Asset Delivery システムから情報をリクエストする、呼び出しを利用できます。また、UGooglePADFunctionLibrary は C++ と Blueprint の両方で使用できます。

Android App Bundle の内容に関する詳細は「Android プロジェクトのパッケージ化」を参照してください。

GooglePAD プラグインを有効化する

GooglePAD プラグインはデフォルトで有効になっていますが、Unreal Editor の [Plugins (プラグイン)] ウィンドウの [Android] セクションで無効にすることもできます。GooglePAD を使用するには、パッケージ化の形式として Android App Bundles を使用する必要があります。

このプラグインを完全に有効化するには [Project Settings (プロジェクト設定)] を開いて [Plugins (プラグイン)] > [GooglePAD] > [Packaging] の順に移動します。[Enable Plugin] チェックボックスをクリックすると、Android プロジェクトの起動時にこのモジュールが使用可能になります。

インストール時 アセットに GooglePAD を使用する場合は、[Platforms (プラットフォーム)] > [Android] > [APK Packaging] の順に移動して、[Package Data inside APK (APK 内のゲーム データをパッケージ化)] を無効にする必要もあります。メインの .obb ファイルはその後インストール時アセット パックとして自動的に供給されます。

クリックして画像を拡大します

アセット パックを作成する

GooglePAD の Asset packs は Android App Bundle ビルド内にパッケージ化され、アップロード時に Google Play Store によって管理されます。このセクションではご使用の App Bundle に含むアセット パックのパッケージ化および整理方法について説明します。

アセットパックの配信モード

チャンク とは外部アセットを管理するための Unreal Engine の形式です。チャンク 0 はゲームの基本インストールを表し、その他すべてのチャンクはゲームのメイン インストール外のアセットを含む .pak ファイルです。

Google PAD を使用するには、ゲームのアセットをチャンクにグループ化し、これらのチャンクをアセット パックにグループかしなければなりません。使用する配信モードに基づいてGoogle Play Asset Delivery は以下のアセットパックの配信モードをサポートします。

アプリケーションにつき最大 50 までアセットパックを作ることができます。1 プロジェクトにつき Install-Time アセットパックと Fast-Follow アセットパックはそれぞれ 1 つしか作成できませんが、On-Demand アセットパックは 50 までであれば好きなだけ作成することができます。

チャンクを作成する

[Project Settings (プロジェクト設定)] をから [Project] > [Packaging] を開いて [Generate Chunks (チャンクを作成する)] が有効であることを確認します。

アセット マネージャ または プライマリ アセット ラベル を使ってチャンク内でアセットを整理することができます。詳細については、「クックとチャンク」を参照してください。

特定のチャンクに属するアセットを指定すると、プロジェクトを パッケージ化 することでチャンクが .pak ファイルで出力されます。このファイルは「Saved\StagedBuilds[PlatformName][ProjectName]\Content\Paks」にあります。

クリックして画像を拡大

App Bundle Build にチャンクをインクルードする

Play Asset Delivery の各配信モードでは、App Bundles にチャンクを取り込むための要求事項が異なります。

Install-Time アセットの場合、何も変更する必要はありません。

Fast-Follow アセット、または On-Demand アセットの場合、インクルードする .pak ファイルを選択して、それをプロジェクトの「Build/Android/gradle/assetpacks」に移動します。配信モードはそれぞれ異なるサブフォルダを持ちます。

• Fast-Follow アセットパックの場所は「Build/Android/gradle/assetpacks/fast-follow/[assetpackname]/src/main/assets」です。

• On-Demand アセットパックの場所は「Build/Android/gradle/assetpacks/on-demand/[assetpackname]/src/main/assets」です。

[assetpackname] を、チャンクがバンドルされるアセットパックの名前に置き換えます。異なる .pak ファイルのセットで複数の異なる名前のついたアセットパックを作成することができます。ただし、アセットパックの名前は一意でなければなりません。また、fast-follow と on-demand 間での再利用はできません。この名前は API でアセットパックをクエリする際に使用する名前になります。

最後に、以下のコードを含むアセットパック フォルダに build.gradle ファイルを追加する必要があります。

	apply plugin: 'com.android.asset-pack'

	def fileparts = projectDir.absolutePath.replaceAll('\\\\', '/').tokenize('/')
	def assetPackName = fileparts[fileparts.size()-1]
	def assetPackType = fileparts[fileparts.size()-2]

	assetPack {
		packName = assetPackName
		dynamicDelivery {
			deliveryType = assetPackType
			instantDeliveryType = assetPackType
		}
	}

Copy full snippet

apply plugin: 'com.android.asset-pack' def fileparts = projectDir.absolutePath.replaceAll('\\\\', '/').tokenize('/') def assetPackName = fileparts[fileparts.size()-1] def assetPackType = fileparts[fileparts.size()-2] assetPack { packName = assetPackName dynamicDelivery { deliveryType = assetPackType instantDeliveryType = assetPackType } }

これらの要求事項を満たした後に、プロジェクトを app buncle として再度パッケージ化すると、ビルド内にこれらのアセットパックがそれぞれインクルードされます。When you upload the App Bundle to the Google Play Store, the asset packs will be available for download using the GooglePAD API.

このワークフローは Unreal Engine 4.26 で効率的に再編されます。

OBB ファイルからチャンクを取り除く

デフォルトでは、.pak ファイルはプロジェクトと一緒に生成される OBB ファイルに含まれています。それらを除外するには、 DefaultEngine.ini ファイルを開き、Android ランタイム設定の OBB フィルターを使用してフィルターする必要があります。

	[/Script/AndroidRuntimeSettings.AndroidRuntimeSettings]
	+ObbFilters="-*pakchunk1*"
	+ObbFilters="-*pakchunk2*"
	+ObbFilters="-*pakchunk3*"
	+ObbFilters="-*pakchunk4*"
	+ObbFilters="-*pakchunk5*"
	+ObbFilters="-*pakchunk6*"
	+ObbFilters="-*pakchunk7*"
	+ObbFilters="-*pakchunk8*"
	+ObbFilters="-*pakchunk9*"

Copy full snippet

[/Script/AndroidRuntimeSettings.AndroidRuntimeSettings] +ObbFilters="-*pakchunk1*" +ObbFilters="-*pakchunk2*" +ObbFilters="-*pakchunk3*" +ObbFilters="-*pakchunk4*" +ObbFilters="-*pakchunk5*" +ObbFilters="-*pakchunk6*" +ObbFilters="-*pakchunk7*" +ObbFilters="-*pakchunk8*" +ObbFilters="-*pakchunk9*"

上記の例では、OBB フィルターは、提供されたテキストのいずれかを含むすべての .pak ファイルをキャッチします。たとえば、 + ObbFilters ="-* pakchunk1 * " は、名前に「pakchunk1」が含まれているすべての pak ファイルを省略します。

API リファレンス

次のセクションでは、GooglePAD 関数ライブラリで利用できる関数と、その使用方法を詳しく説明します。

リクエストとエラー ハンドリング

GooglePAD 関数ライブラリのリクエストはすべて EGooglePADErrorCode を返し、これは操作が成功したかどうかを表します。そして失敗した場合は、リクエストを完了できなかった特定のエラーを示します。発生する可能性があるエラー コードを以下に示します。

この戻り値以外にも、リクエスト関数には必要な情報を提供する出力変数があります。結果が AssetPack_NO_ERROR の場合は、通常どおり提供された情報で続行できます。それ以外の場合は、フロー制御を使用して提供されたエラー コードに適切に対処する必要があります。

ダウンロードしたファイルの場所を取得する

関数 GetAssetPackLocation は、ダウンロードしたアセット パックの場所を取得して、関連する情報とともにローカルにキャッシュします。そのアセットが利用可能なときは、キャッシュした情報へのアクセスに必要に応じて使用する整数のハンドルを出力します。

GetAssetsPath を呼び出して場所ハンドルを提供すると、必要なアセット パックのアセット パスを含む文字列を出力します。また、GetStorageMethod は EGooglePADStorageMethod を出力し、これはアセット パックをユーザーのデバイスにストアした方法を示します。アセットのパスとストア方法を把握したら、適切な呼び出しを使用してそのアセットを利用できます。

可能なストア方法を以下に示します。

上記の情報が必要なくなったら、場所ハンドルを ReleaseAssetPackLocation に渡してキャッシュした場所の情報を解放する必要があります。

GetAssetPackLocation が AsetPack_UNAVAILABLE や AssetPack_DOWNLOAD_NOT_FOUND のエラー コードを返した場合は目的のアセット パックは利用できないため、ダウンロードが必要です。

アセット パックに関する情報をリクエストする

関数 RequestInfo はアセット パック名 TArray を受け取って、現在のステータスを表す EGooglePADErrorCode を返します。RequestInfo はダウンロードを開始する上で必須ではありませんが、リモートのアセット パックが有効かどうかの判断に利用できます。

ダウンロードをリクエストまたはキャンセルする

関数 RequestDownload は、ダウンロードするアセット パック名を表す文字列 TArray を受け取り、リモート サービスにリクエストを送信して対象のアセット パックのダウンロードを開始します。RequestDownload がエラーを示しない場合は、アセット パックをダウンロードして非同期にバックグラウンドでアプリに転送します。

これは非同期の機能なので、RequestDownload 関数は、リクエストが成功したかどうかを表すエラー コードを除いて、ダウンロードするアセット パックについて情報を返しません。ダウンロードの現在のステータスを確認するには、以下の「ダウンロードのステータスを監視する」セクションに詳述している機能を使用する必要があります。その後ダウンロードが完了したら、GetAssetPackLocation を使用してアセット パック自体を利用します。

また、関数 CancelDownload はアセット パック名のリストを使用して、指定したアセット パックのダウンロードをキャンセルします。

携帯電話データ通信のステータスを取得する

関数 ShowCellularDataConfirmation は、携帯電話ネットワークを使用してデータをダウンロードするかどうかをユーザーに確認します。この確認を既に行っている場合は、GetShowCellularDataConfirmationStatus を使用してユーザーがダウンロードを承認しているかどうかを示す EGooglePADCellularDataConfirmStatus を取得できます。

この結果が AssetPack_CONFIRM_UNKNOWN や AssetPack_CONFIRM_PENDING の場合はまだユーザーが承認していないことを表し、アプリケーションは承認されるまで待つ必要があります。

この結果が AssetPack_CONFIRM_USER_CANCELLED の場合はユーザーが携帯電話データ通信の使用を許可していないことを表し、この時点でダウンロードしてはいけません。

この結果が AssetPack_CONFIRM_USER_APPROVED の場合は、ユーザーが携帯電話データ通信の使用を明示的に承認しているのでダウンロードを続行できます。さらに、この関数が AssetPack_NETWORK_UNRESTRICTED の結果で EGooglePADErrorCode を返す場合は、ユーザーが Wi-Fi ネットワークを利用できるため携帯電話データ通信を使用する必要がなく、さらにこの機能を確認せずにダウンロードできます。

ダウンロードのステータスを監視する

GetDownloadState はアセット パックのダウンロード ステータスをローカルにキャッシュして、このキャッシュ済み情報にアクセスするためのダウンロード ハンドルを返します。この関数は、ダウンロードするアセット パック名を受け取り、そのハンドルを整数として出力します。このダウンロード ハンドルをキャッシュしておくことでダウンロードを引き続き監視できます。そうしない場合はダウンロード ハンドルの再取得が必要です。

有効なダウンロード ハンドルを使用して GetDownloadStatus を呼び出すことで、必要なアセット パックのステータスを EGooglePADDownloadStatus として取得できます。この列挙型はダウンロードのステータスであり、以下に示す可能な状態のいずれかを表します。

ダウンロード ステータスのハンドルとともに GetBytesDownloaded を呼び出すことで、ユーザーのデバイスに現在ダウンロード済みのバイト数を取得できます。一方、GetTotalBytesToDownload はダウンロードする対象の合計サイズを返します。

ダウンロードのステータス情報が必要なくなったら ReleaseDownloadState を呼び出してハンドルを提供し、メモリからキャッシュ済みのダウンロード情報を解放する必要があります。

アセット パックを削除する

関数 RequestRemoval にアセット パック名を渡すことで、この指定したアセット パックをユーザーのデバイスから非同期で削除します。このアセット パックを削除するステータスは上記の GetDownloadStatus で監視できます。

推奨する実装方法

GooglePAD API の実装は、ダウンロードの状態によって異なるサイクルとしてモデル化できます。

カスタムの GameState クラスでソリューションを実装すると、シーンやゲーム モードを変更してもダウンロードを引き続き追跡できます。他にも、起動時にロードするフロントエンド ゲーム モードにソリューションを実装して、ゲームの開始前に必要なパッチや更新を実行することが可能です。なお、ソリューションの正確な詳細はアセットを更新するプロジェクト固有のニーズにより異なります。