Search Unity

Addressables is a Unity Editor & runtime asset management system that improves support for large production teams with complex live content delivery needs. This release marks a major milestone in our journey to relieve developer pain while also bringing live content capabilities within reach of smaller teams less equipped to tackle the engineering challenges. Addressables is now out of preview [1] and will be available as a verified package for Unity 2019.3. It will remain fully supported in Unity 2018 LTS releases.

Background

In Unity 4, Asset Bundles were introduced as a low-level mechanism for building assets into discrete units for dynamic loading at runtime. Implementing Asset Bundles enables developers to separate content from the app install. This provides the ability to deliver regular content updates to live apps with a small initial download size, while staying below the over-the-air install limit as additional app content is added.

Despite these benefits, utilizing Asset Bundles in a real production is a complex task. There are no obvious workflows in Unity for transitioning content to Asset Bundles from the simple mechanisms of referencing and loading assets in Unity – through direct references in scenes and public fields of GameObjects. Transitioning an app or game from utilizing purely static, built-in content to one with the ability to load content dynamically with incremental updates requires a large amount of refactoring and custom programming. This capability has therefore remained out of reach for many, if not most, developers.

Addressables

What we found when talking to developers about their experience using Asset Bundles was that almost everyone doing so successfully were more or less writing the same high level systems a thousand slightly different ways. Addressables was born out of this obvious need for a framework to solve a set of common problems related to addressing, building, and loading assets.

Separation of Concerns: Referencing vs. Packaging Assets

The primary function of Addressables is to separate what assets are being loaded from where and how those assets are loaded. Any asset, including scenes, prefabs, text assets, etc. can be marked as addressable, and given a unique name. Once addressable, an asset can be referenced and loaded by its addressable name in code and through a special Asset Reference script type. Separately, Addressable assets can be grouped together for building and loading as built-in content or into bundles for loading dynamically at runtime. It’s through this separation of concerns that decisions about content packaging and distribution can be deferred to later in production without requiring changes to the game code.

The Addressables window

Runtime Memory Management

A key advantage of loading from Asset Bundles in Unity is that they provide an efficient means to unload no longer needed content from memory. Effectively keeping track of what is loaded and what can be safely unloaded is a complicated coding task previously left to the developer. Loading through Addressables automatically provides high level reference counting of loaded assets and their dependencies and can automatically unload bundles and their associated assets when no longer in use. Additionally, Addressables provides a visual profiler for real-time debugging of loaded asset and Asset Bundle reference counts.

The Addressables Profiler

Faster Iteration

Addressables provides some key abstractions to the asset loading process that allow for faster iteration of content changes.

  • Play Mode Simulation: assets load directly from disk without requiring a build process, while still providing the ability to debug asset reference counts through the profiler.
  • Fast Incremental Builds: Addressables ships with the new Scriptable Build Pipeline that improves the speed and reliability of incremental builds.
  • Editor Hosting Services: A built-in facility for serving Addressable content to local, LAN connected devices provides a fast, convenient method for iterating content on device.

Getting Started 

Addressables separates the concerns of referencing and packaging of assets, enables faster iteration both in playmode and on deployed player builds, and provides automatic memory management and profiling tools. It is designed for extensibility and customization to solve for both simple and complex use cases. 

While we are excited to finally bring Addressables out of preview so you can confidently use Addressables in your production apps today, we continue to work diligently on improvements in performance and functionality, and are looking ahead to ensure Addressables evolves along with Unity and with your needs as developers.

With many of the key technical challenges of supporting dynamic content solved by Addressables, the “last mile” problem still remains – the hosting and delivery of assets to live production games and apps. Later this year, we will be launching an enterprise ready, global content hosting solution, fully integrated into the Addressables system. If you would like to learn more about this service, sign up here.

Over 300 projects are already using Addressables. Add it in your project today using the Package Manager system in Unity. It’s easy to get started in a new project, or follow the Migration Guide if you would like to upgrade an existing project to take advantage of addressables. We also provide example projects for basic and advanced usage on GitHub.

[1] To clarify the meaning of “out of preview”, if you update to Addressables 1.1.5, you will note the “Preview” tag is gone from the package in Package Manager. This intermediate state communicates that the package passes a suite of automated tests against the latest version of Unity, and that the package owner – my team – is ready to support the feature in developer projects. It is compatible with all versions of Unity including and after 2018.3. For the future 2019.3 release, the intent is that the package will be “verified” – that is it will have been tested and validated by release QA in combination with the main Unity engine/editor release.

38 Comments

Subscribe to comments

