Skip to content

t1k:playablelabs:web:lazy-load

FieldValue
Moduleweb
Version1.18.2
Effortmedium
Tools—

Keywords: --lazy-assets, gen-playable-lazy, google h5 lazy loading, playable boot payload, playable defer assets, playable first frame assets, playable lazy generate, playable lazy load, playable-lazy.json

/t1k:playablelabs:web:lazy-load
[generate | check | contract | verify | failures]

Two-phase loading for web and none playables

Section titled “Two-phase loading for web and none playables”

Scope: the game’s first-frame asset set, the playable-lazy.json file that declares it, and what the packer defers. The generator writes the file from a first-frame trace; the packer reads it at pack time.

Not here, linked instead (single source of truth):

  • The --lazy-assets flag row and --lazy-config: t1k-playablelabs-base-pack.
  • Jenkins PARAM_LAZY_ASSETS and stage order: t1k-playablelabs-ci-jenkins.
  • The globals the smoke reads (__PLA_SCENE_UP__, __plaGame__): t1k-playablelabs-web-host-contract.
  • The dist/ layout and bundler wiring: t1k-playablelabs-web-port.
  • Frame and CPU cost: t1k-playablelabs-web-perf.

Say whether the game targets web or none before you start. --lazy-assets exits 2 on cocos-3.8. Pack and the checks below use the same engine host.

Build dist/, then run the generator from this skill’s folder (<skill-dir> is .claude/skills/t1k-playablelabs-web-lazy-load in a consumer project):

Terminal window
bun <skill-dir>/scripts/gen-playable-lazy.cjs --build dist

The default --mode runtime serves dist/ on loopback, opens it in headless Chrome and keeps every file the page requests before its first frame. It needs puppeteer-core and Chrome; without them it exits 3 and writes nothing. It never falls back to static mode silently.

Then:

  1. Read the printed summary: kept and deferred counts and bytes, and the top kept files with why.
  2. Check each top kept file is needed before the first frame. A large file that only a boot preload asks for is a game defect: fix the preload (section 3), then regenerate.
  3. Commit the file it writes (public/playable-lazy.json when public/ exists).
  4. Add a step after the build in the game’s CI: bun <skill-dir>/scripts/gen-playable-lazy.cjs --build dist --check.

Exit codes: 0 wrote or valid; 1 --check violation; 2 usage error, unusable build or refused overwrite (--force replaces a file); 3 no browser; 4 wrote the file but nothing is deferrable (section 5). Flags, trace rules and limits: references/generator.md.

--mode static needs no browser and is LOW CONFIDENCE (a literal-path scan, not a trace). Use it only when no browser exists, and say so in the delivery post.

The packer reads <build>/playable-lazy.json when --lazy-assets is on and no --lazy-config is given. An explicit --lazy-config wins. The file is metadata: it is never packed into the payload.

{ "keep": ["assets/scene-01/hero.glb", "fonts/ui-regular.woff2"], "deferRest": "rest", "idlePrefetchMs": 1500 }
FieldMeaning
keeppaths or globs held in the boot payload. Never .js, .mjs, .css, .wasm or .html (never deferred anyway)
deferRestgroup for every file that no keep glob, no defer rule and no never-deferred type holds
deferextra {group, glob} rules. The built-in audio rules stay unless onlyDefer is true
onlyDefertrue replaces the built-in audio rules instead of extending them
idlePrefetchMsms after boot before every group loads untouched. File default 1500; 0 disables it

Any other field, a malformed value or a bad group name exits 2 and names the field. Nothing is ignored silently. Group names match ^[a-z][a-z0-9-]{0,31}$ and name late-<group>.js.

