t1k:cocos:playable:splash-setup
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: html splash, loader prefab, loading view removal, loadingview, migrate loading screen, pre-engine splash, preloader group, splash setup, splash-setup
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:splash-setupCocos Playable: Splash Setup
Section titled “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.
Replacing a stale logo.png (opt-in --logo)
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
--logofile 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 printsplan updateplusplan 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
--logonothing changes. The write follows the same uncommitted-changes refusal (exit 3) as every other file.
Build script location and format
Section titled “Build script location and format”Verified against PlayableAdsTemplate/CocosPlayableAdsTemplate/tools/splash/ and the Jenkins builder, not recalled.
- Injector:
<cocosRoot>/tools/splash/splash-inject.cjs. CommonJS CLI (.cjs), run locally withbun. The Jenkins step runs the same file under Node. - Runtime and art:
tools/splash/splash/holdssplash-runtime.js,unflatten.js, andassets/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.cjsandlazyload.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:
0ok.1with--check: a deliverable has no block or a STALE one.2bad arguments, bad--params, or a load error; nothing is written. In inject mode a single file that fails is logged asleft ... untouchedand the exit stays0, so the--checkpass 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, unlessplayable-lazyload.config.jsonsets"splash": false. It warns whentools/splash/splash-inject.cjsis absent. - Jenkins: Step 4,
injectPreEngineSplashinGroovyScripts/src/CocosJenkinsBuilder.groovy. It runs the injector under Node, ontools/splash/splash-inject.cjswithbuild/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": falseis set. It passes no--params,--hold-ms,--settled-pathsor--hold-hosts, so the baked defaults apply. - Status: the Jenkins step is on
mainofThe1Studio/CocosJenkinsScripts. PR and date:references/jenkins-status.md.
- Local builds:
- Old layout is gone:
extensions/super-html/splash-inject.cjsno longer exists. A project still on that layout gets no splash from Jenkins, because the step looks only attools/splash/. Migrate it with this skill.
Splash behaviour to know
Section titled “Splash behaviour to know”- Hold hosts (
--hold-hosts). Defaultapp.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 flatPreloader.*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.mdsplash section andtools/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.
What the script does
Section titled “What the script does”| Action | Target | Kind |
|---|---|---|
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 runs | assets/scripts/parameter/config/PlayableConfig.ts | automatic (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 value | PlayableConfig.ts | automatic (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: manual | assets/scripts/parameter/config/PlayableConfigMeta.ts | automatic (edit), else manual |
Removes the legacy SplashProgressBar group; refuses if another .ts still reads it | PlayableConfig.ts | automatic (edit) |
Adds static LOADING_STALL_MS above the first class line | assets/scripts/constant/constant.ts | automatic (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.ts | assets/scripts/services/loading/ | automatic (write/update) |
Refuses (exit 2, nothing written) when extensions/super-html/validate-google.cjs or lazyload.cjs is missing | project | check |
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.js | check |
Reports (manual) a LAZY_SPLASH_FILES keep-list left by the old layout; never edits it | setup-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 import | assets/scripts/UI/GameView.ts | automatic (edit) |
Deletes LoadingView .ts, .ts.meta, .prefab, .prefab.meta, after the edits above succeed | assets/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 them | assets/**/*.ts | manual |
Scene node removal, ParameterController refresh wiring, logo sprite, editor save | listed as manual | manual |
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.
Exit codes and output
Section titled “Exit codes and output”- Every change prints
[splash-setup] <action> <path>. A dry run prefixes the action withplan. - 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, alsomanual-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:--applywrote its changes, but either the on-disk layout check or a re-plan still finds work. The layout check names any missing file amongtools/splash/splash-inject.cjs,splash-runtime.js,unflatten.jsand the four PNGs. The tree is partly migrated; the written paths are printed. Re-run the dry run.
Hard rules
Section titled “Hard rules”- One location. The splash installs to
tools/splash/only. Never copy it back underextensions/super-html/: the Jenkins step and the locallazy-hooks.jsreadtools/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
onDestroywith 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_ENDorcc.ButtonCLICK removal in the newonDestroy. ActaButtonlistener with no matchingoffthere exits 2: add theoff, then re-run. - Legacy group removal is guarded.
SplashProgressBaris removed only when no.tsreads it in code (comment mentions do not count). Port that reader toPreloaderfirst, then re-run.
Workflow
Section titled “Workflow”- Detect. Confirm
assets/scripts/parameter/config/PlayableConfig.tsexists under the Cocos root (any folder case), and thatextensions/super-html/validate-google.cjsandlazyload.cjsexist (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). Copyextensions/super-htmlfromThe1Studio/PlayableAdsTemplate(CocosPlayableAdsTemplate/extensions/super-html) or a sibling branch of the project that already has 5.4.0, keeping the project’s ownlazy-hooks.jswiring. Note the GameView shape the dry run reports. Ifextensions/super-html/lazy-hooks.jsstill 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 ininjectSplashat:A file with no splash call takesconst inject = path.join(__dirname, '..', '..', 'tools', 'splash', 'splash-inject.cjs');injectSplashfrom the referencelazy-hooks.jsat the ref. - Dry run. No flags except
--ref(or--template-dir):Exit 1 means automatic work is pending. Exit 2 or 3 means stop and fix the cause first.bun .claude/skills/t1k-cocos-playable-splash-setup/scripts/splash-setup.cjs <cocosRoot> --ref <ref> - Show the plan and gate it. If more than 10 paths change, or the plan deletes files, call
AskUserQuestionbefore applying. List every deleted path. A deletion is the point of the migration, but the user confirms it. - Apply. Commit or move aside any dirty file the plan names (exit 3 otherwise), then:
A second dry run must exit 0 with the same manual list. Re-runningbun .claude/skills/t1k-cocos-playable-splash-setup/scripts/splash-setup.cjs <cocosRoot> --ref <ref> --apply
--applyis 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. - Manual steps. Work through each
manualline from the output:- Preloader snippet. If the line is printed, the config has no
UIConfigorAppIconanchor: paste each part where its comment says, then re-run the dry run. Until then the project does not havePlayableConfig.Preloader. - LoadingView scene node. Remove the node via
manage_nodein every scene that namesLoadingView, 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.onUpdateto call__plaSplash.refresh(), as the referenceParameterController.tsdoes. - 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 548x266game-logo.webp). Do not reuse the image the former LoadingView prefab showed: that can be the square app icon, often namedLogo.png. The splash box isPreloader.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
Preloadergroup reachesParameterToolBuild/playable-config.jsononly when ConfigWatcher runs in a visible, ticking editor.manage_asset refreshdoes not trigger it. Without it Jenkins bakes the 200x200 runtime fallback. Verify and fall back as int1k-cocos-playable-editor-toolsskills/t1k-cocos-playable-editor-tools/references/configwatcher.md. - LoadingView code references. Each
file:linemanual line is code that looked LoadingView up and now dangles.
- Preloader snippet. If the line is printed, the config has no
- Build and verify. Build, then:
Exit 0 with nobun tools/splash/splash-inject.cjs <buildDir> --check
STALEmeans the splash is in the deliverable. Grep the Jenkins log for[splash] pre-engine splash injected. - Strict gate. Re-run with
--strictin CI. It exits 1 while any manual step is still open.
Executed by
Section titled “Executed by”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”.
| Step | Agent |
|---|---|
Run the dry run (Workflow step 2) and the step 6 --check; tabulate the [splash-setup] lines | t1k-metrics-reporter |
Run tests/splash-setup.test.cjs through scripts/run-skill-tests.cjs and report the pass/fail counts | t1k-tester |
Decide to apply, gate the plan with AskUserQuestion, run --apply | main session (write, needs the user) |
Commit dirty files the plan names, before --apply | main session (git ops route through t1k-git-manager) |
| Manual steps: LoadingView scene node removal, ParameterController wiring, logo sprite, editor save | main 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.
Not covered here
Section titled “Not covered here”- Lazy-load policy:
t1k-cocos-playable-lazyload. - Scene and prefab JSON edits:
t1k-cocos-playable-editor-toolsandt1k-cocos-base-editor-mcp-truth.