Unity Addressables Workflow

What the system is for

Unity Addressables solve a real problem: assets should not live in Resources or in scene references that hold memory forever. They also bring their own complexity. Loading, releasing, prewarming, evicting and grouping addressables by label are easy to get wrong, and the resulting bugs are usually about memory and load order, which are the worst kind to debug.

The Asset Prefetcher in Serenity puts a service in front of Unity Addressables. Contexts, labels, policies and cache state become first-class concepts. Loading and releasing assets follows a workflow instead of a chain of Addressables calls.

The Unity problem

Direct calls to Addressables.LoadAssetAsync and ReleaseAsset across systems lead to four common issues. First, references leak because release calls are scattered. Second, the same asset is loaded multiple times because different systems do not see each other. Third, eviction is hit-or-miss because every system has its own idea of when an asset is no longer needed. Fourth, prewarming a level becomes a custom script per scene.

Addressables also encourage labels as the way to group related assets, but in practice the project has to invent its own concept of a context, a scope or a session for that grouping to mean something.

How Serenity approaches it

Serenity exposes the asset prefetcher through IAssetPrefetcherApp, IAssetPrefetcherService and IAssetPrefetcherProvider, plus IEvictionService for releases. The Domain layer models the workflow through entities such as PrefetchRequest, PrefetchContext, CacheItem and TargetItem, and through value objects such as AssetKey, PrefetchPolicy, PrefetchProfile, PrefetchBudget, PrefetchPriority and PrefetchStrategy.

Operations are use cases: PrefetchAsset, PrewarmContext, ReleaseContext, UpdateTarget and QueryCacheStatus. The application also ships PrewarmAssetsByLabelsTask so a list of addressable labels can be prewarmed in one call. Asset keys are resolved through IAssetKeyResolver, with a built-in PassthroughAssetKeyResolver for the simple case.

How it fits into Serenity

The Asset Prefetcher lives in the Serenity.AssetPrefetcher namespace. Domain entities and value objects describe the workflow. Domain services such as LruCache and PrefetchQueue back the implementation. The Application layer exposes the contracts and use cases. The Infrastructure layer provides the Unity implementation built on Addressables.

The Asset Prefetcher cooperates with Game Settings through IGameSettingsAssetPreloader and IGameSettingsAssetPreloadingIntegrator, so settings that depend on addressable assets are preloaded with the rest of the configuration. It cooperates with Game Mode for prewarming on state transitions, and with the Event Dispatcher when the project chooses to publish cache events.

Practical workflow

1. Group related assets in the Addressables Groups window using meaningful labels.
2. Describe a prefetch context for the scope you want to load and release together.
3. Pick a prefetch policy and profile that match the platform and the moment in the game.
4. Call PrewarmContext or run PrewarmAssetsByLabelsTask to load the assets you need.
5. Use PrefetchAsset for individual assets and UpdateTarget when the scope changes at runtime.
6. Release through ReleaseContext when the scope ends, and use QueryCacheStatus for diagnostics.

What you get

• Service-based prefetcher IAssetPrefetcherApp, IAssetPrefetcherService and IAssetPrefetcherProvider
• Eviction service IEvictionService for explicit releases
• Domain entities PrefetchContext, PrefetchRequest, CacheItem and TargetItem
• Value objects AssetKey, PrefetchPolicy, PrefetchProfile, PrefetchBudget, PrefetchPriority and PrefetchStrategy
• Use cases PrefetchAsset, PrewarmContext, ReleaseContext, UpdateTarget and QueryCacheStatus
• PrewarmAssetsByLabelsTask for label-based bulk prewarm
• Asset key resolution through IAssetKeyResolver with a PassthroughAssetKeyResolver default
• Integration with Game Settings asset preloading and Game Mode transitions

When to use this

• Projects that rely on Unity Addressables and want a defined load and release workflow.
• Games that need to prewarm assets by label before entering a level or screen.
• Teams that want eviction and cache status to be observable instead of guessed.
• Codebases that want addressables to be driven from services rather than from scattered direct calls.

Related systems

• Unity Game Settings Typed get and set use cases for bool, int, float and string settings, with persistence and update signals built in.
• Unity Game Mode System Typed game state transitions with signals, pause strategies and a readiness gate that other systems can subscribe to.
• Unity Menu System Declarative menus, shared UI themes and predictable navigation, configured as assets instead of hand-wired GameObjects.
• Unity Music Player Background music driven by track definitions, configurable transitions and typed signals you can hook into game state.