[email protected]

## [1.16.8] - 2020-11-4 - Added internal naming option for the Bundled Asset Group Schema. Instead of using the full path, there are options to use the asset guid or the hashcode of the guid. These values are stable and wont change if the asset path changes, reducing the need to rebuild a bundle if paths change but contents do not. The internal ids stored in the content catalog will generally be shorter than asset paths - 32 bytes for the full guid, 8 bytes for the guid hash. - Added option to exclude sub catalog entries by file extension - Added options to exclude catalog entries for address, labels, and guids - Added option to optimize catalog size by extracting duplicated string in urls and file paths - Fixed issue where ResourceLocations were returning null for the ResourceType. - Added warning to build when an Addressable Group doesn't have any AddressableAssetGroupSchemas - Fixed issue where resource folder search was case sensitive for Mac and Linux - Fixed issue where warnings were getting logged incorrectly when marking an asset as Addressable using the checkbox in the inspector. - Add Yamato trigger for release testing & rework variables into metafile - Fixed issue where an AssetReference's cached asset is not reset when the underlying asset re-imports. - Fixed issue where we were still checking for CRC when a bundle was cached. - Fixed bug when using Play Mode Script "Use AssetDatabase (fastest)", and calling Addressables.LoadContentCatalogAsync would fail when it had not been cached.
needle-mirror · Mar 29, 2021 · c04df58 · c04df58
1 parent f752214
commit c04df58
Show file tree

Hide file tree

Showing 47 changed files with 1,410 additions and 516 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [1.16.8] - 2020-11-4
+- Added internal naming option for the Bundled Asset Group Schema.  Instead of using the full path, there are options to use the asset guid or the hashcode of the guid.  These values are stable and wont change if the asset path changes, reducing the need to rebuild a bundle if paths change but contents do not.  The internal ids stored in the content catalog will generally be shorter than asset paths - 32 bytes for the full guid, 8 bytes for the guid hash. 
+- Added option to exclude sub catalog entries by file extension
+- Added options to exclude catalog entries for address, labels, and guids
+- Added option to optimize catalog size by extracting duplicated string in urls and file paths
+- Fixed issue where ResourceLocations were returning null for the ResourceType.
+- Added warning to build when an Addressable Group doesn't have any AddressableAssetGroupSchemas
+- Fixed issue where resource folder search was case sensitive for Mac and Linux
+- Fixed issue where warnings were getting logged incorrectly when marking an asset as Addressable using the checkbox in the inspector.
+- Add Yamato trigger for release testing & rework variables into metafile
+- Fixed issue where an AssetReference's cached asset is not reset when the underlying asset re-imports.
+- Fixed issue where we were still checking for CRC when a bundle was cached.
+- Fixed bug when using Play Mode Script "Use AssetDatabase (fastest)", and calling Addressables.LoadContentCatalogAsync would fail when it had not been cached.
+
 ## [1.16.7] - 2020-10-21
 - Fixed issue where InvalidHandle errors were getting thrown if an operation failed with releaseDependenciesOnFailure turned on.
 - Fixed group build and load paths not being saved when editing multiple groups at once

