Skip to content

t1k:cocos:playable:build-size

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: build size, engine module, fbx compression, gltf compression, headless build, mesh compress, mesh dedup, meshopt, model compression, physics sweep, texture compression

/t1k:cocos:playable:build-size

Optimize Cocos Creator 3.8.7 playable ad builds for the ad-network size budget — a flat 4.8 MB studio cap by default, read from build.sizeBudgetMB in the layered t1k-config-cocos*.json fragments (see § Ad Network Size Limits). Does NOT handle game logic (use t1k-cocos-playable-gameflow), parameters (use t1k-cocos-playable-parameter), or SDK integration (use t1k-cocos-playable-sdk-core).

The read-only audit is aggregation-and-arithmetic against a fixed budget table; applying any optimization is a judgment-gated file edit (routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”):

StepAgent
Full Size Audit: read engine.json / builder.json / .meta settings, count assets, and tabulate current size vs the per-network budget tablet1k-metrics-reporter
Report findings with estimated savings per line item off the stated optimization tables (§ 1–7)t1k-metrics-reporter
Judge WHICH engine modules are actually safe to crop for this project’s gameplay (false-positive-heuristic risk, meshopt/meshCompress interaction)stays on a reasoning tier — the tables state options, not which apply here
Apply Optimizations workflow: any Edit/Write on engine.json, builder.json, or .fbx.meta/.gltf.meta/.glb.metastays on a write-capable, reasoning tier — mandatory Step 0 AskUserQuestion editor-closed gate, never cheap tier

t1k-metrics-reporter has no Edit/Write tool, which matches the audit’s own read-only shape — Step 0’s editor-closed confirmation and the readback protocol are both destructive-blast-radius work per theonekit-core/.claude/modules/t1k-base/rules/always-ask-on-unresolved.md § 6, and stay off it entirely.

The studio cap is a flat 4.8 MB per deliverable, all networks — the pass mark the shared Jenkins size check uses, and the standing studio default. It comes from config, not from this skill:

build.sizeBudgetMB.default → 4.8 (kit p90, theonekit-cocos)
build.sizeBudgetMB.perNetwork[net] → {} (empty by default)

Effective budget for a network = perNetwork[net] ?? default.

Per-network numbers are not shipped as a table any more. They moved to references/network-size-limits.md, where each row carries its source URL, retrieval date and a verbatim quote — or is explicitly marked no located origin. Only Meta/Facebook’s ceiling is verified (5 MB, Meta’s own page, retrieved 2026-09-20); the remaining rows are unsourced and still contradict the 4.8 MB cap, and their Format column contradicts SuperHtml/conf/channels.json. Read that file before copying a number out of it; treat an unverified row as a claim, not a fact.

Write a project-scope fragment at .claude/t1k-config-cocos-project.json, "priority": 100 — never the kit’s own t1k-config-cocos.json, which t1k modules update key-merges. Restate default whenever you name perNetwork. Worked examples, the merge rule, and what the gate’s WARN means: references/network-size-limits.md § “How to use this file”.

The CLI exit code is the gate. scripts/playable-build.cjs — a zero-dep, cross-platform Node script — measures a SuperHtml output tree, applies the configured budget, and exits non-zero on any breach. Run it from the checkout root after a headless build (§ 8) — it discovers the project itself:

Terminal window
bun .claude/skills/t1k-cocos-playable-build-size/scripts/playable-build.cjs \
--gate --out build-report.json

Exit codes: 0 every gated file passed · 1 at least one failed (over budget, a channel that produced no deliverable, or a forbidden .ogg) · 2 the gate could not run, or a usage error (unknown flag, a flag with no value, --budget-mb that is not a positive number). Under --verdict a “could not run” is a {status:"unknown"} object on stdout with exit 0, because the checkpoints contract separates ran from crashed, never green from red — a red still exits 0 there.

The gate discovers the Cocos project under the search root and measures the first existing build dir (super-html wins); the .ogg scan follows Jenkins. Rules and the --build-dir override: references/gate-discovery.md.

