Skip to content

t1k:cocos:playable:lazyload

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
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

/t1k:cocos:playable:lazyload

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.

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.

IntentPath
“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

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.

Terminal window
ls <cocos project>/lazyload-policy.json 2>/dev/null
  • No lazyload-policy.json → Jenkins logs No lazyload-policy.json in <project> - Google zip left as SuperHtml built it and 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.json in the Cocos project folder, read by the pipeline splitter; its schema (rules[], match, paper deferral, the build-failing errors) is references/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.json is 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.

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.

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.

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:

  1. Outside the scene dependency walk — Cocos resolves the scene’s whole dependency graph before LoadScene resolves, so anything the scene reaches is fetched before the first frame.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

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.

  • 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-local build-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. __lazyLoadNow moves a group’s chunks into the page; it does not make resources.load block. A caller that loads a deferred path without first awaiting __lazyWhenReady(group) goes to super-html’s getRes() before the chunk landed, gets undefined, 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.load with no gate wait fails as TypeError … reading 'substring' (#1581). The splitter takes the clip’s native file out of the payload zip and out of window.__res; nothing re-inserts it until __lazyWhenReady(group) resolves. Until then getRes('audio/<clip>') answers undefined and the audio downloader reads a property off it, so every deferred clip logs Failed 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-load must copy the waiting half too (that package’s ensureLoaded warms the gate itself, which is why setup.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 — including undefined — 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.
  • defer on a <script> tag is not lazy loading. The browser still fetches every deferred script while parsing the document — defer delays 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 via createElement. So emit the boot chunks as static defer tags (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.
  • 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 — the resources.load call sites Phase 3 reads.
  • t1k-gamedev-playable-preview-verify — headless runtime verification of a built package.
  • t1k-cocos-playable-gen — build/packaging pipeline context.