diff --git a/Documentation~/AddressableAssetsAsyncOperationHandle.md b/Documentation~/AddressableAssetsAsyncOperationHandle.md
@@ -48,7 +48,11 @@ void Start() {
 ```
 public IEnumerator Start() {
     AsyncOperationHandle<Texture2D> handle = Addressables.LoadAssetAsync<Texture2D>("mytexture");
-    yield return handle;
+	
+	//if the handle is done, the yield return will still wait a frame, but we can skip that with an IsDone check
+	if(!handle.IsDone)
+		yield return handle;
+		
     if (handle.Status == AsyncOperationStatus.Succeeded) {
         Texture2D texture = handle.Result;
         // The texture is ready for use.

diff --git a/Documentation~/AddressablesAPI.md b/Documentation~/AddressablesAPI.md
@@ -5,14 +5,15 @@ uid: addressables-api
 
 This page exists in addition to the standard Addressable Assets [Scripting API documentation](xref:addressables-script-ref). The purpose of this expanded API documentation is to provide quick access and a deeper understanding of often-used or important API items, including code samples where relevant.
 
-* [LoadingAddressableAssets](LoadingAddressableAssets.md)
+* [BuildPlayerContent](BuildPlayerContent.md)
+* [DownloadDependenciesAsync](DownloadDependenciesAsync.md)
+* [ExceptionHandler](ExceptionHandler.md)
 * [InitializeAsync](InitializeAsync.md)
-* [TransformInternalId](TransformInternalId.md)
 * [InstantiateAsync](InstantiateAsync.md)
-* [DownloadDependenciesAsync](DownloadDependenciesAsync.md)
 * [LoadContentCatalogAsync](LoadContentCatalogAsync.md)
-* [UpdateCatalogs](UpdateCatalogs.md)
+* [LoadingAddressableAssets](LoadingAddressableAssets.md)
+* [LoadResourceLocationsAsync](LoadResourceLocations.md)
 * [LoadSceneAsync](LoadSceneAsync.md)
-* [ExceptionHandler](ExceptionHandler.md)
-* [BuildPlayerContent](BuildPlayerContent.md)
-* [LoadResourceLocationsAsync](LoadResourceLocations.md)
+* [TransformInternalId](TransformInternalId.md)
+* [UpdateCatalogs](UpdateCatalogs.md)
+
diff --git a/Documentation~/AddressablesFAQ.md b/Documentation~/AddressablesFAQ.md
@@ -0,0 +1,50 @@
+---
+uid:  addressables-faq
+---
+
+# Addressables FAQ
+
+### Is it better to have many small bundles or a few bigger ones?
+There are a few key factors that go into deciding how many bundles to generate.
+First, it's important to note that you control how many bundles you have both by how large your groups are, and by the groups' build settings.  "Pack Together" for example, creates one bundle per group, while "Pack Separately" creates many.  See [schema build settings for more information](xref:UnityEditor.AddressableAssets.Settings.GroupSchemas.BundledAssetGroupSchema.BundleMode).
+
+Once you know how to control bundle layout, the decision of how to set these up will be game specific.  Here are key pieces of data to help make that decision:
+
+Dangers of too many bundles:
+* Each bundle has memory overhead.  Details are [on the memory management page](MemoryManagement.md#assetbundle-memory-overhead). This is tied to a number of factors, outlined on that page, but the short version is that this overhead can be significant.  If you anticipate 100's or even 1000's of bundles loaded in memory at once, this could mean a noticeable amount of memory eaten up.
+* There are concurrency limits for downloading bundles.  If you have 1000's of bundles you need all at once, they cannot not all be downloaded at the same time.  Some number will be downloaded, and as they finish, more will trigger. In practice this is a fairly minor concern, so minor that you'll often be gated by the total size of your download, rather than how many bundles it's broken into.
+* Bundle information can bloat the catalog.  To be able to download or load catalogs, we store string-based information about your bundles.  1000's of bundles worth of data can greatly increase the size of the catalog.
+
+Dangers of too few bundles:
+* The UnityWebRequest (which we use to download) does not resume failed downloads.  So if a large bundle downloading and your user loses connection, the download is started over once they regain connection. 
+* Items can be loaded individually from bundles, but cannot be unloaded individually.  For example, if you have 10 materials in a bundle, load all 10, then tell Addressables to release 9 of them, all 10 will likely be in memory.  This is also covered [on the memory management page](MemoryManagement.md#when-is-memory-cleared).
+
+### What compression settings are best?
+Addressables provides three different options for bundle compression: Uncompressed, LZ4, and LZMA.  Generally speaking, LZ4 should be used for local content, and LZMA for remote, but more details are outlined below as there can be exceptions to this.  
+You can set the compression option using the Advanced settings on each group. Compression does not affect in-memory size of your loaded content. 
+* Uncompressed - This option is largest on disk, and generally fasted to load.  If your game happens to have space to spare, this option should at least be considered for local content.  A key advantage of uncompressed bundles is how they handle being patched.  If you are developing for a platform where the platform itself provides patching (such as Steam or Switch), uncompressed bundles provide the most accurate (smallest) patching.  Either of the other compression options will cause at least some bloat of patches.
+* LZ4 - If Uncompressed is not a viable option, then LZ4 should be used for all other local content.  This is a chunk-based compression which provides the ability to load parts of the file without needing to load it in its entirety. 
+* LZMA - LZMA should be used for all remote content, but not for any local content.  It provides the smallest bundle size, but is slow to load. If you were to store local bundles in LZMA you could create a smaller player, but load times would be significantly worse than uncompressed or LZ4. For downloaded bundles, we avoid the slow load time by recompressing the downloaded bundle when storing it in the asset bundle cache.  By default, bundles will be stored in the cache Uncompressed.  If you wish to compress the cache with LZ4, you can do so by creating a [`CacheInitializationSettings`](xref:UnityEditor.AddressableAssets.Settings.CacheInitializationSettings).  See [Initialization Objects](AddressableAssetsDevelopmentCycle.md#initialization-objects) for more information about setting this up. 
+
+Note that the hardware characteristics of a platform can mean that uncompressed bundles are not always the fastest to load.  The maximum speed of loading uncompressed bundles is gated by IO speed, while the speed of loading LZ4-compressed bundles can be gated by either IO speed or CPU, depending on hardware.  On most platforms, loading LZ4-compressed bundles is CPU bound, and loading uncompressed bundles will be faster. On platforms that have low IO speeds and high CPU speeds, LZ4 loading can be faster. It is always a good practice to run performance analysis to validate whether your game fits the common patterns, or needs some unique tweaking.
+
+More information on Unity's compression selection is available in the [Asset Bundle documentation](https://docs.unity3d.com/Manual/AssetBundles-Cache.html).  
+
+### Are there ways to miminize the catalog size?
+Currently there are two optimizations available.
+1. Compress the local catalog.  If your primary concern is how big the catalog is in your build, there is an option in the inspector for the top level settings of **Compress Local Catalog**. This option builds catalog that ships with your game into an asset bundle. Compressing the catalog makes the file itself smaller, but note that this does increase catalog load time.  
+2. Disable built-in scenes and Resources.  Addressables provides the ability to load content from Resources and from the built-in scenes list. By default this feature is on, which can bloat the catalog if you do not need this feature.  To disable it, select the "Built In Data" group within the Groups window (**Window** > **Asset Management** > **Addressables** > **Groups**). From the settings for that group, you can uncheck "Include Resources Folders" and "Include Build Settings Scenes". Unchecking these option only removes the references to those asset types from the Addressables catalog.  The content itself is still built into the player you create, and you can still load them via legacy API. 
+
+### What is addressables_content_state?
+After every content build of addressables, we produce an addressables_content_state.bin file, which is saved to the `Assets/AddressableAssetsData/<Platform>/` folder of your Unity project.
+This file is critical to our [content update workflow](ContentUpdateWorkflow.md). If you are not doing any content updates, you can completely ignore this file.
+If you are planning to do content updates, you will need the version of this file produced for the previous release. We recommend checking it into version control and creating a branch each time you release a player build.  More information is available on our [content update workflow page](ContentUpdateWorkflow.md).
+
+### What are possible scale implications?
+As your project grows larger, keep an eye on the following aspects of your assets and bundles:
+* Total bundle size - Historically Unity has not supported files larger than 4GB.  This has been fixed in some recent editor versions, but there can still be issues. It is recommended to keep the content of a given bundle under this limit for best compatibility across all platforms.  
+* Sub assets affecting UI performance. There is no hard limit here, but if you have many assets, and those assets have many sub-assets, it may be best to turn off sub-asset display. This option only affects how the data is displayed in the Groups window, and does not affect what you can and cannot load at runtime.  The option is available in the groups window under **Tools** > **Show Sprite and Subobject Addresses**.  Disabling this will make the UI more responsive.
+* Group hierarchy display.  Another UI-only option to help with scale is **Group Hierarchy with Dashes**.  This is available within the inspector of the top level settings. With this enabled, groups that contain dashes '-' in their names will display as if the dashes represented folder hierarchy. This does not affect the actual group name, or the way things are built.  For example, two groups called "x-y-z" and "x-y-w" would display as if inside a folder called "x", there was a folder called "y".  Inside that folder were two groups, called "x-y-z" and "x-y-w". This will not really affect UI responsiveness, but simply makes it easier to browse a large collection of groups. 
+* Bundle layout at scale.  For more information about how best to set up your layout, see the earlier question: [_Is it better to have many small bundles or a few bigger ones_](AddressablesFAQ.md#Is-it-better-t-have-many-small-bundles-or-a-few-bigger-ones)
+
+
diff --git a/Documentation~/LoadResourceLocations.md b/Documentation~/LoadResourceLocations.md
@@ -68,4 +68,92 @@ IEnumerator Start()
 
     Addressables.Release(handle);
 }
+```
+
+#### Sub-Objects
+Sub-Objects are a special case.  Locations for Sub-Objects are generated at runtime to keep bloat out of the content catalogs and improve runtime performance, such as entering Play Mode while using the Use Asset Database Playmode script.  This has implications when calling `LoadResourceLocationsAsync` with a Sub-Object key.  If the system is not aware of the desired Type then IResourceLocations is generated for each `Type` of Sub-Object detected.  If an AssetReference with a Sub-Object selection is not set, the system generates IResourceLocations for each Type of detected Sub-Object with the Address of the main object.
+
+For the following examples lets assume we have an FBX asset marked as Addressable that has a Mesh Sub-Object.
+
+##### When passing a string Key:
+```
+IEnumerator Start()
+{
+    AsyncOperationHandle<IList<IResourceLocation>> handle = Addressables.LoadResourceLocationsAsync("myFBXObject");
+	yield return handle;
+	
+	//This result contains 3 IResourceLocations.  One with Type GameObject, one with Type Mesh, and one with Type Material.  Since the string Key has no Type information we generate all possible IResourceLocations to match the request.
+	IList<IResourceLocation> result = handle.Result;
+	
+	//...
+	
+	Addressables.Release(handle);
+}
+```
+
+```
+IEnumerator Start()
+{
+    AsyncOperationHandle<IList<IResourceLocation>> handle = Addressables.LoadResourceLocationsAsync("myFBXObject[Mesh]");
+	yield return handle;
+	
+	//This result contains 3 IResourceLocations.  One with Type GameObject, one with Type Mesh, and one with Type Material.  Since the string Key has no Type information we generate all possible IResourceLocations to match the request.
+	IList<IResourceLocation> result = handle.Result;
+	
+	//...
+	
+	Addressables.Release(handle);
+}
+```
+
+```
+IEnumerator Start()
+{
+    AsyncOperationHandle<IList<IResourceLocation>> handle = Addressables.LoadResourceLocationsAsync("myFBXObject[Mesh]", typeof(Mesh));
+	yield return handle;
+	
+	//This result contains 1 IResourceLocation.  Since the Type parameter has a value passed in we can create the IResourceLocation.
+	IList<IResourceLocation> result = handle.Result;
+	
+	//...
+	
+	Addressables.Release(handle);
+}
+```
+
+##### When using an AssetReference:
+```
+//An AssetReference set to point to the Mesh Sub-Object of a FBX asset
+public AssetReference myFBXMeshReference;
+
+IEnumerator Start()
+{
+    AsyncOperationHandle<IList<IResourceLocation>> handle = Addressables.LoadResourceLocationsAsync(myFBXMeshReference);
+	yield return handle;
+	
+	//This result contains 1 IResourceLocation.  Since the AssetReference contains Type information about the Sub-Object, we can generate the appropriate IResourceLocation.
+	IList<IResourceLocation> result = handle.Result;
+	
+	//...
+	
+	Addressables.Release(handle);
+}
+```
+
+```
+//An AssetReference that is not set to point at a Sub-Object
+public AssetReference myFBXReference;
+
+IEnumerator Start()
+{
+    AsyncOperationHandle<IList<IResourceLocation>> handle = Addressables.LoadResourceLocationsAsync(myFBXReference);
+	yield return handle;
+	
+	//This result contains 3 IResourceLocation.  Since the AssetReference Sub-Object is not set we generate all possible IResourceLocations with the detected Sub-Object Types.
+	IList<IResourceLocation> result = handle.Result;
+	
+	//...
+	
+	Addressables.Release(handle);
+}
 ```
diff --git a/Documentation~/TableOfContents.md b/Documentation~/TableOfContents.md
@@ -45,21 +45,28 @@
        * [The Resource folders method](AddressableAssetsMigrationGuide.md#the-resource-folders-method)
        * [The AssetBundles method](AddressableAssetsMigrationGuide.md#the-assetbundles-method)
     * [Expanded API documentation](AddressablesAPI.md)
-        * [LoadingAddressableAssets](LoadingAddressableAssets.md)
+        * [BuildPlayerContent](BuildPlayerContent.md)
+        * [DownloadDependenciesAsync](DownloadDependenciesAsync.md)
+        * [ExceptionHandler](ExceptionHandler.md)
         * [InitializeAsync](InitializeAsync.md)
-        * [TransformInternalId](TransformInternalId.md)
         * [InstantiateAsync](InstantiateAsync.md)
-        * [DownloadDependenciesAsync](DownloadDependenciesAsync.md)
         * [LoadContentCatalogAsync](LoadContentCatalogAsync.md)
-        * [UpdateCatalogs](UpdateCatalogs.md)
-        * [LoadSceneAsync](LoadSceneAsync.md)
-        * [ExceptionHandler](ExceptionHandler.md)
-        * [BuildPlayerContent](BuildPlayerContent.md)
+        * [LoadingAddressableAssets](LoadingAddressableAssets.md)
         * [LoadResourceLocationsAsync](LoadResourceLocations.md)
+        * [LoadSceneAsync](LoadSceneAsync.md)
+        * [TransformInternalId](TransformInternalId.md)
+        * [UpdateCatalogs](UpdateCatalogs.md)
     * [Diagnostic Tools](DiagnosticTools.md)
         * [Build Layout](DiagnosticTools.md#build-layout-report)
         * [Build Profiling](DiagnosticTools.md#build-profiling)
         * [The Addressables Analyze tool](DiagnosticTools.md#the-addressables-analyze-tool)
             * [Using Analyze](DiagnosticTools.md#using-analyze)
             * [Provided Analyze rules](DiagnosticTools.md#provided-analyze-rules)
             * [Extending Analyze](DiagnosticTools.md#extending-analyze)
+	* [FAQ](AddressablesFAQ.md)
+		* [Many vs few bundles](AddressablesFAQ.md#Is-it-better-to-have-many-small-bundles-or-a-few-bigger-ones)
+		* [Best compression settings](AddressablesFAQ.md#What-compression-settings-are-best)
+		* [Minimize catlog size](AddressablesFAQ.md#Are-there-ways-to-miminize-the-catalog-size)
+		* [Addressables content state](AddressablesFAQ.md#What-is-addressables_content_state)
+		* [Scale implications](AddressablesFAQ.md#What-are-possible-scale-implications)
+