Addressables-Sample

Addressables-Sample

Demo project using Addressables package

These samples are broken up into projects based on high level functionality. These are intended as jumping off points for your own development. These have not been tested, and are not guaranteed to work in your situation. They are just examples, to make some concepts easier to understand, or easier to replicate in your own project. Use at your own risk.

Note: Please report any bugs found through the regular bug submission process https://unity3d.com/unity/qa/bug-reporting. For any questions, create a new thread on the Unity Forums https://forum.unity.com/forums/addressables.156/.

Projects

Basic/Basic AssetReference

Several sample scenes to display functionality surrounding the asset reference class.

• Scenes/BasicReference
  • Simplest example using a reference to spawn and destroy a game object
  • Each object is instantiated directly via the AssetReference which will increment the ref count.
  • Each object spawned has a script on it that will cause it to release itself after a certain amount of time. This destroys the object and decrements the ref count.
  • Any instances still around when the scene closes will automatically be released (decrementing ref count) by the scene closing process (even if their self-destruct script were disabled).
• Scenes/ListOfReferences
  • Showcases using references within a list.
  • Key feature: once an AssetReference is loaded it keeps a member called .Asset. In this example, you would not want to use the on-complete callback to save off the asset as the loads may not complete in the same order as they were triggered. Thus, it's useful that the reference keeps up with its own loaded asset.
  • Here the objects are instantiated via the traditional GameObject.Instantiate which will not increment the Addressables ref count. These objects still call into Addressables to release themselves, but since they were not instantiated via Addressables, the release only destroys the object, and does not decrement the ref count.
  • The manager of these AssetReferences must release them in OnDestroy or the ref count will survive the closing of the scene.
• Scenes/FilteredReferences
  • Showcases utilizing the various filtering options on the AssetReference class.
  • This scene also shows an alternative loading patter to the one used in other scenes. It shows how you can utilize the Asset property. It is recommended that you only use the Asset for ease of load. You could theoretically also use it to poll completion, but you would never find out about errors in that usage.
  • This sample shows loading via the AssetReference but instantiating via Unity's built in method. This will only increment the ref count once (for the load).
  • Currently, the objects created are being destroyed with Addressables.ReleaseInstance even though they were not created that way. As of version 0.8, this will throw a warning, but still delete the asset. In the future, our intent is to make this method not destroy the asset, or print a warning. Instead it will return a boolean so you can destroy manually if needed.
• Scenes/SubobjectReference
  • Showcases using references with sub objects.
  • An AssetReference contains an main asset (editorAsset) and an optional sub object. Certain reference types (for example, references to sprite sheets and sprite atlases) can use sub objects. If the reference uses a sub object, then it will load the main asset during edit mode and load the sub object during runtime.
  • This scene shows loading a sprite from a sprite sheet (main asset) and loading a sprite as a sub object during runtime.

Basic/Scene Loading

The ins and outs of scene loading.

• Scenes/Bootstrap
  • This is the scene to start with. From this one you can transition to the other scenes.
  • "Transition to Next Scene" will open a new scene (non-additively), which will close the current scene.
  • "Add Object" will instantiate an addressable prefab into the scene. The point of this button is to show that these items do not need ReleaseInstance called on them. Should you use the Profiler, you will see they get cleaned up on scene close.
• Scenes/Foundation
  • This is the scene you transition to from Bootstrap.
  • "Load *" buttons will open other scenes additively.
  • "Unload *" buttons will unload scenes that have been additively loaded.
