Skip to content

t1k:cocos:base:cleanroom-adapter

FieldValue
Modulebase
Version4.51.9
Effortlow
Tools—

Keywords: cleanroom adapter, cleanroom engine adapter cocos, cocos cleanroom, cocos-bootstrap, CocosTemplate scaffold, x-cleanroom

/t1k:cocos:base:cleanroom-adapter
[section]

Cocos adapter for t1k-cleanroom (extension slice, capability x-cleanroom)

Section titled “Cocos adapter for t1k-cleanroom (extension slice, capability x-cleanroom)”

t1k-cleanroom (theonekit-core) keeps the engine-neutral flow; everything Cocos-specific is data in this skill. Core resolves it with gamedev-adapter.cjs resolve --capability x-cleanroom --engine cocos, validates cleanroom/adapter.json against t1k-cleanroom-adapter/1 and hands the workflow the adapter BY PATH (the section files are read from disk, never inlined). Nothing here runs by itself. Cocos target is 3.x only (Creator 3.8.7). Core contract: the core skill’s own t1k-cleanroom/references/adapter-contract.md (sections 3 and 7) in the installed core kit. Needs core >=2.13.0 (R1); until it ships this skill is inert.

FileSectionStatus
gamedev-adapter.jsonextension slice, id cocos, declares only x-cleanroomsupported
cleanroom/template.jsonThe1Studio/CocosTemplate @ develop, bootstrap.{scaffoldCreate,scaffoldSkill}, platforms.{default,map,validateTarget}supported
cleanroom/layout.jsonCocos{{repoName}}, {{projSub}}/assets, assets/scripts/{{gameName}}/{models,gameplay,presentation}, gate dirs, commit pathssupported
cleanroom/roles.jsonbase{spec,build,judge,tester,git} + slices{build_models,build_gameplay,build_presentation}supported
cleanroom/prompts.jsonmotion, knowledge sweep, libraries, UI lane rule, lane rules, layout audit, library usagesupported
cleanroom/logic-recovery.json.prefab/.scene JSON, config.json, readable or minified JSsupported
cleanroom/scripts.jsonsprite meta (supported); library check and release scan (unsupported)partial
cleanroom/acquire.jsonstub, unsupported: owned by phase 7 (new 3.x intake via an omp lane)unsupported
cleanroom/validation.jsonstub, unsupported, runtime: player-build: owned by phase 8unsupported
scripts/cocos-bootstrap.cjscross-platform port of SetupProject.bat (--help lists exit codes, --json, never prompts)
scripts/sprite-meta-cocos.cjsCocos 3.x .meta JSON reader, same output schema as core’s sprite-meta.cjs

What was found in The1Studio/CocosTemplate (develop, read 2026-11-09, template repo, private)

