4. Using Addressables with Gaia

The Unity Addressable System is a way to replace the traditional "hard-wired" references to assets in a scene with an address system, meaning that you can load an asset in via an "address" (a name) during runtime, instead of having to assign a reference somewhere. Doing so brings various advantages, such as being able to separate your art content from your game logic, downloading art content from a file server during runtime, but also deploying content updates without having to roll out a new client build.

Configuring the addressable system in a project with many assets can be a lot of work if done manually, since you would need to identify the used assets on the terrain and configure them as addressables. Gaia can do the heavy lifting for you by automatically collecting all used assets from the terrains in your scene and marking them as addressable.

Please Note: The addressable system is not a pure Gaia feature, but rather a system provided by Unity. Gaia helps you in using the addressable system by taking away the manual configuration work. It is recommended to make yourself familiar with the addressable system and its concepts first before looking at the Gaia integration - this help article for the Gaia integration does not double as full tutorial on addressables in Unity.

Prerequisites / Installation

Addressables can be added at any time in your development process. To use the addressable system, you need to install the "Addressables" package from the Unity Package Manager window.


 

After this has been done, Gaia should detect the package automatically and unlock the corresponding functionalities in the Gaia Manager and other tools.
You can uninstall the package likewise to remove the addressable features of Gaia again. You should get an popup upon deinstallation that asks if you want to remove the "PW_ADDRESSABLES" scripting define, which you should accept to prevent any compilation issues from removing the package.

Activating the Addressable System

The addressable system can be activated from the "Build and Deploy" tab in the Gaia Manager. You can switch the Build Publication Type to "Addressables" to activate it. Upon using the system for the first time, you need to create the initial Addressable Settings Data in your project. This can be done automatically by clicking the "Create Addressable Settings" button:



Now you will see additional options below the list of scenes that allow you to control how the addressable system should be used when building the scenes from the scene list with the addressable system.



The Individual options are:

Working with the Addressable System

When utilizing the addressable system, you can build your world the same way with Gaia as you would if you were doing a regular build. If you are using terrain loading, there is a setting in the Terrain Loader Manager for switching the loading system from loading terrain scenes by their path in the build settings to being loaded from the addressable bundles.

This option will be activated automatically if you switch the build type to Addressables in the Build and Deploy tab.

When you want to build / publish your project with addressables you would need to perform the following steps from the Build and Deploy Tab in the Gaia Manager:

1.) Add the scenes you want to include in this build to the list of scenes. You do NOT need to add single terrain scenes or impostor scenes, those will be added automatically when you include the scene that contains the terrain loader.

2.) Enter the addressable configuration, most importantly the server URL if you intend to do a server build

3.) Create the addressable configuration with the button. This will go through the list of scenes from above, and will include all required assets for the addressable configuration. The addressable configuration window will open after this process so you can control the result.
When using terrain loading, Gaia will try to group assets together in the same bundle that appear in the similar area - in this way terrain loading can be started early while the rest of the world is still being downloaded.

4. Build the addressable bundles - this has nothing to do with the regular build process, but creates the asset bundles based on the configuration created in step 3 before. At the end a file browser window will be opened up that shows the created files. When doing a server build, these are the files you need to make available at the Server URL you entered in the configuration. You can upload these files via FTP or the web interface of your hoster / content delivery network.

5. Do a regular build for your game and publish it. When doing a local build, the addressable bundle files should be included within your build and you would publish them automatically when publishing the entire build directory.
When doing a server build, your client would need to know the location of the catalogue, and would need to be able to open a scene from this catalogue file. We have included a sample client in Gaia that you can use for your first experiments with server builds.

Using the Demo Client to test server builds


 

Gaia comes with a demo client that makes it easier for you to experiment with addressable server builds when you are exploring the addressable system. You can find the client in the following unity scene:

Assets\Procedural Worlds\Frameworks\PWAddressables1\DemoClient

The demo client displays a list of loadable scenes with an "Enter" button. Upon clicking the button, the scene is being loaded and started from a remote location using the addressable system. You can configure the list of displayed worlds with the scriptable object in the same directory as the scene file:


 

To configure a world to load up, you need mainly two things:
 

- The URL of the JSON catalog file on the server - if you followed the addressable workflow as outlined above, you should have the complete address of this file on the server, since you uploaded it there.

- The addressable name of the scene file you want to load from that catalog when the button is pressed. The addressable name of the scene normally equals its path in the asset hierarchy. You can double check in the addressable configuration what the addressable name of the scene is:


 

The remaining fields in the configuration - Display Name, Description, Preview Image Texture - are just for displaying the entry in the list, you can put any info / image here as you please.

If you have configured your scene in the configuration file, you can run the Demo Client scene and the configured scene should be loaded from the catalog when you press the button accordingly. The demo client will cache the files per default, so the second time you press the button, the scene should start instantly since it was already cached. You can disable the cache with the "Use Cached Data" checkbox.
If you do another build of the addressable bundles after changing your scene, and upload the updated files to the server, the addressable system should recognize this and download the changed bundles accordingly.