How it works

1. 1
   Base app ships with minimal assets (UI, loading screens).
2. 2
   Content bundles (characters, levels, textures) are hosted on a CDN.
3. 3
   StreamingController fetches a manifest, downloads bundles on demand, caches them locally with SHA-256 integrity, and tells Unity Addressables to load from the local cache.
4. 4
   Updates only download changed bundles — no full app update required.

Runtime flow

The Flutter side downloads a bundle to the native cache; Unity Addressables then checks that local cache first before hitting the network, so a cached asset never re-downloads.

Flutter                          Native Cache                  Unity
  |                                  |                           |
  |-- download bundle ------------->|                           |
  |                                  |-- write to disk          |
  |-- sendWhenReady(LoadAsset) -----|-------------------------->|
  |                                  |                           |
  |                                  |<--- Addressables checks  |
  |                                  |     local cache first    |
  |                                  |                           |
  |<------- asset_loaded response --|---------------------------|

Two loader strategies

Which strategy to pick

• Addressables (default) — pick this for new projects. Unity manages dependencies, reference counting and remote/local loading for you, and a remote catalog lets you push content updates without an app rebuild. Requires the com.unity.addressables package and the ADDRESSABLES_INSTALLED scripting define.
• Raw AssetBundles — pick this when you cannot add the Addressables package or need full, manual control over packing. No extra Unity package (built-in), but you manage dependencies, versioning and cache invalidation yourself, and it does not support remote content catalogs.

Selecting the strategy is a one-line change on the constructor — the rest of the StreamingController API is identical:

// Option A: Addressables (default)
final controller = StreamingController(
  bridge: bridge,
  manifestUrl: 'https://cdn.example.com/manifest.json',
);

// Option B: Raw AssetBundles
final controller = StreamingController(
  bridge: bridge,
  manifestUrl: 'https://cdn.example.com/manifest.json',
  assetLoader: const UnityBundleLoader(),
);

Loader property comparison

The Addressables loader builds messages with UnityMessage.routed(...) (routed through FlutterBridge → MessageRouter); the raw loader uses UnityMessage.to(...) (a direct GameObject SendMessage). You can also implement your own strategy by extending UnityAssetLoader:

class MyCustomLoader extends UnityAssetLoader {
  const MyCustomLoader();

  @override
  String get targetName => 'MyCustomManager';

  @override
  UnityMessage setCachePathMessage(String cachePath) =>
    UnityMessage.to(targetName, 'SetCachePath', {'path': cachePath});

  @override
  UnityMessage loadAssetMessage({required String key, required String callbackId}) =>
    UnityMessage.to(targetName, 'Load', {'key': key, 'callbackId': callbackId});

  // ... implement remaining methods
}

Top-level fields — ContentManifest

ContentManifest also derives helpers from these fields: baseBundles and streamingBundles (split on isBase), totalSize, bundleCount, getBundlesByGroup(group), getBundleByName(name) and resolveDependencies(bundleName). The last returns dependencies in topological order and throws StateError('Circular dependency detected: $name') on a cycle.

Per-bundle fields — ContentBundle

What the Unity Editor generates

The Addressables builder (AddressablesManifestBuilder.cs) emits a manifest where group is "addressables", a catalogUrl line is added when a catalog_*.bin is found, and a metadata.addressableKeys array is emitted per bundle:

{
  "version": "1.0.0",
  "baseUrl": "{remoteLoadPath}",
  "catalogUrl": "{remoteLoadPath}/{catalogName}",   // only if a catalog_*.bin exists
  "bundles": [
    {
      "name": "{bundleName}",
      "url": "{remoteLoadPath}/{bundleName}",
      "sizeBytes": {fileInfo.Length},
      "sha256": "{sha256}",
      "isBase": false,
      "dependencies": [],
      "group": "addressables",
      "metadata": {"addressableKeys": ["{key}", ...]}   // or {} if none matched
    }
  ],
  "buildTime": "{DateTime.UtcNow:O}",
  "platform": "{EditorUserBuildSettings.activeBuildTarget}"
}

The raw-bundle builder (AssetBundleManifestBuilder.cs) instead emits "group": "default", no metadata, no catalogUrl, and a {BASE_URL} placeholder for both the top-level baseUrl and each bundle url — you replace it with your CDN URL before uploading. Both builders name the file content_manifest.json, compute lowercased-hex SHA-256, and stamp version "1.0.0".

Public members

Behaviour that matters

