BG BGDatabase Home Setup How To Use Videos Example Breakdown Fields Export Import Data Binding Events Code Generation Addons

Downloads

← Back Addressables system plugin
Version:
1.5
Format:
Unity package
Dependencies:
BGDatabase (v. >= 1.8.11), Addressables (v. >= 1.17.17)
Version Dependencies Download
1.5 BGDatabase >= 1.8.11 link
1.3 BGDatabase >= 1.7.1 link
1.2 Addressables >= 1.17.17 link
1.0 link

Description

Support for Unity's Addressables system This package adds 2 Addressables loaders for all Unity asset fields.

Setup:

  1. Use Unity version > 2018.2
  2. Install Unity's addressables package via package manager, version 1.17.17 or higher. If the version you see in the package manager is less than 1.17.17, install the package and use this post as a guide to install required version manually. The list of available releases is here
  3. Install the latest BGDatabase release
  4. Install this package
  5. Create your own database as described here
  6. Create a table with any of the Unity assets field and set loader=Addressables or loader=AddressablesByGuid (while creating a field or via gear icon afterward)
  7. [Important] Before building your application for the target platform, you need to ensure you built Addressables, cause Unity does not build Addressables automatically. Choose Window->Asset Management->Addressables->Groups and then Build->New Build->Default Build Script

Loaders type:

  1. Addressable: asset address is stored as database value in human readable form. Cons: you can not change address after value was assigned to database (without re-assigning asset again)
  2. AddressableByGuid: asset Guid (from meta file) is stored as database value, the asset path can be changed after asset assignment. Cons: Guid is just a set of bytes, it's not readable

Addressables folders:

Addressables system configuration may contain folders. In this case, all assets under such folders are added to addressables implicitly. We support such assets, but after updating the configuration (e.g. after adding/removing an asset to/from addressables folders), update our addressables cache manually, otherwise you may encounter the error, saying that asset is not addressable. We used to update this cache automatically, but building the cache can be very expensive, so building it automatically is not the best idea.

How to read assets at runtime:

# Description Unloading supported
1 The usual way, by retrieving field value (Addressables version >= 1.17 is required). In this case assets are loaded synchronously (read more about loading assets synchronously here) Yes
2 If you use code generation, use Load{FieldName}Async generated methods (BGDatabase version >= 1.5.10 is required) to read values asynchronously Yes
3 Retrieve asset address from database and use this address directly with Addressables system API (synchronously or asynchronously). Each unity asset field is implementing BGAddressablesAssetI interface, which can be used to read asset address (using method string GetAddressablesAddress(int entityIndex)). No
4 If you use Playmaker/Bolt/Unity Visual Scripting, use custom actions (links are at the bottom of this page) Yes

This AddressablesQuickStart example project uses options #1, #2 and #3

Unloading/releasing the assets

The approach, recommended by Unity, is to pair asset loading calls with asset releasing calls, for example you may load asset in Start method and release the asset in OnDestroy method. This is a universal approach, and it should work fine in any possible scenarios.

Addressables system increases internal counter each time the asset is loaded and decrease the counter then the asset is released. Once the counter reaches zero - the asset can be disposed (more information is here). Keep in mind, each time you read the asset from the database - you actually read the asset from Addressables system and the counter is increased. So to mark the asset as disposable you need to release it as many times as it was loaded (test the unloading using Addressables events viewer to make sure the assets are unloaded properly). Use this simple test project to see how unloading works

We advise to adhere to the approach, described above, and also we provide an additional, alternative option to release the assets, which can be used in some very specific scenarios - we keep the number of times the asset was loaded via database so this number could be used to release the asset

Click to see details about custom unloading option
Setup assets unloading
  1. Add a new GameObject to your startup scene and attach BGAddressablesMonitorGo component (located in BGDatabase.Addressables.dll DLL file) to it. Make sure this component's Awake method is executed before database is accessed.
  2. To read assets - use one of the methods (listed above), which supports asset unloading.
How to unload assets
  1. Call BGEntity.ReleaseAddressablesAssets method from C# script (BGEntity is a database row class)
  2. If you toggle "UnloadOnRowDelete" parameter on, the loaded assets will be unloaded automatically on row deletion. This can be useful if you use the partitioning addon

Notices:

  1. This solution is optional, you can use a standard approach by pairing asset loading from database with Addressables.ReleaseAsset calls
  2. Test/debug the code to make sure assets are unloaded properly using Addressables event viewer and "Use Existing Build" play mode
  3. we only trace the number of times the asset was loaded via database, we can not figure out how much time the asset was loaded outside the database.
  4. Once the counter reaches zero - all references to this asset become null and the asset can not be used anymore, so use unloading only when asset is not needed anymore
  5. If you want to test unloading inside Unity Editor, make sure to 1) build Addressables and 2) switch "Play Mode Script" to "Use existing build" to simulate runtime Addressables behaviour

Addressables and WEBGL

Addressables does not support synchronous loading on WEBGL. If you target WEBGL- use asynchronous options/API only.

Testing if Addressables system setup properly:

Some people experience issues while setting Addressables system up. In this case, use this script to test if Addressables works correctly.

  1. Create empty scene
  2. Attach the script to any GameObject
  3. Assign "Address" parameter to some valid address from your Addressables system
  4. Run the scene and make sure asset was loaded successfully (no exceptions in the console)

Using source code

We provide source code for our plugins, so you can use source code instead of built DLL file or build your own DLL using source code.

Guide for using source code:

  1. While importing plugin package, check the packages with source code only
  2. Import source code packages

Additional downloads:

  1. Example "Quick start" project
  2. Custom action for Playmaker
  3. Custom action for Bolt/Unity Visual Scripting
  4. Legacy preloader script, we used in the past for preloading database assets

Releases

Click to see all releases
Version Release date Log
1.5 Jun 05, 2024
  1. FIXED Android support was turned off for Addressables DLL file by mistake
1.4 Jun 02, 2024
  1. Support for unityObjectList field
  2. cleaner generated code
1.3 Dec 22, 2021
  1. Support for releasing loaded assets
  2. Min Net version 4.5 -> 4.7.1
1.2 Jun 17, 2021 Sub-assets cache is not updated automatically anymore. Sub-assets cache is the cache for assets, located under addressables folders, e.g. for assets, which implicitly added to addressables configuration, cause parent folder is added to addressables Building this cache could be very expensive operation, so we decided to not update it automatically (the cache can be rebuilt manually by pressing on "Update cache" button in value popup window). For more details read "Addressables folders" section above.
1.1 Apr 17, 2021
  1. Values are now loaded by using AsyncOperationHandle.WaitForCompletion method
  2. Preloader script is removed, because it's not needed anymore (supports for synchronous assets loading is officially added to Addressables)
1.0 Sep 19, 2020 Versioning reset (unified plugin infrastructure)
0.1.4 Sep 06, 2020 Cache (for entries in folders) update strategy changed to get rid of GUI freezes
0.1.3 Aug 05, 2020 Folders support
0.1.2 March 06, 2020 Update for BGDatabase v.1.5.6
0.1.1 September 20, 2019 Update for BGDatabase v.1.4
0.1.0 January 09, 2019 Initial release
← Back to Downloads