• Scenes/ItemScenes/*
  • These scenes just contain items with no code. Their purpose is to be additively loaded by the Foundation scene.

Basic/ComponentReference

This example creates an AssetReference that is restricted to having a specific Component.

• Scenes/SampleScene
  • This scene has a Spawner game object that alternates between spawning a direct reference prefab and an addressable one.
  • Both the direct reference and the addressable ComponentReference can only be set to one of the prefabs with the component ColorChanger on it.
• Samples/Addressables/1.19.19/ComponentReference/ComponentReference - ComponentReference
  • This is the class that inherits from AssetReference. It is generic and does not specify which Components it might care about. A concrete child of this class is required for serialization to work.
  • At edit-time it validates that the asset set on it is a GameObject with the required Component.
  • At runtime it can load/instantiate the GameObject, then return the desired component. API matches base class (LoadAssetAsync & InstantiateAsync).
• Scripts/ColorChanger - ColorChanger & ComponentReferenceColorChanger
  • The component type we chose to care about.
  • Note that this file includes a concrete version of the ComponentReference. This is needed because if your game code just specified a ComponentReference it could not serialize or show up in the inspector. This ComponentReferenceColorChanger is what makes serialization and the inspector UI work.
  • Releasing a ComponentReference should be done through ReleaseInstance() in the ComponentReference class. To release an instance directly, see our implementation of ReleaseInstance to understand the requirements.

Basic/Sprite Land

2019.3.0a11+ - Sprite demo is back. There was an engine bug causing a crash when loading out of sprite sheets that caused us to remove this demo. This is in 2019.3 alpha, and is being backported to 2019.2 and 2018.4. If you use this demo, and your game crashes, or you get warnings about "gfx" not on main thread, you don't have a fixed version of the platform. There are three sprite access methods currently demo'd in this sample. The on-screen button will change functionality with each click, so you can demo the methods in order.

• Scenes/SampleScene
  • First is having an AssetReference directly to a single sprite. Since this sprite is a single entry, we can reference the asset directly and get the sprite. This is the most simple case.
  • Second is accessing a sprite from within a sprite sheet. This is the one that was causing a crash, but should be fixed now. Here we load the sprite sheet asset as type IList. This tells addressables to load all the sub-objects that are sprites, and return them as a list.
  • Third is accessing a sprite from within an atlas. In this case, you have to use addressables to load the sprite atlas, then use the normal atlas API to load a given sprite from it. This example also shows extending the AssetReference to provide a typed reference that Addressables doesn't come with (AssetReferenceT in this case).
• All code is in Scripts/SpriteControlTest.cs

Basic/Space Shooter (Legacy)

Referenced in past Unite video(s):

• How to use Unity's Addressable Asset system for speed and performance - Unite LA (2018)
• Unite Berlin 2018 - New Addressable Asset system for speed and performance (2018)

A very simple Unity tutorial that we converted to use addressables. The main code file to look at would be Done_GameController.cs, but in general, this is just meant as a simple project to explore.

Advanced/Addressables Variants (Legacy)

Referenced in past Unite video(s):

• Addressables for live content management - Unite Copenhagen (2019)

An example project to show two use cases or workflows for creating "variants". The new build pipeline (Scriptable Build Pipeline) upon which Addressables is built, does not support asset bundle variants. This old mechanism was useful in many instances, so this sample is meant to show how to accomplish similar results for one of those instances.

• Scenes/TextureScalerScene
  • In the scene, there's a prefab with an existing texture that can load alternate textures based on button input. (VariationController.cs)
  • The project only has one instance of the texture in question (Texture/tree2.png). It is marked as addressable, with the address "tree" and no labels
  • The group containing "tree" has a custom schema added to it (TextureVariationSchema). This defines the label for the provided texture, and a scale and label for alternate textures.
  • For "Use Asset Database (fastest)" in the player, run with the play mode script of "Variant Use Asset Database (fastest)". This will look at all the label variations defined in the schema, and apply all labels to the "tree". This will then go into play mode in the normal "Use Asset Database (fastest)" setup of loading from AssetDatabase, but will fake having an "HD", "SD", etc. version of the texture.
  • For "Simulate Groups (Advanced)" in the player, run with the play mode script of "Variant Simulate Groups (Advanced)". This will do the same things as the "Variant Use Asset Database (fastest)" script above. Note, this is not a very accurate "Simulate Groups (Advanced)" mode right now because it does not emulate the fact that each variety should be in its own bundle.
  • With the build script of "Pack Variations" selected, building the player content will:
    • Find all groups with the TextureVariationSchema
    • Loop over all size/label pairs, and copy the textures on-disk.
    • Change the import settings on the created textures so as to scale them.
    • Build all bundles
    • Remove the extra files/groups that were created.
  • After building with "Pack Variations", you can enter play mode using the standard "Use Existing Build (requires built groups)" script.
• Scenes/PrefabTextureScalerScene
  • In this scene an Addressable prefab that gets duplicated with variant textures.
  • The project only has one instance of the prefab (Assets/Cube.prefab). This prefab has a Material that references a texture in the project.
  • The group containing the prefab has a custom schema attached to it (PrefabTextureVariantSchema.cs). This schema defines the label for the default prefab as well as labels and texture scales for the variant prefabs and their textures. PrefabTextureVariantSchema will only iterate over GameObjects that have a MeshRenderer with a valid material and texture assigned to it.
  • For "Use Asset Database (fastest)" in the player, run with the play mode script of "Variant Use Asset Database (fastest)". This will look at all the label variations defined in the schema, and apply all labels to the "Prefab". This will then go into play mode in the normal "Use Asset Database (fastest)" setup of loading from AssetDatabase, but will fake having an "LowRes", "MediumRes", etc. version of the prefab.
  • For "Simulate Groups (Advanced)" in the player, run with the play mode script of "Variant Simulate Groups (Advanced)". This will do the same things as the "Variant Use Asset Database (fastest)" script above. Note, this is not a very accurate "Simulate Groups (Advanced)" mode right now because it does not emulate the fact that each varie