Documentation

Editor/Build/DataBuilders/BuildScriptPackedMultiCatalogMode.cs

@@ -13,7 +13,7 @@ namespace UnityEditor.AddressableAssets.Build.DataBuilders
 	/// <summary>
 	/// Build script used for player builds and running with bundles in the editor, allowing building of multiple catalogs.
 	/// </summary>
-	[CreateAssetMenu(fileName = "BuildScriptPackedMultiCatalog.asset", menuName = "Addressables/Content Builders/Multi-Catalog")]
+	[CreateAssetMenu(fileName = "BuildScriptPackedMultiCatalog.asset", menuName = "Addressables/Content Builders/Multi-Catalog Build Script")]
 	public class BuildScriptPackedMultiCatalogMode : BuildScriptPackedMode, IMultipleCatalogsBuilder
 	{
 		/// <summary>
@@ -31,7 +31,7 @@ private static void FileMoveOverwrite(string src, string dst)
 		}
 
 		[SerializeField]
-		private List<ContentCatalogGroup> additionalCatalogs = new List<ContentCatalogGroup>();
+		private List<ExternalCatalogSetup> externalCatalogs = new List<ExternalCatalogSetup>();
 
 		private readonly List<CatalogSetup> catalogSetups = new List<CatalogSetup>();
 
@@ -40,10 +40,10 @@ public override string Name
 			get { return base.Name + " - Multi-Catalog"; }
 		}
 
-		public List<ContentCatalogGroup> AdditionalCatalogs
+		public List<ExternalCatalogSetup> ExternalCatalogs
 		{
-			get { return additionalCatalogs; }
-			set { additionalCatalogs = value; }
+			get { return externalCatalogs; }
+			set { externalCatalogs = value; }
 		}
 
 		protected override List<ContentCatalogBuildInfo> GetContentCatalogs(AddressablesDataBuilderInput builderInput, AddressableAssetsBuildContext aaContext)
