Skip to content

t1k:unity:optimize:initial-bundle

FieldValue
Moduleoptimize
Version2.35.6
Effortmedium
Tools—

Keywords: addressables, BackgroundWarmLoadQueue, buildlayout, GameReady, initial bundle, InitialBundle, lazy load, on-demand, pack together, preload, PreloadT0, startup download, warm load, WebGL

/t1k:unity:optimize:initial-bundle
[analyze|group|lazy-load|verify] [--budget-mib 30] [--game-ready <symbol>]

Initial Bundle ≤30 MiB + Lazy-Load Everything Else

Section titled “Initial Bundle ≤30 MiB + Lazy-Load Everything Else”

Initial Bundle Size = the total built size of every Addressable asset that is loaded before the GameReady checkpoint. Two hard rules, both blocking:

  1. ≤ 30 MiB (compressed on-disk .bundle size, i.e. what the client actually downloads).
  2. Exactly ONE Addressable group, InitialBundle, Bundle Mode = Pack Together — so the whole pre-GameReady set is one bundle = one HTTP request. Everything else lives in *_OnDemand groups and is loaded lazily (just-in-time via IAssetsManager, or ahead of need via a background warm-load queue that starts after GameReady).

Scope: MainGame + Composition layers (Assets/_Game/, Assets/Scripts/, Assets/AddressableAssetsData/). Never edit Packages/com.gdk.* / Assets/UITemplate (BASE, frozen); their boot labels (PreloadSprite / PreloadGameObject / PreloadAudioClip, loaded by com.gdk.core/Scripts/AssetsLoader.cs) are inputs to the analysis, not things to change.

IntentPath
“How big is our initial bundle? / is it under 30 MiB?”Step 1 Analyze → scripts/check_initial_bundle_size.py
“Put everything loaded before GameReady into one group”Step 2 Group + references/initial-bundle-analysis.md
“Lazy-load the rest / add a warm-load queue”Step 3 Lazy-load + references/lazy-load-warm-queue.md
“Prove the real download-before-ready in WebGL”Step 4 Verify + references/initial-bundle-watch.md
“Where is GameReady in this project?”GameReady detection

GameReady checkpoint — detect, then confirm

Section titled “GameReady checkpoint — detect, then confirm”

The checkpoint varies per game. Grep in this order, present the first hit(s), and confirm with AskUserQuestion before treating it as the boundary (never assume):

OrderSymbolTypical site
1IGameplayService.OnLoaded / .IsLoaded (TheOneFeature)Assets/Scripts/Services/GameplayService.cs
2GameReadyToPlaySignal (GameFoundation scene signal)consumer fires it after loading screen + boot overlay
3FinishLoadingNewSceneSignal → YG2.GameReadyAPI()MainSceneScope.cs, YandexGameReadySignalBridge.cs
4Platform-native ready call (GameReadyAPI, TikTok/YouTube ready)TheOnePlatform bridges
Terminal window
grep -rnE 'IGameplayService\.OnLoaded|GameReadyToPlaySignal|FinishLoadingNewSceneSignal|GameReadyAPI\(' \
--include='*.cs' Assets/Scripts Assets/_Game Assets/TheOnePlatform Assets/PlatformIntegration

Everything loaded on the code path up to and including the confirmed site is “initial”. Anything first touched after it is on-demand.

  1. Build Addressables (Addressables → Build → New Build → Default Build Script) so Library/com.unity.addressables/buildlayout.json is fresh for the target platform.
  2. Run python3 scripts/check_initial_bundle_size.py --project <UnityProjectRoot> [--budget-mib 30]. It reports per-group built size, packing mode, and the initial set (default = group InitialBundle + any group/label matching Preload|InstallTime|T0 — the pre-migration vocabulary), and exits non-zero over budget. After migrating, pass --initial-pattern InitialBundle so PreloadT1 (on-demand) stops counting.
  3. Enumerate what the boot path actually loads (see references/initial-bundle-analysis.md § “Building the pre-GameReady set”): built-in scene dependencies, gdk boot labels, LoadingSceneScope / MainSceneScope early loads, IAsyncEarlyLoadable / IInitializable that call IAssetsManager, the first level’s content, FTUE prefabs.
  4. Produce a table: asset | why it's initial (call site) | size | keep-in-initial? | if not, on-demand trigger.

Step 2 — Group into ONE Pack-Together InitialBundle

