Addressables system plugin
|1.3||BGDatabase >= 1.7.1||link|
|1.2||Addressables >= 1.17.17||link|
Support for Unity's Addressables system This package adds 2 Addressables loaders for all Unity asset fields.
- Use Unity version > 2018.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
- Install the latest BGDatabase release
- Install this package
- Create your own database as described here
- 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 afterwards)
[Important] Before building your application for the target platform, you need to ensure you built Addressables, cause Unity does not build Addressables automatically.
Window->Asset Management->Addressables->Groupsand then
Build->New Build->Default Build Script
- 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)
- 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 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:
|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|
If you use code generation, use
|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
|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 advice 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
- 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.
- To read assets- use one of the methods (listed above), which supports asset unloading.
How to unload assets
- Call BGEntity.ReleaseAddressablesAssets method from C# script (BGEntity is a database row class)
- 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
- This solution is optional, you can use a standard approach by pairing asset loading from database with Addressables.ReleaseAsset calls
- Test/debug the code to make sure assets are unloaded properly using Addressables event viewer and "Use Existing Build" play mode
- 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.
- 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
- 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.
- Create empty scene
- Attach the script to any GameObject
- Assign it's Address parameter to some valid address from your Addressables system
- 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:
- While importing plugin package, check the packages with source code only
- Import source code packages
- Example "Quick start" project
- Custom action for Playmaker
- Custom action for Bolt/Unity Visual Scripting
- Legacy preloader script, we used in the past for preloading database assets
Click to see all releases
|1.3||Dec 22, 2021||
|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.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|