• initialize() — sets state initializing, GETs the manifest URL (throws http.ClientException on non-200), parses ContentManifest.fromJson, initialises the cache, then sends the cache path to Unity via setCachePath(bridge, cacheManager.cachePath). If manifest.catalogUrl != null it also sends loadContentCatalog(url: catalogUrl, callbackId: 'catalog_load'). On success state → ready; on any error it emits StreamingErrorType.initializationFailed and state → error.
• preloadContent({bundles, strategy}) — if bundles is null, preloads all baseBundles. Cached bundles emit DownloadProgress.cached and are skipped. The strategy parameter is reserved for future network-aware logic and currently has no effect.
• loadBundle(name) — if the bundle is absent from the manifest it emits StreamingErrorType.bundleNotFound. It branches on manifest.catalogUrl != null: with a remote catalog set, Unity handles downloads via Addressables and the asset is loaded by its addressable key (extractAddressableKey, callbackId load_$bundleName); otherwise Flutter downloads the bundle (if uncached) then loads by bundle name.
• loadScene(name, {loadMode}) — downloads the scene's bundle if present and uncached, then loads it with callbackId: 'scene_$sceneName'. 'Single' replaces the current scene, 'Additive' loads alongside it.
• dispose() — closes the HTTP client and all three stream controllers; the controller is not reusable afterwards. cancelDownloads() is currently a no-op placeholder.

End-to-end usage

// 1. Create streaming controller
final streaming = StreamingController(
  bridge: bridge,
  manifestUrl: 'https://cdn.example.com/manifest.json',
);

// 2. Initialize (fetches manifest, sets up cache, informs Unity)
await streaming.initialize();

// 3. Track progress
streaming.downloadProgress.listen((progress) {
  print('${progress.bundleName}: ${progress.percentageString}');
  print('Speed: ${progress.speedString}, ETA: ${progress.etaString}');
});

streaming.errors.listen((error) {
  print('Error: ${error.type} - ${error.message}');
});

// 4. Preload base content
await streaming.preloadContent();

// 5. Load a specific bundle on demand
await streaming.loadBundle('characters');

// 6. Load a Unity scene via Addressables
await streaming.loadScene('BattleArena', loadMode: 'Additive');

// 7. Cache management
final cached = streaming.getCachedBundles();
final size = streaming.getCacheSize();
final isCached = streaming.isBundleCached('characters');
await streaming.clearCache();

// 8. Dispose
await streaming.dispose();

Addressable key resolution

When a remote catalog is set, loadBundle loads by an addressable key. StreamingController.extractAddressableKey(bundleName, {bundle}) resolves it in three steps:

1. 1
   Metadata lookup — the first entry of bundle.metadata['addressableKeys'] (generated by AddressablesManifestBuilder). Most reliable.
2. 2
   Regex on the filename — for a name like {group}_{address}_{32hexhash}.bundle it strips the trailing _[a-f0-9]{32}$ hash, then the leading ^[a-z]+_assets_ prefix.
3. 3
   Raw cleaned name — if neither produces a result, the cleaned bundle name is used as-is.

ContentDownloader (advanced)

The default StreamingController download path uses its own internal streamed GET, not ContentDownloader. ContentDownloader is a separate, advanced component: downloadBundle(bundle) returns a Stream<DownloadProgress>, fills bytesPerSecond and estimatedSecondsRemaining, and retries up to maxRetries (default 3) with exponential backoff of attempt * 2 seconds. Bundles are processed sequentially in the current implementation.

final downloader = ContentDownloader(
  cacheManager: CacheManager(),
  maxRetries: 3,
  maxConcurrency: 3,
);

await for (final progress in downloader.downloadBundle(bundle)) {
  print('${progress.percentageString} - ${progress.speedString}');
}

// Cancel specific download
downloader.cancelDownload('characters');
downloader.cancelAllDownloads();

downloader.dispose();

FlutterAddressablesManager

