Quando integri l'importazione delle risorse, i giochi Unity possono accedere a pacchetti di asset utilizzando gli indirizzi o AssetBundles. Gli indirizzi sono la soluzione di distribuzione degli asset più recente e consigliata per i giochi creati con Unity 2019.4 o versioni successive, mentre AssetBundles supporta i pacchetti di asset in Unity 2017.4 e 2018.4.
Indirizzabili Unity
I giochi creati con Unity 2019.4 o versioni successive dovrebbero utilizzare Addressables per il caricamento degli asset su Android. Unity fornisce un'API Play Asset Delivery (PAD) per la gestione di pacchetti di asset Android tramite Addressables. Per informazioni sull'utilizzo di Indirizzabili, vedi quanto segue:
- Indirizzi per il pacchetto Android
- Guida PAD per Unity
- Documentazione di riferimento dell'API PAD per Unity
Utilizzare i file AssetBundle
I giochi creati con Unity 2017.4 e 2018.4 possono utilizzare i file AssetBundle per caricare asset su Android. I file Unity AssetBundle contengono asset serializzati che possono essere caricati dal motore Unity mentre l'app è in esecuzione. Questi file sono specifici della piattaforma (ad esempio, creati per Android) e possono essere utilizzati in combinazione con pacchetti di asset. Più comunemente, un file AssetBundle viene pacchettizzato in un unico pacchetto di asset, che utilizza lo stesso nome di AssetBundle. Se vuoi maggiore flessibilità nella creazione di un pacchetto di asset, configuralo utilizzando l'API.
In fase di esecuzione, utilizza la classe Play Asset Delivery for Unity per recuperare un AssetBundle incluso in un pacchetto di asset.
Prerequisiti
Scarica l'ultima release del plug-in Unity di Play Asset Delivery dai pacchetti Google per Unity.
Configura AssetBundles utilizzando l'interfaccia utente
Configura ogni AssetBundle in un pacchetto di asset:
- Seleziona Google > Android App Bundle > Impostazioni di pubblicazione degli asset.
- Per selezionare cartelle che contengono direttamente i file AssetBundle, fai clic su Aggiungi cartella.
Per ogni bundle, imposta la modalità di invio su Ora di installazione, Rapida Follow o On demand. Risolvi eventuali errori o dipendenze e chiudi la finestra.
Seleziona Google > Build Android App Bundle per creare l'app bundle.
(Facoltativo) Configura l'app bundle in modo che supporti diversi formati di compressione delle texture.
Configurare asset pack utilizzando l'API
Puoi configurare la pubblicazione degli asset tramite script di editor che possono essere eseguiti come parte di un sistema di compilazione automatizzato.
Utilizza la classe AssetPackConfig per definire quali asset includere nella build di un Android App Bundle, così come la modalità di invio degli asset. Questi pacchetti di asset non devono necessariamente
contenere un AssetBundle.
public void ConfigureAssetPacks {
// Creates an AssetPackConfig with a single asset pack, named
// examplePackName, containing all the files in path/to/exampleFolder.
var assetPackConfig = new AssetPackConfig();
assetPackConfig.AddAssetsFolder("examplePackName",
"path/to/exampleFolder",
AssetPackDeliveryMode.OnDemand);
// Configures the build system to use the newly created assetPackConfig when
// calling Google > Build and Run or Google > Build Android App Bundle.
AssetPackConfigSerializer.SaveConfig(assetPackConfig);
// Alternatively, use BundleTool.BuildBundle to build an App Bundle from script.
BuildBundle(new buildPlayerOptions(), assetPackConfig);
}
Puoi anche utilizzare il metodo
BuildBundle
statico nella classe Bundletool per generare un Android App Bundle con pacchetti di
asset, in base a
BuildPlayerOptions
e
AssetPackConfig.
Per un tutorial guidato, consulta la pagina Utilizzare Play Asset Delivery nel codelab per i giochi Unity.
Eseguire l'integrazione con l'API Play Asset Delivery Unity
L'API Play Asset Delivery Unity offre la funzionalità per richiedere pacchetti di asset, gestire i download e accedere agli asset. Assicurati prima di aggiungere il plug-in Unity al tuo progetto.
Le funzioni che utilizzi nell'API dipendono da come hai creato i pacchetti di asset.
Se hai creato pacchetti di asset utilizzando l'interfaccia utente dei plug-in, seleziona pacchetti di asset configurati per i plug-in.
Se hai creato pacchetti di asset utilizzando l'API (o la UI dei plug-in), seleziona pacchetti di asset configurati per API.
Puoi implementare l'API in base al tipo di pubblicazione del pacchetto di asset a cui vuoi accedere. Questi passaggi sono mostrati nel seguente grafico di flusso.
Figura 1. Diagramma di flusso per l'accesso ai pacchetti di asset
Recupera AssetBundle
Importa la
raccolta di Asset Delivery di Google Play
e chiama il metodo
RetrieveAssetBundleAsync()
per recuperare un AssetBundle.
using Google.Play.AssetDelivery; // Loads the AssetBundle from disk, downloading the asset pack containing it if necessary. PlayAssetBundleRequest bundleRequest = PlayAssetDelivery.RetrieveAssetBundleAsync(asset-bundle-name);
Consegna al momento dell'installazione
I pacchetti di asset configurati come install-time sono immediatamente disponibili al lancio
dell'app. Per caricare una scena da AssetBundle puoi utilizzare quanto segue:
AssetBundle assetBundle = bundleRequest.AssetBundle; // You may choose to load scenes from the AssetBundle. For example: string[] scenePaths = assetBundle.GetAllScenePaths(); SceneManager.LoadScene(scenePaths[path-index]);
Distribuzione rapida e on demand
Queste sezioni riguardano i pacchetti di asset fast-follow e on-demand.
Verifica lo stato
Ogni pacchetto di asset viene archiviato in una cartella separata nella memoria interna dell'app.
Utilizza il metodo isDownloaded() per determinare se un pacchetto di asset è già stato scaricato.
Monitorare il download
Esegui una query sull'oggetto PlayAssetBundleRequest per monitorare lo stato della richiesta:
// Download progress of request, between 0.0f and 1.0f. The value will always be
// 1.0 for assets delivered as install-time.
// NOTE: A value of 1.0 will only signify the download is complete. It will still need to be loaded.
float progress = bundleRequest.DownloadProgress;
// Returns true if:
// * it had either completed the download, installing, and loading of the AssetBundle,
// * OR if it has encountered an error.
bool done = bundleRequest.IsDone;
// Returns status of retrieval request.
AssetDeliveryStatus status = bundleRequest.Status;
switch(status) {
case AssetDeliveryStatus.Pending:
// Asset pack download is pending - N/A for install-time assets.
case AssetDeliveryStatus.Retrieving:
// Asset pack is being downloaded and transferred to app storage.
// N/A for install-time assets.
case AssetDeliveryStatus.Available:
// Asset pack is downloaded on disk but NOT loaded into memory.
// For PlayAssetPackRequest(), this indicates that the request is complete.
case AssetDeliveryStatus.Loading:
// Asset pack is being loaded.
case AssetDeliveryStatus.Loaded:
// Asset pack has finished loading, assets can now be loaded.
// For PlayAssetBundleRequest(), this indicates that the request is complete.
case AssetDeliveryStatus.Failed:
// Asset pack retrieval has failed.
case AssetDeliveryStatus.WaitingForWifi:
// Asset pack retrieval paused until either the device connects via Wi-Fi,
// or the user accepts the PlayAssetDelivery.ShowCellularDataConfirmation dialog.
default:
break;
}
Download di grandi dimensioni
I pacchetti di asset di dimensioni superiori a 150 MB possono essere scaricati automaticamente, ma solo tramite Wi-Fi. Se
l'utente non è connesso al Wi-Fi, lo stato di PlayAssetBundleRequest viene impostato su
AssetDeliveryStatus.WaitingForWifi
e il download viene sospeso. In questo caso, attendi che il dispositivo si connetta alla rete Wi-Fi, riprenda il download oppure richiedi all'utente l'approvazione per scaricare il pacchetto tramite rete cellulare.
if(bundleRequest.Status == AssetDeliveryStatus.WaitingForWifi) {
var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation();
yield return userConfirmationOperation;
switch(userConfirmationOperation.GetResult()) {
case ConfirmationDialogResult.Unknown:
// userConfirmationOperation finished with an error. Something went
// wrong when displaying the prompt to the user, and they weren't
// able to interact with the dialog. In this case, we recommend
// developers wait for Wi-Fi before attempting to download again.
// You can get more info by calling GetError() on the operation.
case ConfirmationDialogResult.Accepted:
// User accepted the confirmation dialog - download will start
// automatically (no action needed).
case ConfirmationDialogResult.Declined:
// User canceled or declined the dialog. Await Wi-Fi connection, or
// re-prompt the user.
default:
break;
}
}
Annullare una richiesta (solo on demand)
Se devi annullare la richiesta prima che gli AssetBundles vengano caricati in memoria, chiama il metodo AttemptCancel() sull'oggetto PlayAssetBundleRequest:
// Will only attempt if the status is Pending, Retrieving, or Available - otherwise
// it will be a no-op.
bundleRequest.AttemptCancel();
// Check to see if the request was successful by checking if the error code is Canceled.
if(bundleRequest.Error == AssetDeliveryErrorCode.Canceled) {
// Request was successfully canceled.
}
Richiedi pacchetti di asset in modo asincrono
Nella maggior parte dei casi, devi utilizzare le Coroutine per richiedere pacchetti di asset in modo asincrono e monitorare l'avanzamento, come mostrato di seguito:
private IEnumerator LoadAssetBundleCoroutine(string assetBundleName) {
PlayAssetBundleRequest bundleRequest =
PlayAssetDelivery.RetrieveAssetBundleAsync(assetBundleName);
while (!bundleRequest.IsDone) {
if(bundleRequest.Status == AssetDeliveryStatus.WaitingForWifi) {
var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation();
// Wait for confirmation dialog action.
yield return userConfirmationOperation;
if((userConfirmationOperation.Error != AssetDeliveryErrorCode.NoError) ||
(userConfirmationOperation.GetResult() != ConfirmationDialogResult.Accepted)) {
// The user did not accept the confirmation - handle as needed.
}
// Wait for Wi-Fi connection OR confirmation dialog acceptance before moving on.
yield return new WaitUntil(() => bundleRequest.Status != AssetDeliveryStatus.WaitingForWifi);
}
// Use bundleRequest.DownloadProgress to track download progress.
// Use bundleRequest.Status to track the status of request.
yield return null;
}
if (bundleRequest.Error != AssetDeliveryErrorCode.NoError) {
// There was an error retrieving the bundle. For error codes NetworkError
// and InsufficientStorage, you may prompt the user to check their
// connection settings or check their storage space, respectively, then
// try again.
yield return null;
}
// Request was successful. Retrieve AssetBundle from request.AssetBundle.
AssetBundle assetBundle = bundleRequest.AssetBundle;
Per ulteriori informazioni sulla gestione degli errori, consulta l'elenco di
AssetDeliveryErrorCodes.
Altri metodi dell'API Play Core
Di seguito sono riportati alcuni metodi API aggiuntivi che potresti voler utilizzare nella tua app.
Controlla le dimensioni di download
Controlla le dimensioni di un AssetBundle effettuando una chiamata asincrona a Google Play e impostando un metodo di callback per il completamento dell'operazione:
public IEnumerator GetDownloadSize() {
PlayAsyncOperation<long> getSizeOperation =
PlayAssetDelivery.GetDownloadSize(assetPackName);
yield return getSizeOperation;
if(operation.Error != AssetDeliveryErrorCode.NoError) {
// Error while retrieving download size.
} else {
// Download size is given in bytes.
long downloadSize = operation.GetResult();
}
}
Rimuovi AssetBundles
Puoi rimuovere gli AssetBundles Fast-follow e on demand che non sono attualmente caricati in memoria. Effettua la seguente chiamata asincrona e imposta un metodo di callback per il completamento:
PlayAsyncOperation<string> removeOperation = PlayAssetDelivery.RemoveAssetPack(assetBundleName);
removeOperation.Completed += (operation) =>
{
if(operation.Error != AssetDeliveryErrorCode.NoError) {
// Error while attempting to remove AssetBundles.
} else {
// Files were deleted OR files did not exist to begin with.
}
};
Passaggio successivo
Testa la pubblicazione degli asset in locale e su Google Play.