Every .html/.zip file is gated separately, one row each — a facebook/ or nefta/ channel ships both formats, and google/gdt/pangle each carry three orientation zips. Channels in build.sizeGate.excludeNetworks (default ["common"], the unminified shared bundle no network uploads) are measured and reported but not gated.

--budget-mb N overrides the config for one run; a malformed config budget is a miss, not a crash. --networks, --verdict and the budget-source rules: references/gate-discovery.md § “Gate flags”.

Ship-time reuse line (check id ship-reuse). The gate prints one [reuse-ship] line before the size table; mode, waiver and the no data rule: references/ship-reuse-line.md. Run alone: bun .claude/skills/t1k-cocos-playable-build-size/scripts/reuse-ship-check.cjs --help.

1. Engine Module Pruning (Biggest Impact: 4–6 MB savings)

Section titled “1. Engine Module Pruning (Biggest Impact: 4–6 MB savings)”

File: settings/v2/packages/engine.json

Minimal modules for a 2D playable ad:

"includeModules": [
"2d", "affine-transform", "animation", "audio", "base",
"gfx-webgl", "graphics", "mask", "particle-2d",
"rich-text", "tween", "ui"
]

Modules to REMOVE (with sizes): See references/engine-modules-guide.md

To modify: Open Cocos Editor → Project Settings → Feature Cropping. Or edit engine.json directly — update both cache (_value: false) and includeModules array.

Files: ConfigPath/cfgTemplate.json, ConfigPath/cfgAndroidTemplate.json

