Skip to content

t1k:unity:mobile:build-size

FieldValue
Modulemobile
Version3.65.6
Effortmedium
Tools—

Keywords: aab size, addressables bundles, apk size, build size, dead assets, import settings, mobile memory, startup time, texture compression, webgl build

/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.

IntentGo 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 reportreferences/report-template.md
Before trusting any of the aboveHard rules

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.

Terminal window
python3 -I scripts/apk_breakdown.py Builds/android-dev/app.apk --top 10 # --json for a machine consumer
python3 -I scripts/apk_breakdown.py Builds/android-dev/app.aab # strips base/, detects BundleConfig.pb

Prints 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 Development flag + scripting backend + ABI set with every number. A Development build is not size-representative (debug symbols, no stripping); shipping armv7+arm64 doubles lib/. Also record useCustomMainManifest and the manifest’s versionCode when the APK is for release: a checked-in manifest with useCustomMainManifest: 1 is authoritative (t1k-unity-mobile-core Hard rules).
  • Unity’s own report: the Build Report section of Editor.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.

Addressables/Resources content is dead only if nothing loads it. Prove the loader first.

Terminal window
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, never Assets/ alone. rg 'Addressables\.Load*' over Assets/ returns zero on a fully working Addressables game: loads go through IAssetManager (com.theone.resourcemanagement → AddressablesAssetManager, a registry package whose source sits in Library/PackageCache/), called from gdk.core. Verified path (2026-10-20): GameFoundationVContainer.cs RegisterAddressablesAssetManager() → AssetsLoader (IAsyncEarlyLoadable) → LoadAllAsync for the PreloadSprite, PreloadGameObject and PreloadAudioClip labels at boot. TheOneFeature/UITemplate services 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 aa tree stripped boots and plays. Scans miss string keys, Resources.Load literals, scene-placed refs.
  • Referenced twice is a real finding — an asset in a Resources bank’s serialized refs AND in an Addressables group ships twice. Verified on WarShip by GUID set intersection: 558 guids of WarShipUIArtBank.asset also appear in AssetGroups/*.asset (52.6 MiB as loose player files).
Terminal window
python3 -I scripts/import_audit.py <UnityProject>/Assets --dupes-top 20
python3 -I scripts/import_audit.py <UnityProject>/Assets/Art --json

Prints (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 0 means Android and WebGL inherit the editor default: one setting for every target.
  • maxTextureSize vs real need, ASTC block size (4x4 = 2× the memory of 6x6), Crunch, mipmaps on UI sprites, non-POT, JPEG data wearing a .png extension.
  • Byte-identical duplicates (sha256): the same page under two trees for different bundles is paid twice.
  • Audio loadType by clip length: long music → Streaming, short SFX → DecompressOnLoad or CompressedInMemory. preloadAudioData: 1 on 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.

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.

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.

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 .data reported 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 .meta still says Normal. Census m_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) or md5(get_raw_data()).
  • Code-dominant: parse the wasm sections first; generic instantiations dominate generated C++, and a blanket preserve="all" link.xml defeats stripping (measure pre- vs post-link).
  • 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*' over Assets/ that returns nothing proves nothing — see §2.
  • WebGL SBP ErrorError is not its own error: it is the player-script compile failing inside BuildPlayer (BuildPlayerScripts returns ReturnCode.Error). Fix the CS errors first; a wasm IL2CPP clang step can run over an hour, so set T1K_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, then RemoteProviderException, then No Locale could be selected and the UI silently falls back to the default language. Switch the WebGL entry point’s LZMA groups to LZ4 before BuildPlayer and restore in finally; audit with grep -h "m_Compression" .../Schemas/*.asset | sort | uniq -c (2 is LZMA). references/webgl-build.md.
  • No WebGL: entry under scriptingDefineSymbols means a WebGL build with none of your defines. #if THEONE code compiles out and a GetSingleDerivedType<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. Check uptime first, 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')) over python3 -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, and T1K_SKIP_LOCALIZATION_KEY_GATE=1 is 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.
  • t1k:gamedev:optimize:perf-loop — the engine-neutral loop; its t1k-gamedev-optimize-perf-loop/references/adapter-perf.md carries the Unity perf.metrics / build.sizeReport entries 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).