Section titled “What was found in The1Studio/CocosTemplate (develop, read 2026-11-09, template repo, private)”
  • It is a template repo (isTemplate: true) whose project dir is CocosTemplate/ (Creator 3.8.7, package.json creator.version).
  • Four submodules in .gitmodules, all SSH: ConfigPath, CocosTemplate/assets/CocosGameFoundation, CocosTemplate/extensions/cocos-mcp-server, CocosTemplate/tools/optimize-size.
  • Four vendored packages in assets/packages/@playablelabs/: localization, motion, platform-cocos, platform-cocos-config (the README lists three).
  • SetupProject.bat steps: submodules, git mv CocosTemplate Cocos<repo>, node setup.js, npm install, platform-manager check, extension builds, setup-portals.js. The port does the first five and reports the last two as skipped[]. The .bat keeps a repo already named Cocos...; the port always uses Cocos<repo> so the dir equals layout.projSub.
  • The template has no lockfile, so the plan’s npm ci cannot work: the port runs npm install (package-lock.json is ignored by git).
  • Tests: Vitest 5 (vitest.config.ts, node environment, legacy decorators, db://assets alias) over assets/**/.tests/**/*.test.ts, run from the repo root with node ci/run-vitest.mjs <paths>. Pure modules are named *Rules.ts and ci/pure-modules-no-cc.test.mjs fails on any cc import in them. The template has no tsc CLI step; compilation happens in the editor.
  • The maintainer’s local clone was 7 commits behind origin/develop, so facts here come from origin/develop.

The bootstrap’s git mv moves the folder, not the pins that spell it (guards, prefab specs, docs, ci/build-config.template.json name). Nothing under ci/ may spell the folder; run node --test ci/*.test.mjs green before the scaffold counts as done. Full pin list and migration: references/rename-creator-folder.md.

Spike: can presentation code be type-checked without the editor?

Section titled “Spike: can presentation code be type-checked without the editor?”

Measured on a shallow clone of develop (submodules NOT initialised) with npm install and TypeScript 5, strict: false, db://assets/* path alias:

Runtsc errorsTS2307 on cc
no cc declarations26572
+ @cocos/creator-types 3.8.8 engine/cc.d.ts1470

The npm package supplies cc. What remains: modules of the uninitialised CocosGameFoundation submodule, @playablelabs/platform-* (vendored into node_modules by the platform-manager extension when the editor opens the project), and cc/env. Answer: partly yes, only after submodules are initialised and with the platform packages stubbed or installed; version 3.8.8 was measured, the template pins 3.8.7. UNMEASURED: the error count with submodules initialised, and with 3.8.7 declarations. validation.json therefore declares no tsc gate.

Contract (aligned to theonekit-core PR #6114, phase 2)

Section titled “Contract (aligned to theonekit-core PR #6114, phase 2)”

Pinned in tests/fixtures/core-phase2-pin/ (validator, hook library, schema at core 32f807066d81). Settled and applied here: hooks are bare path templates (scripts.spriteMeta); layout.assetsSub is clone-relative and includes the project dir ({{projSub}}/assets), proj and gameDir are absolute from {{clone}}; layout.layers.*Dir are path templates and gateDirs, commitPaths, layerPrompts exist; template.platforms holds validateTarget; scripts.stateLayout names projDirPrefix, assetsDir, placeholderMap, layoutMap, textMap, defaultTemplate; the vocabulary has repoOwner, {{shq name}} and {{#shq}}..{{/shq}} (no <OWNER>, no hand-quoting); the root may carry _origin and resolved only (R11). Dropped as unused by the workflow: layout.artDir, testsFolder, pureModuleSuffix, the unsupported releaseDefine (a non-string renders an empty define: Cocos has no preprocessor, dev-only grants stay behind a gateway whose release default grants nothing), prompts.uiLaneSkills (now named in prompts.uiLaneRule), template.bootstrap.{steps,ready}.

  • validation.runtime beside status: unsupported: the contract shows runtime on a supported section only (phase 8 owns the file).
  • roles.lanePartners: data, test, asset and editor agents have no workflow role key; kept as an informational map.
  • Core’s workflow still has Unity wording the adapter cannot reach (parked in #6114): the spec visual, animation and vfx prompts, SPRITE_FIT and .meta, the slice prompts (they name asmdefs and take their names from core’s fallback because Cocos declares no layout.asmdefs), GAMEPLAY_RULES #if, the wave .meta pathspecs. The scaffold SUCCESS CONTRACT requires {{proj}}/Library, which a Cocos clone does not have until the editor opens it.
  • The workflow appends /Data to the data dir, so the data folder is models/Data (core/Data for features), capital D, unlike the other lowercase folders.
  • The renderer in tests/cleanroom-adapter.test.cjs mirrors the grammar locally: core’s own lives inside cleanroom.workflow.js and is not importable. The same 142 strings were rendered once by hand with that function and none threw; that check is not in the test.
  • Real gh repo create and npm install end to end, and a cleanroom run with engine: cocos, are not run.

Each pointer in the first two items is asserted by the test, so a change in core turns it red at the spot.

The mechanical steps are scripts/cocos-bootstrap.cjs (scaffold a project from The1Studio/CocosTemplate) and scripts/sprite-meta-cocos.cjs (read a 3.x sprite-frame .meta), both deterministic with a --json mode and no prompts, so the cheap-tier t1k-list-classifier runs them. Neither writes to a game project beyond the paths the bootstrap prints, and every skipped step is reported in skipped[] rather than guessed at. Deciding which sections to fill, and any adapter-content edit, stays on the reasoning tier.

node .claude/modules/base/skills/t1k-cocos-base-cleanroom-adapter/tests/cleanroom-adapter.test.cjs (plain node, no worker pool). Set T1K_CLEANROOM_CORE_LIB to another core adapter-schema.cjs to test against it instead of the pin. Set T1K_GAMEDEV_SCRIPTS to theonekit-gamedev’s scripts/ to also run adapter-conformance.cjs (expects 4 manifests).