Comments are closed.

  1. there is a bug when the file path is too long ,such as File.CopyFile()

  2. How can I load all assets in one of groups? use the group name?

  3. Help with getting the addressable system to upload separate bundles into oculus store as described in the link below. I’m not sure where the actual bundles are being stores so I can then upload them to oculus https://developer.oculus.com/blog/tech-note-expansion-file-support-for-gear-vr-beta/

  4. your local memelord

    August 24, 2019 at 11:06 pm

    The lack of documentation, clear examples, and ease of use made me go back to resources loading after days of trying to have
    something that was not a pain in the ass to work with, I am sure it works wonders if you are part of the dev team and know the inside out, but I absolutely hate having to do trial and error and github issues hunting because there are no docs.

  5. As developers, we tend to do a lot of work, programming/development, etc. and can get caught up in all the pain of the errors we face. But I want to say really, thank you. This was very-much needed, and is absolutely awesome! Great job to your team for all the work put into this! I’ve started using the Addressables in my project, and love it so far!

    I am still using Resources.Load(…) for the majority of my game still, however. I’m wondering if Addressables can be used when *not* in playmode, and just in the editor? I made a level-editing system that requires being able to load these assets (currently through the Resources API) to show where enemy spawns are, but would *love* to switch that system to use the Addressables instead!

  6. after installing the package and updating from bundles my project now fails to load the converted asset. and I find no clue on how to fix the code to make them working again

  7. Leon Moctezuma

    July 29, 2019 at 3:13 pm

    In my opinion this package should stay on preview until it’s truly production ready, otherwise it’s misleading the community.

  8. I am experiencing a weird bug that happens only on iPhone X/Xs/Xr that the Addressables Initialization Task never completes. On any other platforms, it runs to completion. I suspect it might have something to do with the Task initialization or the WaitHandle

  9. Something I’ve been unable to find – how do you get the address of a ScriptableObject at runtime?

    1. This is an valid concern. I’ve found I can only load GameObjects, as the loaders are specific to that type. Outside of this use case it seems to fail.

      Please inform us as to how we can load ScriptableObjects via Addressables, Unity!

      Such a cool feature we’re missing out on due to lacking documentation and overbearing specificity.

  10. Hi. I use Adressables since the beginning. Nice Stuff.
    Would be cool when you could use it the Unity examples like Fontainebleau, FPS Sample and the Additive Loading Lighting Examples Asset.
    Would speed up out of preview.)

  11. Florian Bernard

    July 17, 2019 at 9:11 pm

    That’s great news.

    But last time I tried to play with it (0.8.something), it was not even possible to get a basic load progress.
    Also, very large scenes (~500Mb) were not loading at all over my local network.

    Curious to know if these issues are fixed now.

    Thanks for the great work. I’m sure the Addressable system will be a very powerful feature!

  12. Not sure i understand this sentence:

    “Addressables is now out of preview and will be available as a verified package for Unity 2019.3. It will remain fully supported in Unity 2018 LTS releases.”

    Is the “official” package available right now? which Unity version can i use it with ?

    1. Stephen Palmer

      July 22, 2019 at 5:04 pm

      Lior, we updated the blog post (at the bottom) with a clarification on this point.

  13. Do you anticipate any API churn from now until 2019.3, or is the remaining work mostly bug fixes and new features?

    1. Stephen Palmer

      July 17, 2019 at 4:42 am

      APIs and data will be relatively stable. We are considering a sync loading API, but that would be additive. We’re really focusing on bug fixes and usability improvements for the rest of the year. An Editor UI refresh is coming in about a month, for instance.

  14. typo – “of loadeds assets”

  15. Isaac Surfraz

    July 16, 2019 at 3:20 pm

    Hopefully its usable by then, because right now and up until now except for a handful of cases it has been a pretty broken and difficult to use system.

    The UI is almost completely broken and will throw all sorts of errors, and trying to load anything except at the very very granular level is difficult.

    People just want a way to load a collection of prefabs, a scene, or a single prefab easily, without having to be an expert in using addressables. Right now both packaging up stuff and loading + unloading it is far too cumbersome for something touted as fixing the difficulty of using asset bundles.

    1. Stephen Palmer

      July 17, 2019 at 12:23 am

      We have not been running into UI errors in our tests, and would love to know what situations cause these. Have you already posted the issue on the forum or as a Unity bug? If not, it would be great if you could. A Unity bug is the best way for us to get a repro project and really dig into problems. If you cannot get us a project, we try to stay somewhat on top of the forums, so you can try posting there. (https://forum.unity.com/forums/addressables.156/)

      1. Isaac Surfraz

        July 23, 2019 at 3:42 pm

        Thanks I have not but I will file a bug when I am back home.

  16. So can you load in addressable catalogues as addressables?

    1. Stephen Palmer

      July 17, 2019 at 12:23 am

      Are you referring to having multiple Unity projects, and allowing one to load assets (and a catalog) from another? If so, this is something that can work, but is fairly advanced and not yet well explored on our end. This would be the place to start looking: https://docs.unity3d.com/Packages/com.unity.addressables@1.1/api/UnityEngine.AddressableAssets.Addressables.html#UnityEngine_AddressableAssets_Addressables_LoadContentCatalogAsync_System_String_System_String_.

  17. Feedback — it’s completely unusable in its currently form (v1.1.4 – 6/19/2019). The UI asked to convert existing resource bundles and then it locked-up and became unresponsive. I restored ,my project’s files and tried again — this time skipping conversion of existing bundles. Again, it locked up Unity. I’d warn anyone who reads this article to make a back-up of their Unity project before doing anything with this experimental package, as it exists today.

    1. Stephen Palmer

      July 17, 2019 at 12:25 am

      Thanks for the feedback Shaun. Sounds like you are running into a bug; perhaps related to large numbers of legacy asset bundles in use. We’ll investigate.

  18. Good but the biggest issue with asset bundles is shaders in them throwing errors as Unity changes and old bundles are not fully compatible. Bundles have to be kept up to date with changing shaders and material systems. What if you could have material descriptions instead which map/build final material on load (we did this but old bundles throw shader errors or warnings)

    1. Stephen Palmer

      July 17, 2019 at 4:18 am

      Shaders in bundles built in Unity 2018.x and later should be forward compatible with later versions of Unity. If not it would be considered a bug at this point.

  19. Thanks for the post, I’ll give it a try with 2018.4! I was just looking at the “Getting started” guide, but couldn’t find how to load a scene through the addressables system.

    I don’t need to load individual assets, just levels. I hope I can use the addressables system for that, basically mark every scene to be stored as a separate asset bundle and then use addressables to load that scene from its bundle.

    I’m pretty sure it’s supported, the information how to achieve it is probably available somewhere in the documentation. Do you mind to point there?

    Perhaps update the “Getting started” guide with that information too?

    1. Stephen Palmer

      July 17, 2019 at 12:21 am

      Sorry that this isn’t something you easily found in the docs. We do discuss it some, but I’d actually recommend you look at one of our samples to get started with this. Take a look at https://github.com/Unity-Technologies/Addressables-Sample/tree/master/Basic/Scene%20Loading and if you run into any problems, please post them on the forum (https://forum.unity.com/forums/addressables.156/)

  20. Plenty of time till 2019.3. Ive been following the Addressables team on forums , its a solid team they will deliver

  21. Wait, out already? But what about something like Sync Addressables (because that sample on github is not good enough)? What about proper dependency sorting for stuff like unused models in FBX files? What about having your settings serialized and versioned when using custom providers? What about determenistic build behaviour for easier patching? Or, you know, what about the countless bugs?

    It’s far from being a production ready package for *most* of the projects, unless quite a big amount of problems will be fixed until 2019.3.

    1. I have to say, I’ve learned to take it with a grain of salt whenever Unity says something is production ready.

      1. This is sadly so true. I really don’t want to offend anybody, but when I see “production ready” in Unity I read it as “don’t touch it until at least several months later or more”.

    2. Don’t worry, they’ll probably forget about it then deprecate it and promise to replace it with a new system in a year or two.

      1. Stephen Palmer

        July 17, 2019 at 4:36 am

        We’re not going anywhere. We are committed to making Addressables the best way to manage and build live content in Unity 2018 and 2019. We do expect that there will be some evolution of the system as Unity transitions into DOTS workflows with runtime entity binary data in 2020 and beyond, but the team’s mission and goal remains to reduce pain points around content distribution for live productions.

    3. 2019.2 stable is not even released yet. Just give Unity team a time. It ‘s a long way until 2019.3 I’m sure they can finish it.

    4. Stephen Palmer

      July 17, 2019 at 7:47 pm

      – Synchronous API: this is not as straightforward as it seems, as one of the fundamental principals of Addressables is that asset dependencies are resolved at runtime, and any number of those dependencies (like asset bundles) may require an asynchronous operation to complete, such as downloading from a remote server. Having said that, based on developer feedback and some requirements we see coming up in DOTS/hybrid, I think there is a place for API support for sync loading under certain conditions, and will likely show up in a later release.
      – Dependency sorting/unused sub-assets: Unused objects in complex assets like FBX files are already stripped correctly by the build pipeline. For instance, in an addressable prefab with a mesh renderer that references a single mesh from an FBX file with multiple meshes, the unused mesh will not be included in the build. A limitation that has existed even before Addressables is the ability to reference a sub-object directly as a loadable unit, as you can only do so at the asset level.
      – Serialization and versioning of custom provider settings: sounds like you are expecting/looking for something specific that we need more clarity on – feel free to start a thread in our forums (https://forum.unity.com/forums/addressables.156/) to facilitate that discussion with the team.
      – Deterministic builds: Non-deterministic output in builds are always considered bugs, and we take them seriously. Please report them if you are experiencing them.

      1. Regarding deterministic builds, I think he refers to deterministic asset bundles output on different machines, which seems to be a known issue and not easily fixable: https://forum.unity.com/threads/deterministic-asset-bundle-building.703826/