SettingOptimal ValueWhy
experimentalEraseModulestrueEngine-module erase flag; savings unmeasured (verify, see build-config-reference). May disable import.meta / dynamic import()
gfx-webgl2 (overwrite)"off"WebGL2 backend adds ~200 KB (est.); Cocos 3.8.6 PREFERS WebGL2 and falls back to WebGL1 (device-manager.ts:157,174,177). Disabling forces WebGL1 — do a visual pass: NPOT textures with REPEAT wrap/mipmaps, MSAA on offscreen targets, and GLSL3-only effects can fail on the WebGL1 path (#915)
nativeCodeBundleMode"wasm"Smallest for web; "asmjs" fallback if WASM unsupported
wasmCompressionMode"brotli" (on/off)Compress remaining WASM (if any modules still need it); no gzip option in 3.8
polyfills.asyncFunctionsfalseSaves ~15 KB (est.); modern webviews support ES2017 async/await
bundleCommonChunkfalseMust be false for single-file HTML playable
sourceMapsfalseNo debug maps in production
debugfalseStrips debug assertions

Full settings reference: See references/build-config-reference.md

Where: edit texture compression in the editor under Project Settings → Compressed Textures (Cocos 3.8 docs, asset/compress-texture). The editor stores the presets in settings/v2/packages/builder.json under textureCompressConfig.userPreset; genMipmaps is nested inside textureCompressConfig, not a top-level builder.json key. Each texture’s .meta carries a userData.compressSettings.presetId that resolves against userPreset. The measured 2026-10-27 incident in references/incident-history.md read this store on 3.8.7

SettingOptimalCurrent Issue
genMipmapsfalseMipmaps add ~33% to texture data; useless for flat 2D. Exception: a 3D model texture drawn minified needs mips (references/platform-compression.md)
Compression quality70–80Quality 10 causes artifacts; 80 balances size/quality
WebP formatAdd "webp": { "quality": 80 } — web target onlyPNG-only misses 25–35% savings on web. For a single-file super-html playable, listing png AND webp in one preset ships BOTH — the entries are additive, not a fallback
Uncompressed texturesApply preset to ALLCheck all .meta files have compressSettings

Full texture & audio guide: See references/texture-audio-optimization.md

Full games (not single-file playables) also need atlas, ASTC/ETC2, duplicate-art and launcher-icon checks: references/full-game-asset-checks.md (the atlas gate is scripts/check-atlas-oversize.cjs <cocos-root>).

Target: MP3 (never OGG — the .ogg gate fails it), mono, 96 kbps for SFX, 128 kbps for BGM. Use optimize-size tool.

Terminal window
cd CocosPlayableAdsTemplate/tools/optimize-size && bun start
# Opens http://localhost:3456 — browse and compress audio files
  • 3D ParticleSystem imports force 3d + particle modules. Use ParticleSystem2D instead.
  • import * as cc from "cc" pulls entire namespace — import specific classes.
  • Both SDK adapters always bundled via SdkFactory. Minor issue, both are small.
  • fs-extra in dependencies — should be devDependencies (editor-only).
  • Remove unused assets from game-assets/vfx/ before shipping
  • Cocos only bundles scene-referenced assets, but accidental references happen
  • Use optimize-size tool to identify large source assets
  • Check for a bundled third-party demo/sample scene. A scene living inside an installed @playablelabs/* package (e.g. assets/packages/@playablelabs/motion/demo.scene) is bundled by the build like any other scene by default, and can drag in its own default assets (measured: 0.85 MB of default skybox cubemaps from a motion-package demo scene never used by the actual playable). Restrict the build to the real scene list explicitly via a build config (--build "configPath=<json>" with an explicit scenes: [{ url, uuid }] and startScene) rather than relying on “only what’s referenced” — a package’s own demo scene can be independently registered as buildable and slip past a purely reference-based audit.

7. Model Compression (FBX / glTF) — Optional, only if shipping 3D

Section titled “7. Model Compression (FBX / glTF) — Optional, only if shipping 3D”

If the playable contains 3D meshes (*.fbx, *.gltf, *.glb under game-assets/), per-asset .meta editing of meshCompress.compress alone typically halves mesh .bin files (≈48% measured), on top of whatever meshSimplify (target-ratio decimation) buys. On Cocos Creator 3.8.7 start with compress: true only — on FBX, quantize and encode both crash the editor’s meshopt_encoder wasm with RuntimeError: memory access out of bounds, taking the mesh sub-assets down with them (Importer exec failed, runtime The asset <uuid>@<sub> is missing!), and compress alone is lossless (11.4 MB → 5.9 MB across 151 sub-assets). Static .glb sets can take all three; see the strategy split below.

Before compressing, deduplicate. The FBX importer emits one mesh sub-asset per FBX NODE, even when multiple nodes share identical geometry (Blender linked duplicates) — a scene with many placed instances of a few unique models can build far more .bin bytes than the unique geometry justifies. Deduplication is a zero-quality-cost win and should run BEFORE compression, not after: retarget duplicate cc.MeshRenderer._mesh references onto one canonical sub-asset per unique mesh in the scene JSON (no FBX edit required — an unreferenced sub-asset is not emitted by the build). Full procedure, MD5-verification method, and a measured 5.73 MB → 1.76 MB result: references/mesh-dedup-shared-geometry.md.

Critical interaction: meshCompress.encode: true REQUIRES the meshopt engine module to be enabled. If you previously cropped meshopt per § 1, you must re-enable it before turning encode on — otherwise runtime crashes with meshopt_decoder undefined. (It applies whenever you enable encode, per the strategy split below.)

Strategy split:

  • Static meshes (field, props, ball) — compress is the safe default. quantize + encode on top is the biggest mesh lever where the importer accepts it: on UFOPLA’s static .glb sets (every mesh within ~32 m of its origin, half-float error ≤ 8 mm) the three combined cleanly and halved the meshes (2026-10-23), while the FBX crashes above (multi-bundle meshes, vendor FBX in the CLI importer) still stand. Enable it per asset, then confirm "quantized":true / "encoded":true in the built JSON, an import log free of Importer exec failed, and a booting build — never the HTML size alone. Keep meshes larger than ~32 m float32. meshSimplify only after measuring it: on flat-shaded low-poly models it barely reduces anything and can delete thin coplanar surfaces (water)
  • Skinned meshes (character, hair, hands) — compress only; the importer refuses quantize on skinned data (Attribute a_joints has different format) and meshopt encode grows float32 skins. meshSimplify.enable: false (or targetRatio: 0.7+) to preserve skin weights
  • Every model: tangents: 1 (Exclude) unless a material samples a normal map or an effect reads a_tangent — 16 bytes off every vertex. The .meta value is an enum INDEX, not a boolean: optional=0, exclude=1, require=2, recalculate=3 (Creator 3.8.7, cocos-engine editor/inspector/assets/fbx/model.js, which builds the select from ['optional','exclude','require','recalculate'] and defaults an ABSENT key to 2 = Required). 0 is Optional: it keeps tangents the file already carries, so on a glTF with no TANGENT attribute it imports none and the saving appears anyway — but on an FBX, or a glTF that does carry tangents, 0 imports them and the saving silently does not happen. Confirm the lever landed by reading the reimported .meta back for "tangents": 1, then the .bin vertex stride, never the HTML size alone

3D playable to single-file budget (17 → 4.5 MB measured): crowd folding, dumped shared materials, dropping builtin-standard, joint stripping, delta-coded level data, loudness-matched mono audio, and how to measure the HTML before Jenkins: references/3d-single-file-playbook.md. Runtime cost (draw calls, stalls, memory) is t1k-cocos-playable-runtime-perf.

Full workflow including pre-change checklist, red-flag breakage table, rollback steps, and batch-script template: references/model-compression-guide.md. The userData.meshCompress schema is confirmed real and editor-initialised (Mesh Optimizer panel) — see the resolved-keys section at that guide’s top, which carries the crash evidence and the compress-only default.

A fresh worktree build exits 36 with a broken scene: seed temp/programming/packer-driver and gate on Missing class = 0. Why it runs detached and the full trap: references/headless-verification-overview.md; procedure: references/headless-cli-build-detached.md.

9. Physics Module — Sweep Queries Are physics-ammo/physics-physx-Only

Section titled “9. Physics Module — Sweep Queries Are physics-ammo/physics-physx-Only”

physics-builtin has no sweepSphere/sweepBox, so a sweep-only reason to ship physics-ammo can often become a raycastClosest ring: references/physics-sweep-scope.md, worked TypeScript in references/physics-sweep-raycast-ring-workaround.md.

Use direct file reads for engine and build configuration; no MCP tool exposes or mutates engine modules:

  1. Check engine modules — read settings/v2/packages/engine.json directly with Read/Grep.
  2. Check build config — read settings/v2/packages/builder.json and ConfigPath/*.json directly with Read/Grep.
  3. Check texture configuration — inspect builder.json and texture .meta files directly.
  4. Scan code for 3D imports — use Grep with ParticleSystem[^2].
  5. Audit assets and dependencies — manage_asset → get_dependencies (params url / urlOrUUID / assetPath, plus direction: dependents | dependencies | both) answers “who references this asset”, which is the safe form of the delete question. There is no unused-asset action in the MCP: get_unused was advertised but never implemented (its handler returned a fixed stub), and it was unadvertised upstream in #133 (5bf8e50). For genuine orphan detection use t1k-cocos-playable-modularize-reuse-scan’s verify-reachability.cjs — four independent checks (TS importers, scene/prefab attachment on full decoded uuids, prefab nesting, resources.load refs), which an import-graph scan cannot substitute for.
  6. Check audio sizes — use the repository’s size-analysis tooling; there is no audio-stats MCP action.
  7. Report findings with severity and estimated savings

Steps 0-2 detail — see references/apply-steps.md

Section titled “Steps 0-2 detail — see references/apply-steps.md”

Step 0’s AskUserQuestion editor-closed gate is mandatory for an ATTENDED run; a run with no human reachable (headless, --yolo) takes Step 0b instead — a process probe that proceeds only on a clean absence, reports gate=autonomous-probe, and skips the section when the editor is detected or unprobeable, never silently (#1436). § 2’s only target, ConfigPath/cfgTemplate.json, lives in a git submodule — when it is uninitialised, report the state and mark § 2 not audited rather than inventing numbers.