t1k:cocos:playable:build-size

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	playable
Version	0.5.6
Effort	high
Tools	—

Keywords: ads, build size, cocos, engine module, FBX, glTF, mesh compress, meshopt, model compression, optimization, playable, texture compression

How to invoke

/t1k:cocos:playable:build-size

---

Cocos Playable Build Size Optimization

Optimize Cocos Creator 3.8.7 playable ad builds for ad network size budgets (2–5 MB). 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).

Ad Network Size Limits

Network	Max Size	Format
Meta/Facebook	2 MB	Single HTML
Google Ads	5 MB	Single HTML or ZIP
Unity Ads	5 MB	Single HTML
IronSource	5 MB	ZIP
AppLovin	5 MB	Single HTML
TikTok	2 MB	Single HTML
Voodoo	5 MB	Single HTML
Mintegral	5 MB	ZIP

Size Optimization Checklist

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

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

Setting	Optimal Value	Why
experimentalEraseModules	true	Cocos’s JS dead-code removal. 10–30% engine JS reduction
gfx-webgl2 (overwrite)	"off"	WebGL2 backend adds ~200 KB; most ad webviews use WebGL1
nativeCodeBundleMode	"wasm"	Smallest for web; "asmjs" fallback if WASM unsupported
wasmCompressionMode	"gzip" or "brotli"	Compress remaining WASM (if any modules still need it)
polyfills.asyncFunctions	false	Saves ~15 KB; 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

File: settings/v2/packages/builder.json

Setting	Optimal	Current Issue
genMipmaps	false	Mipmaps add ~33% to texture data; useless for 2D
Compression quality	70–80	Quality 10 causes artifacts; 80 balances size/quality
WebP format	Add "webp": { "quality": 80 }	PNG-only misses 25–35% savings on web
Uncompressed textures	Apply preset to ALL	Check all .meta files have compressSettings

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

4. Audio Optimization

Target: MP3/OGG, mono, 96 kbps for SFX, 128 kbps for BGM. Use optimize-size tool.

cd CocosPlayableAdsTemplate/tools/optimize-size && npm start
# Opens http://localhost:3456 — browse and compress audio files

5. Code-Level Optimizations

• 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).

6. Asset Audit

• 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

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 (quantize + meshopt encode) and meshSimplify (target-ratio decimation) typically drops mesh .bin files by 40–70%.

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.

Strategy split:

• Static meshes (field, props, ball) — full compress + simplify targetRatio: 0.3–0.5
• Skinned meshes (character, hair, hands) — full compress but meshSimplify.enable: false (or targetRatio: 0.7+) to preserve skin weights

Full workflow including pre-change checklist, red-flag breakage table, rollback steps, and batch-script template: references/model-compression-guide.md

Workflow: Full Size Audit

If Cocos MCP Server is connected, use MCP tools for automation:

1. Check engine modules — manage_settings → get_engine_modules (or read engine.json directly)
2. Check build config — manage_settings → get with fileName: "builder" (or read files directly)
3. Check builder config — manage_settings → get_texture_config
4. Scan code for 3D imports — manage_code_analysis → scan_imports with pattern: "ParticleSystem[^2]"
5. Scan texture metas — manage_asset → get_texture_stats
6. Check audio sizes — manage_asset → get_audio_stats
7. Report findings with severity (Critical/Important/Minor) and estimated savings

Without MCP: read files directly with Read tool, use Grep for code scanning.

Workflow: Apply Optimizations

Step 0 — User Confirmation Gate (MANDATORY for direct file edits)

Before any Edit / Write tool call on engine.json, builder.json, or any .fbx.meta / .gltf.meta / .glb.meta, you MUST invoke AskUserQuestion to confirm the Cocos Editor is fully closed. No exceptions. No “I already checked Task Manager” shortcuts — the user owns this confirmation. The editor watches these files and rewrites them from its in-memory state on its next save cycle, silently clobbering your edits. Blast radius is non-trivial: optimization work that appears committed but never ships.

Required gate sequence:

1. Call AskUserQuestion BEFORE the first direct edit with prompt:

   “I’m about to edit <file> directly. Cocos Editor MUST be fully closed (verify CocosCreator.exe / Creator.exe absent in Task Manager) or my edits will be silently reverted on the editor’s next save cycle. Is the editor closed?”

