t1k:playablelabs:cocos:build-facts
| Field | Value |
|---|---|
| Module | cocos |
| Version | 1.4.1 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/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.
What goes in
Section titled “What goes in”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:
pla-pack --build <project>/build/web-mobile --out <out> --engine-host cocos-3.8 --json > pack-report.jsoncocos-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.
Facts that cost people time
Section titled “Facts that cost people time”| Fact | Consequence | Detail |
|---|---|---|
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 tree | references/build-tree.md |
Import JSON class tables mix cc.* names with compressed custom-script ids | Code that treats every entry as cc.* misses your own components | references/class-table.md |
Cropping physics (Bullet) changes the engine layout under cocos-js/ | Never find the engine core by chunk name | references/engine-layout.md |
--optimize is opt-in; with no flag the pack is byte-identical to a build from before the optimize module | Size work is something you turn on and then measure, never a default | t1k-playablelabs-optimize-passes |
Four optimize passes are Cocos-only: engine-module-prune, anim-extraction, mesh-simplify, texture-downscale | They exist for this host only; they refuse or skip elsewhere | t1k-playablelabs-optimize-passes |
--optimize-audio-mono is lossy and deliberately outside --optimize | Needs a listening check per game before it ships | t1k-playablelabs-optimize-passes |
--optimize-font-subset needs pyftsubset on the packing machine, and --font-keep-chars <file> for text that only appears at runtime | A subset that drops a glyph shows a missing character only for that text | t1k-playablelabs-optimize-passes |
audit-modules and smoke --canary are Cocos-only | They compare the engine modules the game declares with the ones it uses | t1k-playablelabs-base-pack, t1k-playablelabs-base-smoke |
Do not change the engine
Section titled “Do not change the engine”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).
Verified against
Section titled “Verified against”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.
Hard rules
Section titled “Hard rules”- 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-hostoff is silent: the packer will not warn that the host and the build disagree.