@@ -53,7 +53,7 @@ protected override List<ContentCatalogBuildInfo> GetContentCatalogs(Addressables
 
 			// Prepare catalogs
 			var defaultCatalog = new ContentCatalogBuildInfo(ResourceManagerRuntimeData.kCatalogAddress, builderInput.RuntimeCatalogFilename);
-			foreach (ContentCatalogGroup catalogContentGroup in additionalCatalogs)
+			foreach (ExternalCatalogSetup catalogContentGroup in externalCatalogs)
 			{
 				if (catalogContentGroup != null)
 				{
@@ -169,14 +169,14 @@ public override void ClearCachedData()
 		{
 			base.ClearCachedData();
 
-			if ((additionalCatalogs == null) || (additionalCatalogs.Count == 0))
+			if ((externalCatalogs == null) || (externalCatalogs.Count == 0))
 			{
 				return;
 			}
 
 			// Cleanup the additional catalogs
 			AddressableAssetSettings settings = AddressableAssetSettingsDefaultObject.Settings;
-			foreach (ContentCatalogGroup additionalCatalog in additionalCatalogs)
+			foreach (ExternalCatalogSetup additionalCatalog in externalCatalogs)
 			{
 				string buildPath = settings.profileSettings.EvaluateString(settings.activeProfileId, additionalCatalog.BuildPath);
 				if (!Directory.Exists(buildPath))
@@ -195,7 +195,7 @@ public override void ClearCachedData()
 
 		private class CatalogSetup
 		{
-			public readonly ContentCatalogGroup CatalogContentGroup = null;
+			public readonly ExternalCatalogSetup CatalogContentGroup = null;
 
 			/// <summary>
 			/// The catalog build info.
@@ -215,7 +215,7 @@ public bool Empty
 				get { return BuildInfo.Locations.Count == 0; }
 			}
 
-			public CatalogSetup(ContentCatalogGroup buildCatalog)
+			public CatalogSetup(ExternalCatalogSetup buildCatalog)
 			{
 				this.CatalogContentGroup = buildCatalog;
 				BuildInfo = new ContentCatalogBuildInfo(buildCatalog.CatalogName, buildCatalog.CatalogName + ".json");

Editor/Build/DataBuilders/ContentCatalogGroup.cs → Editor/Build/DataBuilders/ExternalCatalogSetup.cs

@@ -8,18 +8,18 @@
 namespace UnityEditor.AddressableAssets.Build.DataBuilders
 {
 	/// <summary>
-	/// Separate catalog for assigned asset groups.
+	/// Separate catalog for the assigned asset groups.
 	/// </summary>
-	[CreateAssetMenu(menuName = "Addressables/new Catalog Content Group", fileName = "NewContentCatalogGroup")]
-	public class ContentCatalogGroup : ScriptableObject
+	[CreateAssetMenu(menuName = "Addressables/new External Catalog", fileName = "newExternalCatalogSetup")]
+	public class ExternalCatalogSetup : ScriptableObject
 	{
 		[SerializeField, Tooltip("Assets groups that belong to this catalog. Entries found in these will get extracted from the default catalog.")]
 		private List<AddressableAssetGroup> assetGroups = new List<AddressableAssetGroup>();
 		[SerializeField, Tooltip("Build path for the produced files associated with this catalog.")]
 		private string buildPath = string.Empty;
 		[SerializeField, Tooltip("Runtime load path for assets associated with this catalog.")]
 		private string runtimeLoadPath = string.Empty;
-		[SerializeField, Tooltip("Catalog name.")]
+		[SerializeField, Tooltip("Catalog name. This will also be the name of the exported catalog file.")]
 		private string catalogName = string.Empty;
 
 		public string CatalogName

Editor/Build/DataBuilders/IMultipleCatalogsBuilder.cs

@@ -4,7 +4,7 @@ namespace UnityEditor.AddressableAssets.Build.DataBuilders
 {
 	public interface IMultipleCatalogsBuilder
 	{
-		List<ContentCatalogGroup> AdditionalCatalogs
+		List<ExternalCatalogSetup> ExternalCatalogs
 		{
 			get; set;
 		}

Editor/Settings/AddressableAssetSettings.cs

@@ -1364,6 +1364,8 @@ void Validate()
 				m_DataBuilders.Add(CreateScriptAsset<BuildScriptPackedPlayMode>());
 				m_DataBuilders.Add(CreateScriptAsset<BuildScriptPackedMode>());
 				m_DataBuilders.Add(CreateScriptAsset<BuildScriptPackedMultiCatalogMode>());
+
+				m_ActivePlayerDataBuilderIndex = 4;
 			}
 
 			if (ActivePlayerDataBuilder != null && !ActivePlayerDataBuilder.CanBuildData<AddressablesPlayerBuildResult>())

readme.md

@@ -1 +1,88 @@
-Addressable Assets info placeholder
+# Addressables - Multi-Catalog
+
+The Addressables package by Unity provides a novel way of managing and packing assets for your build. It replaces the Asset Bundle system, and in certain ways, also seeks to dispose of the Resources folder.
+
+This variant forked from the original Addressables-project adds support for building your assets across several catalogs in one go and provides several other benefits, e.g. reduced build times and build size, as well as keeping the buildcache intact.
+
+## The problem
+
+A frequently recurring question is:
+
+> Can Addressables be used for DLC bundles/assets?
+
+The answer to that question largely depends on how you define what DLC means for your project, but for clarity's sake, let's define it this way:
+
+> A package that contains assets and features to expand the base game. Such a package holds unique assets that _may_ rely on assets already present in the base game.
+
+So, does Addressables support DLC packages as defined above? Yes, it's supported, but in a very crude and inefficient way.
+
+In the _vanilla_ implementation of Addressables, only one content catalog file is built at a time, and only the assets as defined to be included in the current build will be packed and saved. Any implicit dependency of an asset will get included in that build too, however. This creates several major problems:
+
+* Each build (one for the base game, and one for each DLC package) will include each and every asset it relies on. This is expected for the base game, but not for the DLC package. This essentially creates unnecessary large DLC packages, and in the end, your running game will include the same assets multiple times on the player's system, and perhaps even in memory at runtime.
+* No build caching can be used, since each build done for a DLC package is considered a whole new build for the Addressables system, and will invalidate any prior caching done. This significantly increases build times.
+* Build caching and upload systems as those used by Steam for example, can't fully differentiate between the changes properly of subsequent builds. This results in longer and larger uploads, and consequently, in bigger updates for players to download.
+
+## The solution
+
+The solution comes in the form of performing the build process of the base game and all DLC packages in one step. In essence, what this implementation does is, have the Addressables build-pipeline perform one large build all all assets tracked for the base game and each of its DLC packages, and afterwards, extract the contents per defined DLC package and create a separate content catalog for each of them. Finally, Addressables creates the final content catalog file for the left-over asset groups, those that remain for the base game.
+
+## Installation
+
+This package is best installed using Unity's Package Manager. Fill in the URL found below in the package manager's input field for git-tracked packages:
+
+> https://github.com/juniordiscart/com.unity.addressables.git
+
+**Note**: this repository does not track every available version of the vanilla Addressables package. It's only kept up-to-date sporadically.
+
+### Updating a vanilla installation
+
+When you've already set up Addressables in your project and adjusted the settings to fit your project's needs, it might be cumbersome to set everything back. In that case, it might be better to update your existing settings with the new objects rather than starting with a clean slate:
+
+1. Remove the currently tracked Addressables package from the Unity Package manager and track this version instead as defined by the [Installation section](#installation). However, __don't delete__ the `Assets/AddressableAssetsData` folder from your project!
+
+2. In your project's `Assets/AddressableAssetsData/DataBuilders` folder, create a new 'multi-catalog' data builder:
+
+   > Create → Addressables → Content Builders → Multi-Catalog Build Script
+
+   ![Create multi-catalog build script](Documentation~/images/multi_catalogs/CreateDataBuilders.png)
+
+3. Select your existing Addressable asset settings object, navigate to the `Build and Play Mode Scripts` property and add your newly created multi-catalog data builder to the list.
+
+   ![Assign data builder to Addressable asset settings](Documentation~/images/multi_catalogs/AssignDataBuilders.png)
+
+4. Optionally, if you have the Addressables build set to be triggered by the player build, or have a custom build-pipeline, you will have to set the `ActivePlayerDataBuilderIndex` property. This value must either be set through the debug-inspector view (it's not exposed by the custom inspector), or set it through script.
+
+   ![Set data builder index](Documentation~/images/multi_catalogs/SetDataBuilderIndex.png)
+
+### Setting up multiple catalogs
+
+With the multi-catalog system installed, additional catalogs can now be created and included in build:
+
+1. Create a new `ExternalCatalogSetup` object, one for each DLC package:
+
+   > Create → Addressables → new External Catalog
+
+2. In this object, fill in the following properties:
+   * Catalog name: the name of the catalog file produced during build.
+   * Build path: where this catalog and it's assets will be exported to after the build is done. This supports the same variable syntax as the build path in the Addressable Asset Settings.
+   * Runtime load path: when the game is running, where should these assets be loaded from. This should depend on how you will deploy your DLC assets on the systems of your players. It also supports the same variable syntax.
+
+   ![Set external catalog properties](Documentation~/images/multi_catalogs/SetCatalogSettings.png)
+
+3. Assign the Addressable asset groups that belong to this package.
+
+4. Now, select the `BuildScriptPackedMultiCatalogMode` data builder object and assign your external catalog object(s).
+
+   ![Assign external catalogs to data builder](Documentation~/images/multi_catalogs/AssignCatalogsToDataBuilder.png)
+
+## Building
+
+With everything set up and configured, it's time to build the project's contents!
+
+In your Addressable Groups window, tick all 'Include in build' boxes of those groups that should be build. From the build tab, there's a new `Default build script - Multi-Catalog` build option. Select this one to start a content build with the multi-catalog setup.
+
+## Loading the external catalogs
+
+When you need to load in the assets put aside in these external packages, you can do so using:
+
+> `Addressables.LoadContentCatalogAsync("catalogName.json");`