2. Options: [Editor closed — proceed], [Editor open — wait, I'll close it], [Cancel].
3. Proceed ONLY on closed — proceed. On wait, pause and re-ask after the user signals closed. On cancel, stop and report.
4. Optionally cross-check: Get-Process CocosCreator -ErrorAction SilentlyContinue (PowerShell) or tasklist | findstr /i CocosCreator (cmd). If the process is detected after a closed — proceed answer, surface the mismatch to the user and re-ask — do NOT proceed silently.
5. The gate is required ONCE per workflow session for the same file set; if the user re-opens the editor mid-workflow you MUST re-gate before subsequent edits.

Exception — MCP path: if Cocos MCP Server is connected AND every mutation goes through manage_settings / manage_asset MCP tools (NOT Edit / Write), the gate is not required — MCP tools coordinate with the running editor. Any direct file edit alongside MCP work ALWAYS triggers the gate.

Exception — non-watched files: ConfigPath/cfgTemplate.json and ConfigPath/cfgAndroidTemplate.json are Jenkins build templates outside settings/v2/packages/ and are not watched by the editor — Step 0 gate not required for these specific files.

Rule basis: rules/always-ask-on-unresolved.md § 6 — “Any deletion, overwrite, or destructive action whose blast radius is non-trivial — even if you have a strong default. Ask first.” Silent-revert qualifies as destructive blast radius.

Step 1 — With MCP Server (editor-aware, no quit needed)

1. manage_settings → set_engine_modules with modules: {"3d": false, "profiler": false, ...} (syncs both cache + includeModules)
2. manage_settings → set_texture_config with config: {"genMipmaps": false}
3. manage_asset → compress_textures with presetId from builder.json presets
4. Edit cfgTemplate.json + cfgAndroidTemplate.json — apply optimal settings (no MCP tool yet; non-watched files, Step 0 gate not required)
5. Fix code — replace 3D ParticleSystem with ParticleSystem2D if appropriate
6. Rebuild in Cocos Editor and verify output size

Step 1 — Without MCP (manual direct-edit path)

Step 0 User Confirmation Gate is MANDATORY before any step below.

1. Quit Cocos Editor fully (verify in Task Manager — CocosCreator.exe absent).
2. Edit engine.json — flip _value: false AND remove from includeModules for each cropped module.
3. Edit cfgTemplate.json / cfgAndroidTemplate.json.
4. User reopens editor → declines any “re-enable module X” prompt unless grep confirms actual usage (see reference grep table).
5. Mandatory readback — re-read engine.json after reopen; confirm every cropped module is still _value: false AND absent from includeModules. Report drift explicitly. Never claim “done” before this step.

Common Mistakes

• Editing engine.json while Cocos Editor is open — editor reverts the file from its in-memory state. ALWAYS run the Step 0 User Confirmation Gate (Workflow: Apply Optimizations) before any direct edit. Never skip on the basis of “I already checked Task Manager” — the user owns the confirmation.
• Editing engine.json but forgetting to update both cache._value and includeModules — must update BOTH
• Editing the wrong config block — multiple configs can exist (migrationsConfig, custom-config-{uuid}); only the one named in modules.globalConfigKey is active.
• Reporting “modules cropped” without re-reading the file after the user reopens the editor — the editor’s auto-scan may have reverted some via false-positive heuristics.
• Trusting prior session’s “this module is already off” claims — always read the actual _value and includeModules array; never assume.
• Setting texture quality too low (10) — causes visible artifacts, especially on VFX
• Keeping profiler module enabled — adds FPS overlay code to production builds
• Forgetting genMipmaps: false — 33% texture waste, invisible in dev but bloats build
• Using "gfx-webgl2": "on" when targeting ad webviews that don’t support WebGL2
• Not applying texture compression preset to all textures (check each .meta file)
• Enabling meshCompress.encode: true while the meshopt engine module is cropped — runtime meshopt_decoder undefined crash. Always re-enable meshopt first.
• Running meshSimplify on skinned character meshes with default targetRatio: 0.4 — collapses vertices that share skin weights, producing distorted limbs. Disable simplify on skinned meshes or raise ratio to 0.7+.
• Editing .fbx.meta while Cocos Editor is open — same trap as engine.json. Editor re-imports and reverts your changes. Step 0 User Confirmation Gate applies to .fbx.meta / .gltf.meta / .glb.meta edits too.
• Deleting a .fbx.meta to “start fresh” instead of editing in place — invalidates the UUID and orphans every prefab reference. Always edit, never recreate.

Gotchas

• Cocos Editor silently reverts engine.json / builder.json / *.fbx.meta edits while open. Step 0 User Confirmation Gate (Workflow: Apply Optimizations) is MANDATORY before any direct Edit / Write tool call on these files — call AskUserQuestion to make the user confirm editor is closed. AI-side process checks (Get-Process / tasklist) supplement but do NOT replace the user confirmation. Details + active-config rule + post-edit readback protocol + false-positive grep table: references/engine-modules-guide.md § Editor Workflow Pitfalls.
• Feature cropping has no editor-visible effect. Scene/preview always renders with the full engine. Savings only appear in final BUILD output — verify via tools/optimize-size or build folder size diff, never editor view.
• Build size cap for ad networks: typically 5MB — going over silently fails on AdMob, hard-rejects on Meta.
• Inlining base64 assets blows up minified JS — keep large assets as separate URLs and gate crossOrigin: 'anonymous'.
• TerserPlugin defaults preserve class names; flip mangle: { keep_classnames: false } for an extra ~5% reduction.
• Model compression has a hard dependency on the meshopt engine module. Cropping meshopt is the right call for 2D-only playables, but the moment any .fbx.meta has meshCompress.encode: true the module becomes mandatory. Cross-check before flipping either side. Full workflow: references/model-compression-guide.md.
• .fbx.meta UUID is referenced by every prefab that uses the model. Never delete-and-recreate a .meta — always edit in place. Restoring from .meta.bak is safe; regenerating from scratch is not.
• Cocos has no project-wide model compression preset. Each .fbx.meta is configured individually. For projects with 20+ models, batch via a Node.js script (template in the reference) with the editor closed.