Asset Bundles

Purpose

The Asset Catalog Editor and Asset Loading System Asset Bundles provide a modular pipeline for managing, building, and dynamically loading asset bundles in Unity. It replaces Unity Addressables with a custom, scriptable, and local/remote configurable alternative that is convenient when working with multiple catalogs of varying configurations.

Asset bundles are set up in the two supporting Unity projects (VHUnityHDRP-Assetsand VHUnityURP-Assets), for use in end-user facing projects, like the two provided examples: VHUnityHDRP and VHUnityURP.

Organization

Editor Layer (AssetCatalogEditor):

• Configured in AssetCatalogWindow.cs found in ride.core/Editor
• AssetCatalogEditor window for creating/editing asset groups.
• Persistent state stored in the AssetCatalogProfile scriptable object (Assets/AssetCatalogData/AssetCatalogProfile) and the BuildSummaryProfile.json in the Application.persistentDataPath

Runtime Layer (AssetLoadingSystemAssetBundles):

• Asynchronously loads catalogs and assets by unique name or label list.
• Supports local and remote paths via signed bundle URLs (e.g., AWS S3).
  • Defaults to loading locally, then attempts to load remotely if local load fails
• Caches loaded assets, tracks bundles, and allows for clean unloading.

Approach

• Assets are manually assigned to named groups in the AssetCatalogEditor window.
• Asset metadata (bundle name, labels, local/remote path prefixes) is serialized into JSON during the build process.
• Each group generates its own catalog.json and set of bundles.
• Bundles.hashes is used to track changes for the assets being built to avoid rebuilding assets that have not changed.
• At runtime, catalogs are loaded via CatalogLoadInfo objects, enabling flexible control over which assets are available and how they are loaded.
• Assets are loaded through interface IAssetLoadingSystem by name or label list.

Usage

• In the Unity editor, open the Asset Catalog Editor window from the Ride > Asset Catalogs menu item.
• Initialize the AssetCatalogData folder to initialize an empty AssetCatalogProfile object for persistent data tracking by using the “Create AssetCatalogData” button in the window.
  • 
• Click the “+ Add New Asset Group” button in the top right to create your first asset group.
  • 
• Rename your group and adjust the local/remote prefix paths as needed. Note, renaming the group will automatically adjust the local and remote prefix paths for you. The current configuration has two prefix paths set as follows:
  • Local: [Application.persistentDataPath]/AssetCatalogs/[Group Name]/[Unity Version]/[Render Pipeline]/[Build Target]/
  • Remote: [ride-owt S3 bucket]/AssetCatalogs/[Group Name]/[Unity Version]/[Render Pipeline]/[Build Target]/
    • Replace ride-owt S3 bucket link with your remote endpoint
    • 
    • And after the name is changed to VH, note the changes in the path:
    • 
• Add assets manually via drag and drop or programmatically using AssetCatalogUtils.
  • 
  • Note: assets have to be unique prefab instances and have a unique name within the same asset group.
• Create and assign labels from the Assign Labels dropdown:
  • 
  • Manage Labels… opens up the label editor which allows you to add or remove labels from the AssetCatalogProfile’s label list which spans across all asset groups.
  • 
  • Add a label by typing it out and clicking the + button then using the assign labels dropdown again to select the newly created label.
  • 
  • A label list can be used to load the asset in place of its name, but it does not guarantee pointing to only a single asset like loading by name does.
• Use BuildAssetBundlesAndCatalog() via the “Build Catalog and Bundles” button at the bottom of the AssetCatalogEditor window or via script to output catalog JSON and bundles to disk.
  • See your build history with a snapshot of the catalog.json file in the Build Summary tab:
  • 
• Either keeps the bundles in your local path to have the files be loaded in locally, or upload the bundles and their manifest + the catalog.json file created per asset group to the designated remote location to allow for remote loading.
• At runtime, initialize AssetLoadingSystemAssetBundles, pass in catalogs via inspector by passing in the catalog.json file directly, providing a local or remote path to the catalog.json file or via script, and load assets by label or name using configured RideCatalogAssets.
  • 
  • 

Limitations

• Asset naming and prefab instances must be unique per asset group.
• Asset label combinations do not guarantee unique references to assets when loading via label vs loading via asset name.
• Bundle loading progress tracking is tracked in 10% intervals.

Known Issues

• Editor UI does not currently support sorting/filtering in large catalogs.
• WebGL loading of asset bundles requires a CORS update to AWS Lambda functions that are used when signing URLs to get passed browser securities.