t1k:cocos:playable:submodule-to-package
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: game-foundation, package, parameter-tool, submodule, vendored
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:submodule-to-package[--verify-only]Submodule → @playablelabs Package Migration
Section titled “Submodule → @playablelabs Package Migration”Convert a Cocos 3.8.7 playable from the PLAGameFoundation / PlayableParamterTool git submodules to the vendored @playablelabs/game-foundation and @playablelabs/parameter-tool packages under assets/packages/.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| Full migration (submodules still present) | Run Migration steps 1→7 |
| Packages already vendored, just check for bugs | --verify-only → Step 7 only |
A toast/tutorial/layout call throws ReferenceError: X is not defined | Step 7 — Verify → run the verifier, patch the flagged file |
Why this is not a find-and-replace
Section titled “Why this is not a find-and-replace”The .ts / .core.ts / .core.impl.ts triplet in each vendored package is generated at publish time by the cocos-package-manager editor extension (split + obfuscate) — it is NOT how the source repo looks (upstream is a single monolithic .ts). That obfuscator has a defect (Gotcha 1) and several call-site APIs changed between the submodule and the package (Step 4). Both must be handled or the game silently fails to start / throws at runtime.
Migration steps
Section titled “Migration steps”Step 1 — Remove the submodules
Section titled “Step 1 — Remove the submodules”Drop both [submodule …] blocks from .gitmodules (keep ConfigPath, optimize-size), then git rm --cached the two submodule paths (assets/PLAGameFoundation, assets/PlayableParamterTool). Remove their VCS root mappings from .idea/vcs.xml if present.
Step 2 — Vendor the packages
Section titled “Step 2 — Vendor the packages”Install both from the CPM registry via install-package.cjs/the cocos-package-manager extension — never copy the package source by hand (SSOT: shared-cpm-facts.md § “Consumption is CPM-registry-only”; auth-failure procedure: vendor-fallback.md). This lands the published packages under assets/packages/@playablelabs/game-foundation/ and .../parameter-tool/ (with their .meta files), carrying the generated .core.impl.ts split form.
Step 3 — Register playableSync
Section titled “Step 3 — Register playableSync”In <project>/package.json, playableSync[] must list exactly the packages the project vendors under assets/packages/@playablelabs/ — no more, no fewer. This migration introduces two, so after Steps 1–2 the entry reads:
"playableSync": ["@playablelabs/parameter-tool", "@playablelabs/game-foundation"]A project that already vendored another package before the migration (e.g. @playablelabs/warning) keeps it in the list; one that does not vendor it must NOT add it — a registered-but-not-vendored package makes the cocos-package-manager extension try to sync in a package that was never installed.
Step 4 — Repoint imports + apply API changes
Section titled “Step 4 — Repoint imports + apply API changes”Rewrite every import resolving into the removed submodule directories — both db:// specifiers (db://assets/PLAGameFoundation/… → db://assets/packages/@playablelabs/game-foundation/…, db://assets/PlayableParamterTool/… → db://assets/packages/@playablelabs/parameter-tool/…) and any relative import (../PLAGameFoundation/…, ../../../PlayableParamterTool/…, etc.). A db://-only grep sweep reports false-clean: relative imports into the deleted directories do not get caught, the file compiles fine in isolation, and the Cocos editor reports the attached script as “missing or invalid” with no further detail. Then apply the known signature changes — these are not path-only:
| Call site | Change |
|---|---|
ParameterUtils | ParameterReplacedAssetsHandler moved to assetParameterUtils/ |
PlayableConfig TableParameter | now takes category after minItems/maxItems |
VirtualJoystick TouchEndSignal | now requires (worldPosition, uiPosition) |
ParameterController | getTextureFromBase64 now resolves null (was: never resolves). Guard the null — an unguarded null yields a textureless SpriteFrame that throws in SpriteFrame.getHash |
ParameterManager | parameter-tool is now standalone and no longer imports game-foundation. You MUST register every runtime seam — see Step 4a below. Without them it no-ops silently, ParametersReadySignal never reaches the bus, and the game flow never starts |
NodeComposites / PLAComposites (and their per-type wrapper classes — SpriteParameter, LabelParameter, ButtonParameter, CameraParameter, RedirectParameter, TutorialHandParameter, RichTextParameter, EndCardParameter, LoadingScreenParameter, ProgressBarParameter) | REMOVED, no replacement export. The package’s own migration docs (plans/ under the vendored parameter-tool package) record this as a DELETE, not a rename. A consumer still importing these from the old submodule path must migrate to the component-parameter model documented there before the import can even be repointed |
PlayableConfigProvider.initialize | now takes three required args (config, meta, currentSdk) — was two: (config, currentSdk). Passing the old two-arg call silently shifts currentSdk into the meta slot with no compile error and no runtime error (.core.impl.ts is @ts-nocheck), corrupting PlayableConfigProvider.currentSdk. The call itself is mandatory and independent of the Step 4a seam registrars: a host ParameterManager that registers the seams but never calls it builds and runs clean, PlayableConfigProvider._config stays {} and every parameter silently no-ops (the host SDK only logs Parameter config not found for key: ...) |
Step 4a — Register the ParameterToolRuntime seams
Section titled “Step 4a — Register the ParameterToolRuntime seams”There is no combined ParameterToolRuntime.register(...) method. The runtime exposes a set of
independent registrars, one per seam, each taking an interface implementation. This count is
NOT stable across package releases — it has moved 3 -> 5 -> 6 across three verified releases of
@playablelabs/parameter-tool (v1.0.x). Do not treat any fixed list (including the one below) as
exhaustive. assets/packages/@playablelabs/parameter-tool/ParameterToolRuntime.core.types.ts on
the target project is the only source of truth — read every register* static off that live file
and call each one during boot, rather than trusting a number written in this skill.
As of package 1.0.13, the live declarations are:
export declare class ParameterToolRuntime { static registerSignalEmitter(emitter: ISignalEmitter | null): void; static registerVolumeSink(sink: IVolumeSink | null): void; static registerPresetPlayer(player: IPresetPlayer | null): void; static registerResizeSink(sink: IResizeSink | null): void; static registerHighlightSink(sink: IHighlightSink | null): void; static registerInputToggle(toggle: IInputToggle | null): void; static get signalEmitter(): ISignalEmitter; static get volumeSink(): IVolumeSink; static get presetPlayer(): IPresetPlayer; static get resizeSink(): IResizeSink; static get highlightSink(): IHighlightSink; static get inputToggle(): IInputToggle;}Register every seam the live file declares during boot, before ParameterManager initialises,
e.g.:
ParameterToolRuntime.registerSignalEmitter(SignalBus);ParameterToolRuntime.registerVolumeSink(AudioService);ParameterToolRuntime.registerPresetPlayer(AnimationPresetService);ParameterToolRuntime.registerResizeSink(ResizeService);ParameterToolRuntime.registerHighlightSink(HighlightService);ParameterToolRuntime.registerInputToggle(InputToggleService);Each seam is registered independently because they are independent capabilities — a project with no
preset animations registers the others and leaves presetPlayer unset (same for any other seam the
project genuinely doesn’t use). This is the interface-and-provider seam that keeps parameter-tool
free of a game-foundation dependency; the package names only its own interfaces, never a concrete
game-foundation class.
A missing seam fails silently at runtime — there is no compile error and no warning.
Step 5 — Remap scene/prefab script uuids
Section titled “Step 5 — Remap scene/prefab script uuids”The submodule scripts and the package scripts have different meta uuids. In MainScene.scene (and any prefab referencing a foundation component, e.g. AudioEmitter.prefab), remap __type__ / _componentId / __uuid__ from the old submodule-script uuid to the package-script uuid. Missing this = component silently detaches in the editor. Do this in the Cocos editor (drag-reassign) or by matching each old uuid to the new .ts.meta uuid.
Step 6 — Remove orphans
Section titled “Step 6 — Remove orphans”Delete any .meta whose prefab no longer exists after the swap.
Step 7 — Verify
Section titled “Step 7 — Verify”Run the splitter-defect scanner (also the entry point for --verify-only):
bun "$HOME/.claude/skills/t1k-cocos-playable-submodule-to-package/scripts/scan-missing-sibling-imports.cjs" \ <project>/assets/packages/@playablelabs/game-foundation \ <project>/assets/packages/@playablelabs/parameter-toolFor each DEFECT: line, add the printed import { … } from './<Sibling>'; to that .core.impl.ts. Exit 0 = clean.
Then run the stale-relative-import scan — a db://-only grep sweep reports false-clean while a relative import (../PLAGameFoundation/...) still resolves into a deleted submodule directory:
bun "$HOME/.claude/skills/t1k-cocos-playable-submodule-to-package/scripts/scan-missing-sibling-imports.cjs" \ --stale-imports <project>For each DEFECT: line, rewrite the printed import to the equivalent db://assets/packages/@playablelabs/... path (per Step 4). Exit 0 = clean.
Then open the project in the Cocos editor and confirm LOADING→FTUE→GAMEPLAY runs (the ParameterToolRuntime seams from Step 4a are what let the flow start). If the flow stalls at LOADING, an unregistered seam is the first thing to check — it produces no error, only silence. A flow that runs does NOT prove parameters apply: also confirm the host SDK never logs Parameter config not found for key: ... at startup — that line means PlayableConfigProvider.initialize(config, meta, currentSdk) was never called.
Executed by
Section titled “Executed by”The sibling-import scan is a script; the migration is not a find-and-replace. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run scan-missing-sibling-imports.cjs and list each unresolved import with its file | t1k-list-classifier |
| Perform the submodule to package migration | t1k-cocos-base-developer — reasoning tier |
Hard rules
Section titled “Hard rules”.core.impl.tsfiles trip the descriptive-name Edit/Write hook. TheirPascalCase.core.impl.tsnames are rejected by the naming hook onEdit/Write. Patch them with a Nodefsone-liner viaBash(the hook only guards Edit/Write), or in the editor.- The bug is invisible to type-checking. Every
.core.impl.tscarries// @ts-nocheck, sotsc/t1k-cocos-base-tsc-validatewill NOT catch the missing import. Only runtime execution (or this scanner) does. (The TS2352 cast defect above is the exception — it surfaces IN the type-check, because it lives in.core.ts, not.core.impl.ts.) - Step 5’s uuid remap can be a legitimate no-op — verify before editing scene JSON. If the vendored package’s script kept the exact same
.ts.metauuidas the old submodule script (this happens when the package build reuses the source file without regenerating its meta), the scene/prefab already resolves to a valid component and there is nothing to remap. Before touchingMainScene.sceneor any prefab, diff the package’s.ts.metauuidagainst the__uuid__/_componentId/__type__values already referenced there. Only edit the scene/prefab JSON when that diff shows a real mismatch — blind-editing a working scene file on the assumption that Step 5 always applies risks corrupting references that were already correct. - Do not confuse with
t1k-cocos-base-migrate. That skill is the Cocos 2.4.15 JS→TS pipeline. This skill is Cocos 3.8.7 submodule→package and shares no code.