Skip to content

t1k:cocos:playable:submodule-to-package

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
Tools—

Keywords: game-foundation, package, parameter-tool, submodule, vendored

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

IntentPath
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 definedStep 7 — Verify → run the verifier, patch the flagged file

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.

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.

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.

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 siteChange
ParameterUtilsParameterReplacedAssetsHandler moved to assetParameterUtils/
PlayableConfig TableParameternow takes category after minItems/maxItems
VirtualJoystick TouchEndSignalnow requires (worldPosition, uiPosition)
ParameterControllergetTextureFromBase64 now resolves null (was: never resolves). Guard the null — an unguarded null yields a textureless SpriteFrame that throws in SpriteFrame.getHash
ParameterManagerparameter-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.initializenow 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.

Delete any .meta whose prefab no longer exists after the swap.

Run the splitter-defect scanner (also the entry point for --verify-only):

Terminal window
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-tool

For 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:

Terminal window
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.

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

StepAgent
Run scan-missing-sibling-imports.cjs and list each unresolved import with its filet1k-list-classifier
Perform the submodule to package migrationt1k-cocos-base-developer — reasoning tier
  • .core.impl.ts files trip the descriptive-name Edit/Write hook. Their PascalCase.core.impl.ts names are rejected by the naming hook on Edit/Write. Patch them with a Node fs one-liner via Bash (the hook only guards Edit/Write), or in the editor.
  • The bug is invisible to type-checking. Every .core.impl.ts carries // @ts-nocheck, so tsc / t1k-cocos-base-tsc-validate will 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.meta uuid as 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 touching MainScene.scene or any prefab, diff the package’s .ts.meta uuid against 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.