Skip to content
T1KTheOneKit

t1k:cocos:playable:modularize-refactor

FieldValue
Moduleplayable
Version0.15.0
Efforthigh
Tools—

Keywords: embedded-to-cpm, import-repoint, migration, modularize, playablesync, refactor

How to invoke

Section titled “How to invoke”
/t1k:cocos:playable:modularize-refactor
<project-root> --audit <path> --reuse <path> [--apply]

refactor (Pillar C, project-first)

Section titled “refactor (Pillar C, project-first)”

Turn the audit + reuse classifications into an ordered project refactor plan and (with --apply) execute it incrementally. Migrates the embedded framework (PLAGameFoundation, PlayableParamterTool) to CPM-package consumption. No package splitting — that is contribute. Part of the t1k-cocos-playable-modularize set — obeys the shared CLI contract.

When to invoke

Section titled “When to invoke”
  • After structure-audit + reuse-scan: produce the ordered migration plan.
  • To execute a migration incrementally (--apply, one package per gate).

Hard precondition

Section titled “Hard precondition”

Requires BOTH input reports: a structure-audit JSON (--audit) and a reuse-scan JSON (--reuse). plan-refactor.cjs sets preconditionsOk: false if either is missing/empty — the skill then hard-blocks --apply (report the missing input; do not guess a plan).

Ordering (safe → risky) — never reorder

Section titled “Ordering (safe → risky) — never reorder”
  1. Tier 1 — folder normalizations (create canonical dirs, gitignore artifacts, quarantine orphan metas to report).
  2. Tier 2 — REUSE swaps for already-installed packages (pure import-path changes).
  3. Tier 3 — embedded-submodule → CPM migration, per package: install → verify playableSync + assets/packages/@playablelabs/<n> → repoint imports → verify-imports.cjs green → confirm scene/prefab refs → remove embedded dir. Highest blast-radius.
  4. Tier 4 — tag CONTRIBUTE (no mutation; hand-off to contribute).

Full per-package procedure + rollback: references/migration-playbook.md.

Workflow

Section titled “Workflow”
  1. Validate <project-root> + confirm --audit/--reuse reports exist (else exit 2).
  2. Plan: node scripts/plan-refactor.cjs --audit <a> --reuse <r> → ordered step JSON (tiers + per-step risk + gate mode).
  3. Report the plan (safe → risky) → reports/ (plan-report format).
  4. (--apply only) Per migration unit: AskUserQuestion gate (proceed-one-unit) → on a dedicated branch, execute the Tier-3 procedure → node scripts/verify-imports.cjs <project-root> --scenes must exit 0 (import-resolution gate; the scene-UUID list is advisory) → confirm scene refs in the editor → commit the unit (pathspec form) → re-gate for the next. Never bulk-proceed Tier 3.
  5. (--apply only) Emit the change + status report — REQUIRED. After applying (even one unit), always write a change+status report so there is a record of what changed and how far the migration got. Compose it from: node scripts/refactor-status.cjs --plan <plan.json> --done <orders> --verify <verify-imports.json> --sync-before/--sync-after <package.json> (deterministic per-unit status + gate + playableSync delta) + git diff --stat for the touched files. Format: references/report-format.md § “Change + status report”. Never mutate the codebase without leaving this report.

HARD CONSTRAINTS

Section titled “HARD CONSTRAINTS”
  • Scope = assets/scripts. The import repoint + verify work operates on the project’s own scripts (that consume the framework). Package source is consumed as-is; the skill only reads/writes plain, readable TypeScript.
  • Never move/delete a .meta silently (UUID re-point risk). Co-move .meta with its file; orphan metas are quarantine-to-report. references/import-repoint.md.
  • register(ctx) does not exist — repointing is import-path-only.
  • Never git add ./-A — pathspec commits, one unit each.
  • Import-resolution green is the gate to remove embedded source. The --scenes UUID list is advisory only (Cocos compresses scene UUIDs → over-reports); the editor is authoritative for scene refs.

Scripts

Section titled “Scripts”
Terminal window
node scripts/plan-refactor.cjs --audit <structure-audit.json> --reuse <reuse-scan.json>   # ordered plan (report-only)
node scripts/verify-imports.cjs <project-root> --scenes    # exit 0 iff zero unresolved imports (scene-UUID list advisory)
node scripts/refactor-status.cjs --plan <plan.json> --done 1,2 --verify <verify.json> --sync-before <a> --sync-after <b>   # post-apply status

References

Section titled “References”

Gotchas

Section titled “Gotchas”
  • Migration is the highest-blast-radius step — one package per --apply, branch + rollback each, verify-imports green before removing embedded source.
  • Component UUIDs change on migration → scene/prefab refs to old embedded components go dangling; re-point them (editor/manual) before removing embedded source. verify-imports.cjs --scenes flags the dangling set.
  • Always leave a change + status report after --apply. Never mutate the codebase silently — every apply session records what changed (git diff —stat), the playableSync delta, the verify-imports gate result, and per-unit done/pending/rolled-back status.
  • Do not run without both reports — preconditionsOk: false hard-blocks --apply.
  • AnimalHunter target: migrate PLAGameFoundation → @playablelabs/game-foundation and PlayableParamterTool → @playablelabs/parameter-tool; folder-normalize game-assets/font and .optimize-data/ first (Tier 1).