Skip to content

t1k:playablelabs:cocos:build-facts

FieldValue
Modulecocos
Version1.4.1
Effortmedium
Tools—

Keywords: cocos 3.8 packer input, cocos class table, cocos physics crop, cocos playable build layout, cocos web-mobile build tree, cocos-js engine layout

/t1k:playablelabs:cocos:build-facts
[build tree | class table | physics crop]

Cocos 3.8 build facts for the pack pipeline

Section titled “Cocos 3.8 build facts for the pack pipeline”

For a developer shipping a Cocos Creator 3.8 playable through the PlayableLabs packer with only this kit installed: what the packer reads from your build, what to pass it, and which Cocos behaviours surprise people. You do not need a packer clone; packing and smoke run in CI. Authoring game code, scenes and the in-editor build-size work belong to the Cocos kit (theonekit-cocos: t1k-cocos-playable-build-size, t1k-cocos-playable-sdk-core, t1k-cocos-playable-pipeline). Flags, exit codes and pack-report.json are t1k-playablelabs-base-pack; this skill does not restate them.

The packer’s input is the Creator build/web-mobile directory of a Cocos Creator 3.8.x project, packed with the Cocos host. Name the host explicitly every time, in pack AND smoke:

Terminal window
pla-pack --build <project>/build/web-mobile --out <out> --engine-host cocos-3.8 --json > pack-report.json

cocos-3.8 is what the packer assumes when the flag is absent, but nothing checks that the flag and the build agree, so state it. A bundler dist/ is a different host (web): t1k-playablelabs-base-engine-hosts.

FactConsequenceDetail
The build tree has a fixed shape (cocos-js/, application.js, assets/<bundle>/import and native, src/)A tool or script you write against a build must expect exactly that treereferences/build-tree.md
Import JSON class tables mix cc.* names with compressed custom-script idsCode that treats every entry as cc.* misses your own componentsreferences/class-table.md
Cropping physics (Bullet) changes the engine layout under cocos-js/Never find the engine core by chunk namereferences/engine-layout.md
--optimize is opt-in; with no flag the pack is byte-identical to a build from before the optimize moduleSize work is something you turn on and then measure, never a defaultt1k-playablelabs-optimize-passes
Four optimize passes are Cocos-only: engine-module-prune, anim-extraction, mesh-simplify, texture-downscaleThey exist for this host only; they refuse or skip elsewheret1k-playablelabs-optimize-passes
--optimize-audio-mono is lossy and deliberately outside --optimizeNeeds a listening check per game before it shipst1k-playablelabs-optimize-passes
--optimize-font-subset needs pyftsubset on the packing machine, and --font-keep-chars <file> for text that only appears at runtimeA subset that drops a glyph shows a missing character only for that textt1k-playablelabs-optimize-passes
audit-modules and smoke --canary are Cocos-onlyThey compare the engine modules the game declares with the ones it usest1k-playablelabs-base-pack, t1k-playablelabs-base-smoke

Order of preference when behaviour must change: a per-project module switch or a Creator build-config change first, then packer runtime or adapter code, and only then a minimal patch to the studio engine fork. If you think you need an engine patch, stop and report; it needs a human decision. The full rule and the proof that Cocos output did not move are playablelabs-cocos-zero-change and t1k-playablelabs-base-change-proof (both in base; linked, not copied).

Content source: the packer’s own Cocos build notes and project skill at PlaybleEngine@1a63595 (2026-10-13; the two source files last changed at ea8db18), read for this module, not re-derived from a fresh build. Figures and heuristics in the references are tagged unverified where they rest on one observation.

  • Do not locate engine code by chunk name; use the dependency list of cc.js (references/engine-layout.md).
  • A script that walks an import JSON class table must handle both entry shapes (references/class-table.md).
  • Leaving --engine-host off is silent: the packer will not warn that the host and the build disagree.