t1k:unity:mobile:build-size
| Field | Value |
|---|---|
| Module | mobile |
| Version | 3.65.6 |
| Effort | medium |
| Tools | — |
Keywords: aab size, addressables bundles, apk size, build size, dead assets, import settings, mobile memory, startup time, texture compression, webgl build
How to invoke
Section titled “How to invoke”/t1k:unity:mobile:build-size<apk|aab|webgl build dir> or <what to shrink>Unity Mobile — Build Size, Startup & Memory
Section titled “Unity Mobile — Build Size, Startup & Memory”The Unity half of t1k-gamedev:optimize:perf-loop (that skill owns measure → rank → fix-one →
re-measure); this one supplies the Unity artifact audits. Both scripts are stdlib Python 3, run with
python3 -I: scripts/apk_breakdown.py <apk\|aab> weighs the built artifact by contributor;
scripts/import_audit.py <Assets-dir> audits import settings and duplicate content.
Decision Tree
Section titled “Decision Tree”| Intent | Go to |
|---|---|
| “Why is the APK 300 MiB?” | 1 · references/apk-contributors.md |
| “Can we drop these Addressables/Resources?” | 2 |
| “What do the import settings cost?” | 3 · references/import-budgets.md |
| “Why is boot slow / memory high / stutter?” | 4 · references/startup-and-runtime.md |
| “WebGL build broken / huge / test-only” | 5 · references/webgl.md |
| “WebGL build fails, hangs, or boots frozen” | references/webgl-build.md |
| “The player data is huge / textures are uncompressed” | 6 · references/artifact-census.md |
“lib/ or the wasm dominates” | 6 · references/code-size-anatomy.md |
| “Sprites not atlased / atlas page duplicated or uncompressed?” | references/atlas-audit.md |
| “Does the WebGL build actually boot?” | references/webgl-boot-test.md |
| Writing the report | references/report-template.md |
| Before trusting any of the above | Hard rules |
1. Baseline the built artifact
Section titled “1. Baseline the built artifact”Weigh the artifact, never the project folder: one PNG imports at 0.5 MiB (1024 ASTC) or 64 MiB (4096 RGBA), so folder bytes say nothing about what ships.
python3 -I scripts/apk_breakdown.py Builds/android-dev/app.apk --top 10 # --json for a machine consumerpython3 -I scripts/apk_breakdown.py Builds/android-dev/app.aab # strips base/, detects BundleConfig.pbPrints lib/<abi>, assets/bin/Data, global-metadata.dat, classes*.dex, addressables bundles,
other, sorted with MiB, % of total and the largest files; uncompressed and compressed both, since
compressed is what the store serves. Both scripts divide by 1,048,576, so their unit is MiB.
Category meanings: references/apk-contributors.md.
- Record
Developmentflag + scripting backend + ABI set with every number. A Development build is not size-representative (debug symbols, no stripping); shipping armv7+arm64 doubleslib/. Also recorduseCustomMainManifestand the manifest’sversionCodewhen the APK is for release: a checked-in manifest withuseCustomMainManifest: 1is authoritative (t1k-unity-mobile-coreHard rules). - Unity’s own report: the
Build Reportsection ofEditor.log(~/.config/unity3d/Editor.log); check it exists first (grep -c "Build Report" <log>) — a 0 means no build since the log rotated, so the number is absent, not zero.
2. Dead-weight check
Section titled “2. Dead-weight check”Addressables/Resources content is dead only if nothing loads it. Prove the loader first.
rg -n 'Addressables\.(Load|Instantiate|Initialize)' Assets Packages -g '*.cs'rg -n 'IAssetManager|IGameAssets|LoadAllAsync' Assets Packages -g '*.cs'rg -n 'Resources\.Load' Assets Packages -g '*.cs'- Search
Packages/,Library/PackageCache/and the wrapper interfaces, neverAssets/alone.rg 'Addressables\.Load*'overAssets/returns zero on a fully working Addressables game: loads go throughIAssetManager(com.theone.resourcemanagement→AddressablesAssetManager, a registry package whose source sits inLibrary/PackageCache/), called fromgdk.core. Verified path (2026-10-20):GameFoundationVContainer.csRegisterAddressablesAssetManager()→AssetsLoader(IAsyncEarlyLoadable) →LoadAllAsyncfor thePreloadSprite,PreloadGameObjectandPreloadAudioCliplabels at boot.TheOneFeature/UITemplateservices also take the interface. - An entry being addressable is not evidence anything loads it — and a missing direct call is not
evidence nothing does. Catalog and groups live in
AddressableAssetsData/,*AssetGroups/*.asset. - State the grep scope with every negative (
zero across Assets/ and Packages/, exact command,rules/negative-result-scope.md). A bare “nobody loads this” is not a finding. - “Inert” stays UNVERIFIED until a build with the
aatree stripped boots and plays. Scans miss string keys,Resources.Loadliterals, scene-placed refs. - Referenced twice is a real finding — an asset in a
Resourcesbank’s serialized refs AND in an Addressables group ships twice. Verified on WarShip by GUID set intersection: 558 guids ofWarShipUIArtBank.assetalso appear inAssetGroups/*.asset(52.6 MiB as loose player files).
3. Import audit
Section titled “3. Import audit”python3 -I scripts/import_audit.py <UnityProject>/Assets --dupes-top 20python3 -I scripts/import_audit.py <UnityProject>/Assets/Art --jsonPrints (a) a texture histogram for maxTextureSize, textureCompression, crunchedCompression,
enableMipMap, isReadable and the platform-override count, (b) audio loadType / forceToMono /
preloadAudioData with disk bytes per loadType, (c) sha256 duplicate groups with redundant bytes —
targets and the estimate-vs-measure rule in references/import-budgets.md.
- Platform overrides present?
platform overrides 0means Android and WebGL inherit the editor default: one setting for every target. maxTextureSizevs real need, ASTC block size (4x4 = 2× the memory of 6x6), Crunch, mipmaps on UI sprites, non-POT, JPEG data wearing a.pngextension.- Byte-identical duplicates (sha256): the same page under two trees for different bundles is paid twice.
- Audio
loadTypeby clip length: long music → Streaming, short SFX → DecompressOnLoad or CompressedInMemory.preloadAudioData: 1on a long clip is resident RAM at boot. TMP font assets with an embedded atlas plus a large kerning table, and CJK TTFs used only as fallbacks, are the other two per-asset costs.managedStrippingLevel/ IL2CPP code generation covers the code half.
4. Startup, memory and per-frame cost
Section titled “4. Startup, memory and per-frame cost”Trace boot as a call order and name each step’s cost source (references/startup-and-runtime.md):
synchronous main-thread table loads (File.ReadAllText per file with no yield, one frame; on device
one UnityWebRequest per file, one wait each) · raw JSON retained after parse · eager container
build callbacks · a one-shot Resources.Load of a large bank whose serialized refs all load with
it · targetFrameRate / vSyncCount (vSync must be 0 for a cap to apply). Per-frame cost is
cache-and-guard shapes, never GC settings: path-string node lookup, per-spawn table parsing,
unguarded text/fillAmount writes, per-actor writes under one Canvas, structural ECS change per
bullet, managed EntityManager per tick — cost and fix per shape in the same reference.
5. WebGL test build — stub the SDKs
Section titled “5. WebGL test build — stub the SDKs”A WebGL build made to TEST (boot, playthrough, bug-finding, perf smoke) is not a product build:
exclude as many third-party SDKs as possible and fall through to the library’s no-op / null-object
providers instead of porting them. WarShip: Firebase (no WebGL plugin → CS0246/CS0400), ads and
mediation, attribution, analytics, IAP, notifications, PlayFab. Order: (a) exclude the SDK-owning
asmdefs from WebGL (excludePlatforms) and keep the NoOp path compiling via #if !UNITY_WEBGL;
(b) a WebGL-only define set from the build script, never in ProjectSettings, so mobile is untouched;
(c) never patch Packages/ or a submodule — the fix is a PR in the owning repo. Real third-party
behaviour is verified on the device build, never here. Verified facts and error signatures:
references/webgl.md; the headless serve → Playwright → screenshot → server-log recipe is
references/webgl-boot-test.md.
Building it is a second set of failures (LZMA bundles, an empty WebGL: define set, the single
giant IL2CPP translation unit, pre-build gates): references/webgl-build.md.
6. What is inside the artifact
Section titled “6. What is inside the artifact”Weighing (§1) ranks contributors; this step opens them. Full recipes:
references/artifact-census.md (player/bundle contents, duplicates) and
references/code-size-anatomy.md (wasm sections, per-assembly C++, strip rate).
- The Build Report category table is runtime memory, not file bytes (“Uncompressed usage by
category”: a 96 MB
.datareported 356.5 MB of textures). Rank with it, never budget with it. An incremental build prints no per-asset table and may not have regenerated IL2CPP. - Uncompressed textures are usually a dimension bug. A texture whose width or height is not
divisible by 4 cannot block-compress; the importer falls back to RGBA32/RGB24 while the
.metastill saysNormal. Censusm_TextureFormat× dims (UnityPy). - Ship-twice: reachable from a
Resources/bank and an Addressables group means it ships in both. Match by(name, bytes, w, h)ormd5(get_raw_data()). - Code-dominant: parse the wasm sections first; generic instantiations dominate generated C++, and
a blanket
preserve="all"link.xmldefeats stripping (measure pre- vs post-link).
Hard rules
Section titled “Hard rules”- A cheap-model static audit over-claims. Real cases: used Spine skeletons called “unwired”;
hundreds of sprites called dead while nearly all were referenced from Addressables groups. “No
prefab reference” is not “unused” where art is loaded by key from an art bank. Re-verify every
load-bearing claim against a measured artifact, and state the class of evidence, not just the
verdict. Numbers:
references/warship-r1-findings.md. - A
grep 'Addressables.Load*'overAssets/that returns nothing proves nothing — see §2. - WebGL
SBP ErrorErroris not its own error: it is the player-script compile failing insideBuildPlayer(BuildPlayerScriptsreturnsReturnCode.Error). Fix the CS errors first; a wasm IL2CPP clang step can run over an hour, so setT1K_UNITY_BATCH_TIMEOUT_SEC=10800. - A WebGL build cannot decompress LZMA bundles. The build only warns
(“uses LZMA compression, which cannot be decompressed on WebGL”); in the browser it is
Decompressing this format (1) is not supported on this platform, thenRemoteProviderException, thenNo Locale could be selectedand the UI silently falls back to the default language. Switch the WebGL entry point’s LZMA groups to LZ4 beforeBuildPlayerand restore infinally; audit withgrep -h "m_Compression" .../Schemas/*.asset | sort | uniq -c(2is LZMA).references/webgl-build.md. - No
WebGL:entry underscriptingDefineSymbolsmeans a WebGL build with none of your defines.#if THEONEcode compiles out and aGetSingleDerivedType<T>()lookup throws: splash freezes at 100%, no error without a browser console. Diff the per-platform define lines before the first build. - A WebGL build stuck at 2728 of 2750 steps is one translation unit, not a hang. Read
[BUSY nnns] C_WebGL_wasm ...in the log; a fixed 3000 s gate ceiling killed two builds here (exit 125) where 6600 s finished. Checkuptimefirst, and never use a Development build as the test target. - A produced folder is not a verified build: check it headlessly in Playwright (swiftshader
args,
page.on('console')) overpython3 -m http.server, because the LZMA and empty-define failures appear only there, first frame at 8 s in the observed run. Recipe:references/webgl-boot-test.md. - A submodule bump can add pre-build gates that fail the player build (duplicate Addressables
address,
LocalizationMissingKey). Fix the data: they fail the Android/Jenkins build too, andT1K_SKIP_LOCALIZATION_KEY_GATE=1is not a fix. - Read a shipped file by parsing its container, not by hexdumping an offset.
.data/ bundle member offsets index the decompressed blob; a hexdump at a raw file offset reads other bytes. One such read produced an apparent finding that had to be withdrawn. - Verify every load-bearing claim by reading the cited source line before it enters a report.
- One Unity job at a time (a second compile/refresh on top of the first crashes the Editor);
headless by default (
rules/unity-headless-by-default.md), never Reimport All (rules/unity-forbidden-operations.md). A negative needs its scope: paths + exact command.
Related
Section titled “Related”t1k:gamedev:optimize:perf-loop— the engine-neutral loop; itst1k-gamedev-optimize-perf-loop/references/adapter-perf.mdcarries the Unityperf.metrics/build.sizeReportentries pointing back at these two scripts.t1k:unity:mobile:core(platform settings, budgets) ·t1k-unity-base-addressables(bundle setup) ·t1k-unity-ui-mobile-ui(canvas/uGUI) ·t1k-unity-dots-core-performance(Burst/jobs).- References:
apk-contributors.md·import-budgets.md·startup-and-runtime.md·webgl.md·webgl-build.md·artifact-census.md·code-size-anatomy.md·webgl-boot-test.md·atlas-audit.md·report-template.md·warship-r1-findings.md(worked example, example-labelled numbers).