t1k:cocos:playable:lazyload
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: boot payload, defer assets, deferred audio, first load budget, google lazy loading, late payload, lazy load, lazy loading, lazyload, playable split, super-html, two-phase load
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:lazyloadCocos Playable Lazy-Load Determination
Section titled “Cocos Playable Lazy-Load Determination”Decide what a given playable may defer past its first view, then express that as a
per-game lazy-load policy. Does NOT cover how many bytes ship at all (use
t1k-cocos-playable-build-size — engine module pruning, texture compression,
size budgets); this skill governs when they arrive.
The split mechanism, where a project has one, is mechanical. What is never mechanical — and what this skill exists for — is the determination: which assets a given game genuinely requests only after the player touches it. Get that wrong and the tooling reports a clean split that saves nothing, because a correctly-built runtime gate quietly pulls the assets back during scene load.
Executed by
Section titled “Executed by”Inventory and measurement are mechanical: run the toolchain, read its table back
verbatim. Route a built-package run to t1k-gamedev-playable-runtime-verifier. The
determination itself (Phase 3) and the policy authoring (Phase 4) are judgment
over the game’s source — t1k-cocos-base-developer, or inline.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “Set up the runtime seam” / “audio defers nothing” | references/setup.md |
| “What can this build lazy-load?” | Workflow — all phases |
| “Tune an existing policy” | Phase 2 → 3 → 5 |
| “Jenkins still ships one html” | references/jenkins-split-contract.md — prove Step 3 ran |
| “The deferral saved nothing” | references/verification.md § Paper deferral |
| “An asset broke after deferring it” | Hard rules — a reader that did not wait for its group |
| “Get under the network’s first-load cap” | Splitting alone rarely does it — t1k-cocos-playable-build-size first |
| “No lazyload-policy.json in this project” | Toolchain — add <cocos project>/lazyload-policy.json (schema: references/lazyload-policy-schema.md); the pipeline owns the splitter |
Toolchain — the Jenkins split contract
Section titled “Toolchain — the Jenkins split contract”What ships is what Jenkins builds, and Jenkins splits in exactly one place:
CocosJenkinsScripts Step 3. The pipeline owns the Google splitter
(GroovyScripts/resources/google-split/, materialized per build and run as
bun split-google.cjs --project <cocos project>) after a stock super-html
pack. A project ships only <cocos project>/lazyload-policy.json; a project’s
own build-tools/google-split/ is ignored. Contract, invocation, output rules
and the log lines that prove a split:
references/jenkins-split-contract.md.
ls <cocos project>/lazyload-policy.json 2>/dev/null- No
lazyload-policy.json→ Jenkins logsNo lazyload-policy.json in <project> - Google zip left as SuperHtml built itand ships the google zip single-file, whatever else the project has. Add the policy (Phase 4) before Phases 2-5; do not copy or write a splitter. - The policy is
lazyload-policy.jsonin the Cocos project folder, read by the pipeline splitter; its schema (rules[],match, paper deferral, the build-failing errors) isreferences/lazyload-policy-schema.md. Keep exactly one policy file; a second file nothing in the Jenkins path reads is inert. - The wrapped super-html editor extension never runs in Jenkins (Step 2 re-packs with its own stock clone), so its
playable-lazyload.config.jsonis an editor-only convenience, never evidence that a shipped build splits:references/editor-extension-note.md.
Never assume a splitter flag: read its own usage header. The four tests and the per-class table are judgment in references/determination-rubric.md; the splitter only executes them. Each bundle’s config.json paths map turns uuid payload entries back into asset terms.
Workflow
Section titled “Workflow”Phase 0 — runtime seam
Section titled “Phase 0 — runtime seam”A project with no game-side seam saves nothing however good the policy is.
Install and wire the lazy-load package, remove boot-time demands for deferred
assets, and confirm the build-side prerequisite (a split plus a runtime gate):
references/setup.md.
Phase 1 — get a real payload
Section titled “Phase 1 — get a real payload”The determination cannot be made from source alone: only the build knows which bundle Cocos actually put each asset in, and a policy is written in bundle/type terms. Build the target channel, then work against its packed deliverable.
No build → stop and ask for one. Rules authored against guessed asset paths match nothing, and a rule that matches nothing is inert.
Phase 2 — inventory the payload
Section titled “Phase 2 — inventory the payload”Run the splitter’s inventory (or read the bundle manifests) against the built deliverable, passing the policy
currently in force. What you need out of it, per (bundle, type): gz weight,
key count, the current boot/late state, and an eligibility verdict — the
fact a size report cannot give you:
Verdicts: eligible (candidate), soft (candidate; a raw archive glob will not reach it), paper (scene bundle, pulled back by the walk), locked (engine or bootstrap, never defer). The action per verdict: references/inventory-verdicts.md.
Weight-ordered candidates are candidates, not answers: a tool knows weight and eligibility, never when the game asks for the asset. That is Phase 3.
Phase 3 — decide, from the game’s source
Section titled “Phase 3 — decide, from the game’s source”Confirm each candidate is genuinely requested after the first view. Full
procedure, per-asset-class verdict table, and the greps that produce the
evidence: references/determination-rubric.md.
The four tests, in short — an asset is deferrable only if all hold:
-
Outside the scene dependency walk — Cocos resolves the scene’s whole dependency graph before
LoadSceneresolves, so anything the scene reaches is fetched before the first frame. -
Loaded by an explicit runtime call —
resources.load,assetManager.loadBundle/loadAny, an audio or font service request. No call site means the scene walk is what fetches it. -
That call site runs after the first view — after first interaction, a win/lose view entry, or a later level; not during the loading view.
-
Not first-paint critical — loading-screen art, progress bars and fonts stay in boot. A deferred font paints the first frame with no text, which is the very view the policy exists to protect.
-
No edge case — the first use is late by construction (an outcome, a gesture), not by the current level layout. Content a redesign or a dashboard parameter could bring into frame one (level-placed enemies, gates, a boss) is a keep, however late it shows up today.
Judge every heavy asset class, not just audio, and give a shared asset the earliest use of any of its users. Procedure: references/determination-trace.md.
Record a one-line verdict per candidate before writing any rule. A rule with no recorded reason is what this skill exists to prevent.
Phase 4 — author the policy
Section titled “Phase 4 — author the policy”Write it as <cocos project>/lazyload-policy.json, the file the pipeline splitter
reads (Step 3), never a second policy file: references/jenkins-split-contract.md.
Schema: references/lazyload-policy-schema.md.
Policy lives with the game, not with the tooling — what is deferrable differs per game (audio in one, level data and meshes in the next). Express each rule in asset terms (Cocos type, asset path within its bundle, bundle name), because the payload itself addresses everything by uuid and nobody can author against that. A raw archive glob is the escape hatch for non-asset files only. Conditions within one rule are ANDed.
Groups are the load-bearing design decision, not a label. A group is one trigger moment: a demand-miss on any member pulls the whole group. Never merge a class that is demand-missed during scene load with one that is not; audio starts on the first frame (or the first touch, if earlier) and never later. Deferring an asset defers all of its parts. Full group rules: references/policy-groups.md.
Phase 5 — verify, and do not trust a green
Section titled “Phase 5 — verify, and do not trust a green”Read the build’s own report for rules that matched nothing and keys a keep
rule vetoed, then measure. A policy that classifies cleanly and saves
nothing looks identical to one that works. The five checks that distinguish
them: references/verification.md.
Hard rules
Section titled “Hard rules”- A policy nothing in the Jenkins path reads looks identical to one that
works — until the shipped zip is one html. Only CocosJenkinsScripts Step 3
splits, via the pipeline-owned splitter reading
lazyload-policy.json; an editor-extension config (playable-lazyload.config.json), a project-localbuild-tools/google-split/or any file the splitter does not read is inert. Prove it from the Jenkins log (google-split: replaced …). - The gate only helps a reader that asks it to wait.
__lazyLoadNowmoves a group’s chunks into the page; it does not makeresources.loadblock. A caller that loads a deferred path without first awaiting__lazyWhenReady(group)goes to super-html’sgetRes()before the chunk landed, getsundefined, and the engine downloader throws on it — see the next entry. Reading the state back (__lazyState()) is not waiting either. So a wrong rule is not merely slow: any reader the skill does not own can turn it into a broken asset, which is why Phase 5’s measurement is mandatory and not optional. - A deferred
resources.loadwith no gate wait fails asTypeError … reading 'substring'(#1581). The splitter takes the clip’s native file out of the payload zip and out ofwindow.__res; nothing re-inserts it until__lazyWhenReady(group)resolves. Until thengetRes('audio/<clip>')answersundefinedand the audio downloader reads a property off it, so every deferred clip logsFailed to load clip …and no deferred SFX ever plays — a clean group table, a successful build, and silence. A project-local loader that mirrors@playablelabs/cc-lazy-loadmust copy the waiting half too (that package’sensureLoadedwarms the gate itself, which is whysetup.md(references/setup.md) recommends it over a hand-rolled one). - Why the gate is not optional. super-html’s
getRes()memoises whatever it finds — includingundefined— and deletes the key as it reads. One early miss is therefore permanent: the asset stays broken even after the late payload lands. A split shipped without a gate is not a lazy-load, it is a latent asset-loss bug. deferon a<script>tag is not lazy loading. The browser still fetches every deferred script while parsing the document —deferdelays execution, not download. Only holding chunks out of the document and injecting them later moves bytes. Google’s lazy-loading scan is a static source check: it passes only when it sees a<script defer|async src>tag in the HTML, and reports “No lazy loading detected” for scripts injected viacreateElement. So emit the boot chunks as staticdefertags (needed to pass), keep the deferred chunks gate-injected (needed to actually defer), and never treat passing the scan as evidence that anything was deferred. The pipeline splitter’s static-defer guard now fails the build on a violation (jenkins-split-contract.md(references/jenkins-split-contract.md)).- A group releases only when the whole group has landed. Per-clip registration cannot beat that. A cue the first tap needs (a tiny drag SFX) belongs in boot via a keep rule, or a fast first tap drops it.
- Register clips one by one as they land, never all-or-nothing after the directory. An SFX fired before its clip lands waits for it for a bounded window instead of being dropped; a silent first tap is a bug.
- A keep rule matches by asset (bundle/path/type), like a defer rule. One written as an archive glob silently no-ops on uuid-addressed keys. Check the build report lists the kept keys and flags a keep rule that matched nothing.
- Measure the audio delay, not just bytes: tap to BGM, tap to first SFX,
dropped cues (
verification.md(references/verification.md) Check 5). - Engine code is never deferrable. The engine and its asm side-modules
(bullet, spine, meshopt) are pulled by the engine’s own init, before any touch
is possible. Deferring them does not push work past the first view — it stalls
init so the first view never arrives. The lever for them is engine module
pruning (
t1k-cocos-playable-build-size), not a load policy. - Scene-bundle art cannot be deferred where it sits. It is in the scene dependency walk by construction. Moving it into a loaded-on-demand bundle is a project change that must land first; until it does, a rule naming it is deferral on paper only.
- A build hook that wraps a third-party packer is reinstalled, not patched once. Where a project wires the split into the packer’s own build hook, reinstalling or updating that extension wipes the wiring, and builds revert to untransformed output with no error. Re-run that project’s setup after any packer update, and treat silence as unverified.
- Channels differ structurally. Some ship a sibling config the transform may not carry over; some keep the payload in a separate file rather than inline. Treat the channel list as an explicit allow-list, opted into once each is supported and tested — never a wildcard.
Related
Section titled “Related”t1k-cocos-playable-build-size— how many bytes ship at all. Under a tight first-load cap you need both, and pruning is usually the larger lever.t1k-cocos-playable-asset-management— theresources.loadcall sites Phase 3 reads.t1k-gamedev-playable-preview-verify— headless runtime verification of a built package.t1k-cocos-playable-gen— build/packaging pipeline context.