Which builds apply: --lazy-assets-scope all (the default with the flag) covers every row of the host. default covers only the rows whose network adapter declares lazyAssetsDefault, which are the Google rows. Jenkins PARAM_LAZY_ASSETS: auto (default) runs --lazy-assets --lazy-assets-scope default on web and none, and nothing on cocos-3.8; off; all. The file needs no Jenkins parameter.

  • keep is exactly what the first frame reads. The evidence is the trace, not the file name.
  • Never read a deferred asset synchronously. The read may wait for its group.
  • Load a late path only through a guarded read: fetch, XMLHttpRequest, .src on Image, Audio, Video, Script or Source, or setAttribute('src'). These wait for the group. Anything else is a miss: new Audio(url), CSS url(), and static markup. Full coverage table: references/policy-contract.md.
  • Do not preload a deferred path at boot. One boot-time fetch of any file in a group pulls the whole group before the first frame, and the deferral is lost.
  • Keep the loading art and the first scene’s assets in keep. The splash and the scene’s loading view must not wait on a late group.
  1. pack-report.json emitted[].lazyAssets: policySource names the committed file (or the explicit --lazy-config), and each group has its files, packedBytes and member.
  2. For a Google zip, the archive holds a late-<group>.js member for each declared group, and the zipped index.html is much smaller than the unpacked boot page.
  3. Gate the boot payload on the packed index.html byte size, never on the generator’s kept bytes. The summary counts dist/ file sizes; the packed page a Google first load pays also carries the packer runtime and HTML shell, one VFS manifest entry per packed file, and the whole payload in base64. Every asset stored raw (png, mp3, font — originalLength === length, no deflate) therefore costs 4/3 of its dist/ size. Measured on a 216-entry web build: ~32 KB fixed plus ~137 bytes per manifest entry, so a 200 KB keep across 20 raw-stored files packs to ~276 KB — ~69 KB over the keep figure, ~101 KB over once the fixed part is counted.
  4. Run the packed page. Record first-frame time with device and CPU throttle named, over n runs, or write “unmeasured”. Confirm no late-group error in the console.

A game whose boot fetches everything keeps everything in the boot payload. The generator then exits 4: it writes the file, but nothing is deferrable and the split saves nothing. The fix is in the game: defer its own loads, then regenerate. Packer-side, a group loads on its first touch, so correct output is still produced for such a game; it just defers nothing.

Google’s H5 validator reports “No lazy loading detected.” for a playable without a counted lazy signal. On web and none Google rows the packer defers the Google exit API script, which the validator counts. The counted and uncounted signals, and their measurement, are in references/google-h5-validator.md. Do not claim the validator passes from the packer alone: run the validator on the packed zip.

SymptomLikely causeFix
Pack exits 2 naming a fieldmalformed playable-lazy.jsoncorrect the named field; no fallback exists
Generator exit 1, keep glob ... matches no filea kept asset was renamed or removedregenerate from the trace
Generator exit 3no puppeteer-core or Chromeinstall as the message says, or use --mode static (low confidence)
Generator exit 4the boot fetches every filesection 5
Late group error at runtimea declared group has no payload, or a zip member failed to downloadrebuild; check lazyAssets and the zip members
A late group fetched during boota boot-time read of a deferred pathremove the preload; load on demand
Boot cost unchanged after packingkeep too largeregenerate from a fresh trace
Packed Google index.html bigger than the generator’s kept figure suggestedruntime + shell + manifest + base64 on raw-stored keepssection 4.3; measure the packed page, never the summary

Running the generator and --check, and tabulating the summary rows, is mechanical: t1k-tester (read-only build lane) or the calling agent. Deciding what stays in keep, whether a kept file is a preload artifact, and any change against the trace is judgment: the calling agent, at its own tier. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.

  • A smaller HTML is not a faster first frame by itself. The gain depends on what keep holds back.
  • The generator’s kept-bytes figure undercounts the Google first load. It sums dist/ file sizes, while the packed page also pays the runtime and HTML shell, a manifest entry per packed file, and base64 encoding of the payload (4/3 on any raw-stored asset). Measure the packed index.html (section 4.3), not the summary line.
  • No first-frame gain on a real device has been measured for this split. Say so in the delivery post.
  • The trace runs over the dist/ files, not the packed VFS. Reads the packer cannot guard (CSS, static markup, new Audio(url)) are misses at runtime even when the generator keeps the file.