Section titled “Step 2 — Group into ONE Pack-Together InitialBundle”
  1. Create group InitialBundle (Bundle Mode Pack Together, IncludeInBuild on, local build/load path, label InitialBundle on every entry). Prefer the Addressables window; if editing .asset YAML, GUIDs must match .meta files (see t1k:unity:tof:addressables gotchas).
  2. Move every pre-GameReady asset into it — including entries currently in Preloads, *_PreloadT0, *_InstallTime, UIPreloadT0, Sprites_Preload… Delete the emptied groups.
  3. Move everything else out to <Type>_OnDemand groups (Pack Separately for per-level content, Pack Together for small type-clusters). Never leave the Default Local group holding gameplay assets.
  4. Run Addressables → Analyze → Check Duplicate Bundle Dependencies; a shared dependency between InitialBundle and an on-demand group must live in InitialBundle (or the on-demand group pulls a second bundle at boot).
  5. Rebuild, re-run Step 1. Gate: InitialBundle = 1 bundle, ≤ 30 MiB, and no other group is fetched before GameReady. If over budget → demote the largest assets to on-demand and add a lazy-load trigger for each (Step 3); repeat. Do not raise the budget.

The assets/InitialBundleAnalyzer.cs.txt editor template automates 1–4 in-editor (plain IMGUI window, public Addressables editor API only: analyze → preview → regroup); copy it into an Editor/ folder of the consumer project.

Two lanes, both documented in references/lazy-load-warm-queue.md:

  • Just-in-time: the owning presenter/service resolves the asset via IAssetsManager.LoadAsync<T> when first needed and Releases on scope teardown. Never Resources.Load, never direct Addressables in MainGame.
  • Background warm-load queue (port of Arrow3D BackgroundWarmLoadQueue / Screw3D BackgroundDownloadQueue): priority tiers PreloadT1 → Level → FeatureUI, dedup, gameplay throttle, exponential-backoff retry, MessagePipe pause on popup/app-pause. It starts only after GameReady — anything the queue touches before GameReady silently re-joins the initial bundle. Level look-ahead warms model data only (IDataManager.LoadAsync<LevelModel>), never the stateful PuzzleGameplayService.PreloadAsync.

Per-game knobs to confirm with the user: how many levels ship in InitialBundle (Screw3D: 15; Arrow3D: 0 — models are tiny JSON), look-ahead window, throttle seconds, remote catalog on/off.

  • scripts/check_initial_bundle_size.py passes (1 bundle, ≤ 30 MiB).
  • Runtime: IAssetsManager logging or Addressables Event Viewer shows only initialbundle_*.bundle (plus catalog + built-in scenes) fetched before the GameReady site fires.
  • WebGL: TheOnePlatform InitialBundleWatch reports bytes fetched until platform-ready — references/initial-bundle-watch.md. This is the number that matters on Yandex/TikTok/YouTube.
  • Test Pass Gate: EditMode/PlayMode suites green after regrouping (addresses unchanged ⇒ no code change, but a moved asset with a renamed address breaks LoadAsync at runtime).
  • Pack Together ≠ one request if two groups are Pack Together. The rule is one group; six T0 groups each Pack Together = six requests (Arrow3D webgl-yg state before this skill).
  • LoadAllAsync<T>(label) filters by type — a mixed-type label must be loaded as <UnityEngine.Object> or non-matching entries are silently dropped (Arrow3D AddressableAssetWarmLoader).
  • A label resolving to 0 assets is not success — log a warning; don’t count it as loaded.
  • buildlayout.json uses SerializeReference rid indirection (references.RefIds); the top-level Groups[] are just {rid} handles. The script resolves them; a naive parser reads nothing.
  • Duplicate Asset Isolation groups (auto-created by Analyze) are Pack Separately → hundreds of tiny bundles. Anything an initial asset depends on must be inside InitialBundle, not isolated.
  • Bundle Mode m_BundleMode: 0 = Pack Together, 1 = Pack Separately, 2 = Pack Together By Label in AssetGroups/Schemas/*_BundledAssetGroupSchema.asset.
  • m_BuildRemoteCatalog: 0 (Arrow3D) means “download” is really the local WebGL fetch — the size gate still applies; only the warm loader’s engine differs (LoadAllAsync vs DownloadDependenciesAsync).
  • GameReady must not fire early. Firing on scene-finish while the loading screen/boot overlay is still up both violates platform rules and shrinks the “initial” set on paper only.
  • Addressable .asset group files are not merge=ours — regrouping on a WebGL branch propagates to mobile branches on merge; call this out in the PR.
  • Boot labels are BASE-owned. Do not rename PreloadSprite/PreloadGameObject/PreloadAudioClip; put those entries in InitialBundle and keep the labels.
  • T0 soft-fail: Screw3D loads its T0 label with a 20 s timeout and continues on failure — copy that; a stalled initial load must not hang the loading screen forever.

t1k:unity:tof:addressables (TOF group placement) · t1k:unity:base:boot-flow (LoadingSceneScope→MainSceneScope) · t1k:unity:optimize:project-auditor · TheOnePlatform PlatformSetup/Editor/InitialBundleWatch/