t1k:cocos:playable:build-size
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: build size, engine module, fbx compression, gltf compression, headless build, mesh compress, mesh dedup, meshopt, model compression, physics sweep, texture compression
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:build-sizeCocos Playable Build Size Optimization
Section titled “Cocos Playable Build Size Optimization”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).
Executed by
Section titled “Executed by”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”):
| Step | Agent |
|---|---|
Full Size Audit: read engine.json / builder.json / .meta settings, count assets, and tabulate current size vs the per-network budget table | t1k-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.meta | stays 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.
Ad Network Size Limits
Section titled “Ad Network Size Limits”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.
Overriding the budget
Section titled “Overriding the budget”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”.
Automated Budget Gate (CLI)
Section titled “Automated Budget Gate (CLI)”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:
bun .claude/skills/t1k-cocos-playable-build-size/scripts/playable-build.cjs \ --gate --out build-report.jsonExit 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.
Size Optimization Checklist
Section titled “Size Optimization Checklist”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.
2. Build Config Tuning
Section titled “2. Build Config Tuning”Files: ConfigPath/cfgTemplate.json, ConfigPath/cfgAndroidTemplate.json
| Setting | Optimal Value | Why |
|---|---|---|
experimentalEraseModules | true | Engine-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.asyncFunctions | false | Saves ~15 KB (est.); modern webviews support ES2017 async/await |
bundleCommonChunk | false | Must be false for single-file HTML playable |
sourceMaps | false | No debug maps in production |
debug | false | Strips debug assertions |
Full settings reference: See references/build-config-reference.md
3. Texture Optimization
Section titled “3. Texture Optimization”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
| Setting | Optimal | Current Issue |
|---|---|---|
genMipmaps | false | Mipmaps add ~33% to texture data; useless for flat 2D. Exception: a 3D model texture drawn minified needs mips (references/platform-compression.md) |
| Compression quality | 70–80 | Quality 10 causes artifacts; 80 balances size/quality |
| WebP format | Add "webp": { "quality": 80 } — web target only | PNG-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 textures | Apply preset to ALL | Check 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>).
4. Audio Optimization
Section titled “4. Audio Optimization”Target: MP3 (never OGG — the .ogg gate fails it), mono, 96 kbps for SFX, 128 kbps for BGM. Use optimize-size tool.
cd CocosPlayableAdsTemplate/tools/optimize-size && bun start# Opens http://localhost:3456 — browse and compress audio files5. Code-Level Optimizations
Section titled “5. Code-Level Optimizations”- 3D ParticleSystem imports force
3d+particlemodules. UseParticleSystem2Dinstead. import * as cc from "cc"pulls entire namespace — import specific classes.- Both SDK adapters always bundled via
SdkFactory. Minor issue, both are small. fs-extrain dependencies — should bedevDependencies(editor-only).
6. Asset Audit
Section titled “6. Asset Audit”- Remove unused assets from
game-assets/vfx/before shipping - Cocos only bundles scene-referenced assets, but accidental references happen
- Use
optimize-sizetool 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 explicitscenes: [{ url, uuid }]andstartScene) 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) —
compressis the safe default.quantize+encodeon top is the biggest mesh lever where the importer accepts it: on UFOPLA’s static.glbsets (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":truein the built JSON, an import log free ofImporter exec failed, and a booting build — never the HTML size alone. Keep meshes larger than ~32 m float32.meshSimplifyonly 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) —
compressonly; the importer refusesquantizeon skinned data (Attribute a_joints has different format) and meshoptencodegrows float32 skins.meshSimplify.enable: false(ortargetRatio: 0.7+) to preserve skin weights - Every model:
tangents: 1(Exclude) unless a material samples a normal map or an effect readsa_tangent— 16 bytes off every vertex. The.metavalue is an enum INDEX, not a boolean:optional=0, exclude=1, require=2, recalculate=3(Creator 3.8.7,cocos-engineeditor/inspector/assets/fbx/model.js, which builds the select from['optional','exclude','require','recalculate']and defaults an ABSENT key to2= Required).0is Optional: it keeps tangents the file already carries, so on a glTF with noTANGENTattribute it imports none and the saving appears anyway — but on an FBX, or a glTF that does carry tangents,0imports them and the saving silently does not happen. Confirm the lever landed by reading the reimported.metaback for"tangents": 1, then the.binvertex 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.
8. Headless Verification Builds
Section titled “8. Headless Verification Builds”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.
Workflow: Full Size Audit
Section titled “Workflow: Full Size Audit”Use direct file reads for engine and build configuration; no MCP tool exposes or mutates engine modules:
- Check engine modules — read
settings/v2/packages/engine.jsondirectly with Read/Grep. - Check build config — read
settings/v2/packages/builder.jsonandConfigPath/*.jsondirectly with Read/Grep. - Check texture configuration — inspect
builder.jsonand texture.metafiles directly. - Scan code for 3D imports — use Grep with
ParticleSystem[^2]. - Audit assets and dependencies —
manage_asset→get_dependencies(paramsurl/urlOrUUID/assetPath, plusdirection: 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_unusedwas advertised but never implemented (its handler returned a fixed stub), and it was unadvertised upstream in #133 (5bf8e50). For genuine orphan detection uset1k-cocos-playable-modularize-reuse-scan’sverify-reachability.cjs— four independent checks (TS importers, scene/prefab attachment on full decoded uuids, prefab nesting,resources.loadrefs), which an import-graph scan cannot substitute for. - Check audio sizes — use the repository’s size-analysis tooling; there is no audio-stats MCP action.
- Report findings with severity and estimated savings
Workflow: Apply Optimizations
Section titled “Workflow: Apply Optimizations”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.