t1k:unity:optimize:initial-bundle
| Field | Value |
|---|---|
| Module | optimize |
| Version | 2.35.6 |
| Effort | medium |
| Tools | — |
Keywords: addressables, BackgroundWarmLoadQueue, buildlayout, GameReady, initial bundle, InitialBundle, lazy load, on-demand, pack together, preload, PreloadT0, startup download, warm load, WebGL
How to invoke
Section titled “How to invoke”/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:
- ≤ 30 MiB (compressed on-disk
.bundlesize, i.e. what the client actually downloads). - 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*_OnDemandgroups and is loaded lazily (just-in-time viaIAssetsManager, 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.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “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):
| Order | Symbol | Typical site |
|---|---|---|
| 1 | IGameplayService.OnLoaded / .IsLoaded (TheOneFeature) | Assets/Scripts/Services/GameplayService.cs |
| 2 | GameReadyToPlaySignal (GameFoundation scene signal) | consumer fires it after loading screen + boot overlay |
| 3 | FinishLoadingNewSceneSignal → YG2.GameReadyAPI() | MainSceneScope.cs, YandexGameReadySignalBridge.cs |
| 4 | Platform-native ready call (GameReadyAPI, TikTok/YouTube ready) | TheOnePlatform bridges |
grep -rnE 'IGameplayService\.OnLoaded|GameReadyToPlaySignal|FinishLoadingNewSceneSignal|GameReadyAPI\(' \ --include='*.cs' Assets/Scripts Assets/_Game Assets/TheOnePlatform Assets/PlatformIntegrationEverything loaded on the code path up to and including the confirmed site is “initial”. Anything first touched after it is on-demand.
Workflow
Section titled “Workflow”Step 1 — Analyze
Section titled “Step 1 — Analyze”- Build Addressables (
Addressables → Build → New Build → Default Build Script) soLibrary/com.unity.addressables/buildlayout.jsonis fresh for the target platform. - 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 = groupInitialBundle+ any group/label matchingPreload|InstallTime|T0— the pre-migration vocabulary), and exits non-zero over budget. After migrating, pass--initial-pattern InitialBundlesoPreloadT1(on-demand) stops counting. - 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/MainSceneScopeearly loads,IAsyncEarlyLoadable/IInitializablethat callIAssetsManager, the first level’s content, FTUE prefabs. - 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”- Create group
InitialBundle(Bundle Mode Pack Together,IncludeInBuildon, local build/load path, labelInitialBundleon every entry). Prefer the Addressables window; if editing.assetYAML, GUIDs must match.metafiles (seet1k:unity:tof:addressablesgotchas). - Move every pre-GameReady asset into it — including entries currently in
Preloads,*_PreloadT0,*_InstallTime,UIPreloadT0,Sprites_Preload… Delete the emptied groups. - Move everything else out to
<Type>_OnDemandgroups (Pack Separatelyfor per-level content,Pack Togetherfor small type-clusters). Never leave the Default Local group holding gameplay assets. - Run Addressables → Analyze → Check Duplicate Bundle Dependencies; a shared dependency between
InitialBundleand an on-demand group must live inInitialBundle(or the on-demand group pulls a second bundle at boot). - 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.
Step 3 — Lazy-load everything else
Section titled “Step 3 — Lazy-load everything else”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 andReleases on scope teardown. NeverResources.Load, never directAddressablesin MainGame. - Background warm-load queue (port of Arrow3D
BackgroundWarmLoadQueue/ Screw3DBackgroundDownloadQueue): priority tiersPreloadT1 → 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 statefulPuzzleGameplayService.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.
Step 4 — Verify
Section titled “Step 4 — Verify”scripts/check_initial_bundle_size.pypasses (1 bundle, ≤ 30 MiB).- Runtime:
IAssetsManagerlogging or Addressables Event Viewer shows onlyinitialbundle_*.bundle(plus catalog + built-in scenes) fetched before the GameReady site fires. - WebGL: TheOnePlatform
InitialBundleWatchreports 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
LoadAsyncat runtime).
Hard rules
Section titled “Hard rules”- 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-ygstate 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 (Arrow3DAddressableAssetWarmLoader).- A label resolving to 0 assets is not success — log a warning; don’t count it as loaded.
buildlayout.jsonuses SerializeReferenceridindirection (references.RefIds); the top-levelGroups[]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 inAssetGroups/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 (LoadAllAsyncvsDownloadDependenciesAsync).- 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
.assetgroup files are notmerge=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 inInitialBundleand 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.
Related
Section titled “Related”t1k:unity:tof:addressables (TOF group placement) · t1k:unity:base:boot-flow (LoadingSceneScope→MainSceneScope) · t1k:unity:optimize:project-auditor · TheOnePlatform PlatformSetup/Editor/InitialBundleWatch/