It receives cache paths from Flutter and loads assets / scenes from them, registering under the target name "FlutterAddressablesManager". It uses conditional compilation (#if ADDRESSABLES_INSTALLED) so the project compiles even without the Addressables package — when the package is absent, every load returns a descriptive error to Flutter instead of silently failing. Supported messages:

SetCachePath must come first

SetCachePath(string path) rejects a null/empty path, stores System.IO.Path.GetFullPath(path), marks the manager initialised, and installs the cache-first redirect. It must be called before any load — StreamingController.initialize() sends it automatically. Calling a load first returns "FlutterAddressablesManager not initialized. Call SetCachePath first.".

// Redirect remote Addressable URLs to the Flutter-managed cache.
Addressables.InternalIdTransformFunc = TransformInternalId;

TransformInternalId(IResourceLocation location) is that redirect: it only rewrites remote http/https URLs, extracts the filename, joins it to the cache path, and returns the local path only if File.Exists(cachedPath) (logging Redirecting '{fileName}' to cache) — otherwise it returns the original InternalId and Addressables downloads it normally. LoadAsset streams ProgressResponse with handle.PercentComplete while loading and replies with AssetLoadedResponse {callbackId, key, success, error}; LoadScene maps "Additive" → LoadSceneMode.Additive (else Single). UnloadAsset only logs — Addressables uses reference counting, so callers must hold the handle and call Addressables.Release(handle) themselves.

FlutterAssetBundleManager (raw bundles)

The raw-bundle manager registers under "FlutterAssetBundleManager" and supports SetCachePath, LoadBundle, LoadScene and UnloadBundle. It loads via AssetBundle.LoadFromFileAsync and includes a path-traversal guard, SafeBundlePath(bundleName), which strips to Path.GetFileName, resolves under the cache dir, and returns null if the resolved path escapes it.

Editor setup — Addressables (Option A)

1. 1
   Install the Addressables package — Unity Package Manager > com.unity.addressables.
2. 2
   Add the scripting define symbol — Project Settings > Player > Scripting Define Symbols > Add ADDRESSABLES_INSTALLED.
3. 3
   Configure Addressable Groups — base content on Local Build + Local Load paths; streaming content on Remote Build + Remote Load paths. Groups live under Window > Asset Management > Addressables > Groups. Enable Build Remote Catalog (key for remote updates) and, optionally, Only update catalogs manually.
4. 4
   Build content — menu Flutter > Build Addressables. This generates content_manifest.json in the remote build folder.
5. 5
   Upload to CDN — upload all .bundle files and content_manifest.json.
6. 6
   Add FlutterAddressablesManager to your scene — create an empty GameObject, attach the FlutterAddressablesManager component; it auto-registers with MessageRouter. (The README variant suggests attaching it to the same FlutterBridge GameObject.)

Editor setup — raw AssetBundles (Option B)

• Mark assets with AssetBundle labels — select assets in the Inspector and set the AssetBundle label at the bottom.
• Build via menu Flutter > Build AssetBundles → output Builds/AssetBundles/ with content_manifest.json.
• Replace the {BASE_URL} placeholder in content_manifest.json with your CDN URL.
• Upload all bundle files and content_manifest.json, then attach FlutterAssetBundleManager to your scene.

What goes to the CDN

How Addressables resolves a load at runtime

For context, this is the standard Addressables load pipeline that the cache redirect above plugs into — the cache check in step 2 is exactly where TransformInternalId substitutes the local file:

1. Initialization (auto or manual):
   Addressables.InitializeAsync()
   → loads local settings
   → checks remote catalog hash
   → if new → downloads new catalog

2. Load asset:
   Addressables.LoadAssetAsync<T>("address")
   → resolves address → bundle location
   → checks cache (is bundle already downloaded)
   → downloads bundle if remote and not in cache
   → loads dependencies (other bundles)
   → deserializes asset
   → increments reference count
   → returns asset

3. Release:
   Addressables.Release(handle)
   → decrements reference count
   → if count = 0 → frees asset from memory
   → if no asset from bundle is used
     → frees bundle from memory

SHA-256 verification (differs per method)

• cacheBundle(name, data, {sha256Hash}) — used by the default StreamingController._downloadBundle path. It writes the bytes and stores hash = sha256Hash ?? sha256.convert(data).toString() as-is; it does not compare the manifest hash against the computed hash on this path.
• cacheBundleFromStream(name, stream, {expectedSize, sha256Hash}) — hashes chunks incrementally. If sha256Hash is provided, the computed hash is verified after the stream completes; on mismatch the written file is deleted and it throws StateError('SHA256 mismatch: expected $sha256Hash, got $computedHash').
• verifyCache() — an explicit integrity pass over every cached bundle. It recomputes sha256.convert(bytes) per file and returns the names of bundles that are missing from disk or whose hash does not match the manifest entry (logging Cache verification found N invalid bundle(s)).
• isCachedWithHash(name, sha256Hash) — returns whether the stored hash equals the given hash, with no recompute.

Progress events

During a Flutter-managed download you get per-chunk DownloadProgress(state: downloading, downloadedBytes, totalBytes) events, DownloadProgress.cached for already-cached bundles, DownloadProgress.completed when done, and DownloadProgress.failed(error: ...) on failure. DownloadProgress exposes formatted getters: percentageString ("75%"), speedString ("1.2 MB/s") and etaString ("2m 30s"). On the Unity side, FlutterAddressablesManager streams ProgressResponse {callbackId, progress, status} with status "loading" / "loading_scene".

Errors from the controller

The full StreamingErrorType enum is notInitialized, initializationFailed, manifestFetchFailed, bundleNotFound, downloadFailed, networkUnavailable and cacheError. The ones you will actually see emitted:

Errors from Unity

Unity → Flutter errors arrive as ErrorResponse {callbackId, error, errorType}: