Skip to content

t1k:cocos:playable:splash-setup

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
Tools—

Keywords: html splash, loader prefab, loading view removal, loadingview, migrate loading screen, pre-engine splash, preloader group, splash setup, splash-setup

/t1k:cocos:playable:splash-setup

Migrates a Cocos playable so the pre-engine HTML splash is the only loading screen. The in-game LoadingView goes, the Preloader dashboard group comes in, the GameView waits on the LoadingTracker contract before it releases the splash, and the legacy SplashProgressBar group is removed.

scripts/splash-setup.cjs does the deterministic work. It reads the template at a pinned ref, so the template is the single source of truth and nothing is copied into this skill. This skill owns the judgment and the editor steps around it.

Reuse check: t1k-cocos-playable-lazyload owns the lazy-load split and the vendored extensions/super-html/. This skill installs the splash pieces only, into tools/splash/ (outside super-html, so a super-html swap cannot delete them). The injector requires two super-html modules, so the skill refuses to run in a project without them. Corpus sweep (mcp__knowledge-retrieval__doc_search, queries “pre-engine splash loader migration” and “LoadingView removal splash”): no splash-setup or loader-migration skill found. Hits were unrelated (H5 BootLoader, a LoadingScreen overlay, the PlayableAdsTemplate GameView field docs). Verdict: reuse-search: not-found-after-corpus-and-grep, scope: 2 corpus queries + grep of the installed skills and modules for “splash”. Recorded verdict: sibling skill, not an extension. Boundary: t1k-cocos-playable-lazyload decides what a game may defer; this skill migrates a project onto the splash.

Section titled “Replacing a stale logo.png (opt-in --logo)”

A project migrated earlier may carry the square app icon as tools/splash/splash/assets/logo.png. The default run keeps it (the file is project-owned, so the default stays non-destructive). To fix it, pass the intended game logo as a PNG:

bun splash-setup.cjs <cocosRoot> --logo <game-logo.png> [--apply]

  • logo.png absent: written from the --logo file instead of the template placeholder.
  • logo.png present and different: replaced, and the run prints [splash-setup] note ... replaced with the --logo file (was N bytes, now M bytes). A dry run prints plan update plus plan note.
  • logo.png present and identical: nothing is planned (idempotent).
  • Not a PNG or not a file: exit 2, nothing written. Convert a webp/jpg wordmark to PNG first.
  • Without --logo nothing changes. The write follows the same uncommitted-changes refusal (exit 3) as every other file.

Verified against PlayableAdsTemplate/CocosPlayableAdsTemplate/tools/splash/ and the Jenkins builder, not recalled.

  • Injector: <cocosRoot>/tools/splash/splash-inject.cjs. CommonJS CLI (.cjs), run locally with bun. The Jenkins step runs the same file under Node.
  • Runtime and art: tools/splash/splash/ holds splash-runtime.js, unflatten.js, and assets/ with four PNGs: logo.png, bar-track.png, bar-fill.png, signature.png. All four are required; a missing one throws.
  • Tests: tools/splash/tests/splash.test.cjs.
  • Dependency: the injector requires ../../extensions/super-html/validate-google.cjs and lazyload.cjs, so super-html must be present. The skill checks this before writing and exits 2 if either is missing.
  • CLI: bun tools/splash/splash-inject.cjs <build/super-html dir or file>... [--config <playable-config.json>] [--assets <dir>] [--params <paramContent.json>] [--hold-ms <n>] [--settled-paths a,b] [--hold-hosts a.com,b.com] [--check].
  • Exit codes: 0 ok. 1 with --check: a deliverable has no block or a STALE one. 2 bad arguments, bad --params, or a load error; nothing is written. In inject mode a single file that fails is logged as left ... untouched and the exit stays 0, so the --check pass is what catches it.
  • Stamp: each injected block carries data-pla-splash-rev="<hash>". A current block is left byte-identical.
  • Who runs it:
    • Local builds: extensions/super-html/lazy-hooks.js (injectSplash) runs it after the pack, unless playable-lazyload.config.json sets "splash": false. It warns when tools/splash/splash-inject.cjs is absent.
    • Jenkins: Step 4, injectPreEngineSplash in GroovyScripts/src/CocosJenkinsBuilder.groovy. It runs the injector under Node, on tools/splash/splash-inject.cjs with build/super-html --config assets/ParameterToolBuild/playable-config.json, then the same arguments with --check, and fails the stage on either non-zero exit. It skips (does not fail) when the injector is absent or "splash": false is set. It passes no --params, --hold-ms, --settled-paths or --hold-hosts, so the baked defaults apply.
    • Status: the Jenkins step is on main of The1Studio/CocosJenkinsScripts. PR and date: references/jenkins-status.md.
  • Old layout is gone: extensions/super-html/splash-inject.cjs no longer exists. A project still on that layout gets no splash from Jenkins, because the step looks only at tools/splash/. Migrate it with this skill.
  • Hold hosts (--hold-hosts). Default app.playablelabs.ai. The black hold (no pinned or live value yet) runs only when a listed host embeds the page, as an ancestor origin or the referrer, matched on host or subdomain. A standalone export or a network export paints the baked defaults at once. --hold-hosts "" never holds.
  • Export bridge. A dashboard export defines window.__PLAYABLE_PARAMETERS__ with flat Preloader.* keys, near the end of the file. The splash treats those values as pinned and paints them once they exist. While the document is still parsing and the bridge is not yet defined, the splash waits, painting nothing, for the bridge, the end of parsing, or 800 ms (BRIDGE_WAIT_MS), whichever comes first. An exporter that places the blob above the splash removes the wait.
  • Source of truth: the project’s CLAUDE.md splash section and tools/splash/splash/splash-runtime.js. If this section and those disagree, they win.

--ref defaults to main, which has the splash since The1Studio/PlayableAdsTemplate#57 merged. A ref that predates it exits 2 and names the fix: pass --ref main, or a commit sha that has the splash. --template-dir <export> reads a local export of the ref instead of GitHub.

ActionTargetKind
Adds the Preloader group (category, size constant, block) derived from the template. The parameter/ folder is matched in any case. With no const UIConfig or AppIcon entry to anchor on, it prints the exact snippet instead and the rest of the plan runsassets/scripts/parameter/config/PlayableConfig.tsautomatic (edit), else manual
With --logo, sets the new group’s Logo Size default from the PNG aspect (width 330, height round(330*h/w), so 548x266 gives 330x160). An existing group with another aspect gets a manual line naming the valuePlayableConfig.tsautomatic (edit), else manual
Adds the matching Preloader entry from the template’s PlayableConfigMeta.ts (a typed Record<keyof typeof PlayableConfig, ...>, so a missing key is a type error). No meta file: skipped. Entry not placeable: manualassets/scripts/parameter/config/PlayableConfigMeta.tsautomatic (edit), else manual
Removes the legacy SplashProgressBar group; refuses if another .ts still reads itPlayableConfig.tsautomatic (edit)
Adds static LOADING_STALL_MS above the first class lineassets/scripts/constant/constant.tsautomatic (edit)
Installs the splash: splash-inject.cjs, splash/splash-runtime.js, splash/unflatten.js, four splash/assets/*.png. logo.png is project-owned: written only when absent, never updated, unless the opt-in --logo <png> is passed (see “Replacing a stale logo.png”)tools/splash/automatic (write/update)
Installs LoadingTracker.ts, LoadingSignals.ts, .tests/LoadingTracker.test.tsassets/scripts/services/loading/automatic (write/update)
Refuses (exit 2, nothing written) when extensions/super-html/validate-google.cjs or lazyload.cjs is missingprojectcheck
Refuses (exit 2, nothing written) when no path.join, path.resolve, require, spawn, exec or fork call in lazy-hooks.js code takes tools/splash/splash-inject.cjs, literally or through a variable holding that path (a comment, a warning string or an unused constant does not count); never edits it (Workflow step 1)extensions/super-html/lazy-hooks.jscheck
Reports (manual) a LAZY_SPLASH_FILES keep-list left by the old layout; never edits itsetup-extensions.js (one level above the Cocos root)manual
Ports the GameView hand-off: interface, fields, onLoad subscriptions, startLoading, onParametersReady, onLoadingProgress, finishLoading, htmlSplash, onDestroy; removes the loadingView property, its orphan tooltip decorator, and the LoadingView importassets/scripts/UI/GameView.tsautomatic (edit)
Deletes LoadingView .ts, .ts.meta, .prefab, .prefab.meta, after the edits above succeedassets/scripts/UI/, assets/resources/prefab/UI/automatic (delete)
Lists every .ts under assets/ that still names LoadingView in code (a string such as getChildByPath('UICanvas/LoadingView') counts, a comment does not), as file:line manual lines; never edits themassets/**/*.tsmanual
Scene node removal, ParameterController refresh wiring, logo sprite, editor savelisted as manualmanual

The script never edits ParameterToolBuild/*.json and never edits .scene/.prefab JSON. Those go through the editor MCP.

Every new file text is computed in memory before the first write. An ambiguous anchor, an unknown GameView shape, an onDestroy with a statement the port does not know, or a CTA listener the ported onDestroy would not remove, throws (exit 2) and writes nothing.

  • Every change prints [splash-setup] <action> <path>. A dry run prefixes the action with plan.
  • Every open step prints [splash-setup] manual <step>, then a final [splash-setup] manual-pending: N.
  • 0: no automatic change remains. Manual steps, if any, are listed and counted.
  • 1: a dry run with automatic work pending. With --strict, also manual-pending > 0.
  • 2: usage or validation error. Nothing was written.
  • 3: refused: not a Cocos playable, or, with --apply, uncommitted changes in a file it would touch (checked in the repo that owns each file). Exit 2 also when a file belongs to no git repo.
  • 4: --apply wrote its changes, but either the on-disk layout check or a re-plan still finds work. The layout check names any missing file among tools/splash/splash-inject.cjs, splash-runtime.js, unflatten.js and the four PNGs. The tree is partly migrated; the written paths are printed. Re-run the dry run.
  • One location. The splash installs to tools/splash/ only. Never copy it back under extensions/super-html/: the Jenkins step and the local lazy-hooks.js read tools/splash/, so a copy there is dead weight that drifts.
  • No fallback. A ref without the splash exits 2 and names the fix. The script never substitutes another ref.
  • Unknown code is never dropped. An onDestroy with a statement the port does not know exits 2, because dropping it would be silent. A GameView edited heavily by hand also exits 2: port it by hand from the reference, then re-run.
  • The CTA listener stays removed. The port keeps the legacy TOUCH_END or cc.Button CLICK removal in the new onDestroy. A ctaButton listener with no matching off there exits 2: add the off, then re-run.
  • Legacy group removal is guarded. SplashProgressBar is removed only when no .ts reads it in code (comment mentions do not count). Port that reader to Preloader first, then re-run.
  1. Detect. Confirm assets/scripts/parameter/config/PlayableConfig.ts exists under the Cocos root (any folder case), and that extensions/super-html/validate-google.cjs and lazyload.cjs exist (the injector needs them; they ship from super-html 5.4.0, and a 5.2.4 copy has neither: the script exits 2 naming the version and the missing files). Copy extensions/super-html from The1Studio/PlayableAdsTemplate (CocosPlayableAdsTemplate/extensions/super-html) or a sibling branch of the project that already has 5.4.0, keeping the project’s own lazy-hooks.js wiring. Note the GameView shape the dry run reports. If extensions/super-html/lazy-hooks.js still runs the old injector path, rewire it before the first dry run: the script never edits that file, and on the old wiring the dry run exits 2 with no plan. Point the injector path in injectSplash at:
    const inject = path.join(__dirname, '..', '..', 'tools', 'splash', 'splash-inject.cjs');
    A file with no splash call takes injectSplash from the reference lazy-hooks.js at the ref.
  2. Dry run. No flags except --ref (or --template-dir):
    bun .claude/skills/t1k-cocos-playable-splash-setup/scripts/splash-setup.cjs <cocosRoot> --ref <ref>
    Exit 1 means automatic work is pending. Exit 2 or 3 means stop and fix the cause first.
  3. Show the plan and gate it. If more than 10 paths change, or the plan deletes files, call AskUserQuestion before applying. List every deleted path. A deletion is the point of the migration, but the user confirms it.
  4. Apply. Commit or move aside any dirty file the plan names (exit 3 otherwise), then:
    bun .claude/skills/t1k-cocos-playable-splash-setup/scripts/splash-setup.cjs <cocosRoot> --ref <ref> --apply
    A second dry run must exit 0 with the same manual list. Re-running --apply is a byte-identical no-op. Exit 4 means the writes happened and the tree is partly migrated: re-run the dry run before anything else.
  5. Manual steps. Work through each manual line from the output:
    • Preloader snippet. If the line is printed, the config has no UIConfig or AppIcon anchor: paste each part where its comment says, then re-run the dry run. Until then the project does not have PlayableConfig.Preloader.
    • LoadingView scene node. Remove the node via manage_node in every scene that names LoadingView, and check that no prefab still does. The script has already deleted the LoadingView files, so until the node is gone the editor shows a missing prefab. Do this before opening the project in the editor.
    • ParameterController refresh. If the line is printed, wire PlayableConfig.Preloader.onUpdate to call __plaSplash.refresh(), as the reference ParameterController.ts does.
    • Logo image. In the editor, set the Preloader group’s “Logo Image” (Preloader.logo.spriteFrame) to the game logo: the wide title wordmark (for example a 548x266 game-logo.webp). Do not reuse the image the former LoadingView prefab showed: that can be the square app icon, often named Logo.png. The splash box is Preloader.logo.contentSize, so match it to the image’s aspect. Leave the image empty to keep the embedded splash logo (tools/splash/splash/assets/logo.png). By default this skill never replaces that file once it exists; if it is still the app icon, re-run with --logo <game-logo.png> (below) or swap it by hand.
    • Save the scene. Editor step reality: the Preloader group reaches ParameterToolBuild/playable-config.json only when ConfigWatcher runs in a visible, ticking editor. manage_asset refresh does not trigger it. Without it Jenkins bakes the 200x200 runtime fallback. Verify and fall back as in t1k-cocos-playable-editor-tools skills/t1k-cocos-playable-editor-tools/references/configwatcher.md.
    • LoadingView code references. Each file:line manual line is code that looked LoadingView up and now dangles.
  6. Build and verify. Build, then:
    bun tools/splash/splash-inject.cjs <buildDir> --check
    Exit 0 with no STALE means the splash is in the deliverable. Grep the Jenkins log for [splash] pre-engine splash injected.
  7. Strict gate. Re-run with --strict in CI. It exits 1 while any manual step is still open.

Running the dry run, the --check verify, and the test suite, then tabulating their output, is fixed-command work with a known result, so a cheap tier runs it. Deciding to apply, gating the deletions, and the editor steps change the project and need the user, so they stay with the main session. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run the dry run (Workflow step 2) and the step 6 --check; tabulate the [splash-setup] linest1k-metrics-reporter
Run tests/splash-setup.test.cjs through scripts/run-skill-tests.cjs and report the pass/fail countst1k-tester
Decide to apply, gate the plan with AskUserQuestion, run --applymain session (write, needs the user)
Commit dirty files the plan names, before --applymain session (git ops route through t1k-git-manager)
Manual steps: LoadingView scene node removal, ParameterController wiring, logo sprite, editor savemain session (editor MCP, per-scene judgment)

Cosmetic lessons (the legacy editor-flag comment left in GameView, import placement after the last import) live in ledger/gotchas/t1k-cocos-playable-splash-setup.md, not in this body.

  • Lazy-load policy: t1k-cocos-playable-lazyload.
  • Scene and prefab JSON edits: t1k-cocos-playable-editor-tools and t1k-cocos-base-editor-mcp-truth.