t1k:playablelabs:web:lazy-load
| Field | Value |
|---|---|
| Module | web |
| Version | 1.18.2 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/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-assetsflag row and--lazy-config:t1k-playablelabs-base-pack. - Jenkins
PARAM_LAZY_ASSETSand 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.
State your host first
Section titled “State your host first”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.
1. Generate the policy before packing
Section titled “1. Generate the policy before packing”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):
bun <skill-dir>/scripts/gen-playable-lazy.cjs --build distThe 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:
- Read the printed summary: kept and deferred counts and bytes, and the top kept files with why.
- 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.
- Commit the file it writes (
public/playable-lazy.jsonwhenpublic/exists). - 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.
2. The contract the packer reads
Section titled “2. The contract the packer reads”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 }| Field | Meaning |
|---|---|
keep | paths or globs held in the boot payload. Never .js, .mjs, .css, .wasm or .html (never deferred anyway) |
deferRest | group for every file that no keep glob, no defer rule and no never-deferred type holds |
defer | extra {group, glob} rules. The built-in audio rules stay unless onlyDefer is true |
onlyDefer | true replaces the built-in audio rules instead of extending them |
idlePrefetchMs | ms 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.
3. Game obligations
Section titled “3. Game obligations”keepis 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,.srcon Image, Audio, Video, Script or Source, orsetAttribute('src'). These wait for the group. Anything else is a miss:new Audio(url), CSSurl(), 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.
4. Verify
Section titled “4. Verify”pack-report.jsonemitted[].lazyAssets:policySourcenames the committed file (or the explicit--lazy-config), and each group has itsfiles,packedBytesandmember.- For a Google zip, the archive holds a
late-<group>.jsmember for each declared group, and the zippedindex.htmlis much smaller than the unpacked boot page. - Gate the boot payload on the packed
index.htmlbyte size, never on the generator’s kept bytes. The summary countsdist/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 storedraw(png, mp3, font —originalLength === length, no deflate) therefore costs 4/3 of itsdist/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. - 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.
5. The honest limit
Section titled “5. The honest limit”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.
6. Google H5 validator
Section titled “6. Google H5 validator”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.
Failure table
Section titled “Failure table”| Symptom | Likely cause | Fix |
|---|---|---|
| Pack exits 2 naming a field | malformed playable-lazy.json | correct the named field; no fallback exists |
Generator exit 1, keep glob ... matches no file | a kept asset was renamed or removed | regenerate from the trace |
| Generator exit 3 | no puppeteer-core or Chrome | install as the message says, or use --mode static (low confidence) |
| Generator exit 4 | the boot fetches every file | section 5 |
| Late group error at runtime | a declared group has no payload, or a zip member failed to download | rebuild; check lazyAssets and the zip members |
| A late group fetched during boot | a boot-time read of a deferred path | remove the preload; load on demand |
| Boot cost unchanged after packing | keep too large | regenerate from a fresh trace |
Packed Google index.html bigger than the generator’s kept figure suggested | runtime + shell + manifest + base64 on raw-stored keeps | section 4.3; measure the packed page, never the summary |
Executed by
Section titled “Executed by”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”.
Hard rules
Section titled “Hard rules”- A smaller HTML is not a faster first frame by itself. The gain depends on what
keepholds 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 packedindex.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.