Skip to content

t1k:cocos:playable:gamedev-adapter

FieldValue
Moduleplayable
Version4.33.13
Effortlow
Tools—

Keywords: adapter cocos-page-adapter, cocos page adapter, cocos runtime page, preview verify adapter, verify a cocos playable

/t1k:cocos:playable:gamedev-adapter
--serve-dir <builtDir> | --editor-project <projectDir> [--flow <json>]

Cocos page adapter for the shared preview verifier

Section titled “Cocos page adapter for the shared preview verifier”

Preview verification, QA flows and the design pack live in theonekit-gamedev (module playable). That tool has no built-in engine: everything that touches cc (the frame-rate cap, “the engine is up”, pause and resume, finding the editor preview port) is scripts/cocos-page-adapter.cjs in this skill. It is declared as the runtime.page capability in gamedev-adapter.json (extension slice; the primary slice is t1k-cocos-base-gamedev-adapter), with perf and build pointing at t1k-cocos-playable-build-size.

Terminal window
bun .claude/skills/t1k-gamedev-playable-preview-verify/scripts/preview-verify.cjs \
--adapter .claude/skills/t1k-cocos-playable-gamedev-adapter/scripts/cocos-page-adapter.cjs \
--serve-dir build/super-html/<channel> --flow flow.json --out out/

--serve-dir verifies the artifact that ships; swap it for --editor-project . to verify this project’s running editor preview (the adapter finds the port per editor, never a constant 7456), or --url for an already-known URL. Exit codes, flow steps, the report fields and the rest of the flags: theonekit-gamedev t1k-gamedev-playable-preview-verify and the cli reference it ships. Without --adapter the tool exits 2 and names the contract; without gamedev’s playable module installed this command does not exist (it is a dependency of this module).

MemberCocos fact
setFpsCap(page, fps)injects a script on every new document that sets cc.game.frameRate, polling up to 10 s for cc.game, and writes the applied value to globalThis.__t1kFpsApplied (the neutral read-back)
waitReady(page, timeoutMs)polls for cc.game._inited and at least one rendered frame; a page with no cc.game resolves not-cocos at once; rejects at the deadline naming the last probe
createAdapter({readiness})optional game-level readiness (#1984): readiness.probe and readiness.overlays are page expressions polled in order after the engine is ready — first gameplay screen up, then no blocking overlay left (tutorial, offline-earnings, no-ads pack) — against the same timeoutMs budget; the ready report gains gameReady / overlaysSettled, errors name the phase that hit the deadline, and a probe that can never pass is a TypeError at factory time. Dismissal taps stay in the capture flow (assets/templates/game-ready-boot-queue.flow.json). Without readiness the engine-only contract is unchanged
pause(page) / resume(page)cc.game.pause() / resume() (the whole loop, unlike cc.director.pause()), returning {paused} from cc.game.isPaused() so the verifier can fail a pause the engine did not take
resolveEditorPreview({projectDir})asks ports 7456 to 7471 for their page and keeps the one titled Cocos Creator - <project>; no match, no editor or two matches throw, never a fallback
hookTweennot provided: the tween recorder stays with t1k-gamedev-playable-ref-capture

t1k-gamedev-playable-qa-flows installs window.__qa from a template whose ENGINE object is a set of stubs the engine kit replaces. assets/qa-engine-adapter.js is the Cocos section (toPage through the UI camera, isActive, labelTexts, toggleNode, hitNodes): paste the block between its ===== ENGINE ADAPTER markers over the stub. The per-game half stays the game’s own; worked examples with cc types: references/tap-adapter-example.md, references/picbubble-adapter-example.md.

Reaching theonekit-gamedev’s skills from a Cocos script

Section titled “Reaching theonekit-gamedev’s skills from a Cocos script”

scripts/lib/gamedev-skills.cjs is the one lookup rule for the gamedev skills the Cocos reference-port scripts use (frame-compare, ref-decode, the flow template, preview-verify’s png lib): the sibling skill dir, or $T1K_GAMEDEV_PLAYABLE_SKILLS_DIR (exclusive; CI and local runs point it at a theonekit-gamedev checkout’s .claude/modules/playable/skills). A missing file is an error naming the path, never a fallback.

tests/cocos-page-adapter.test.cjs, tests/editor-preview.test.cjs, tests/scene-probe.test.cjs, tests/qa-engine-adapter.test.cjs and tests/gamedev-skills.test.cjs pin the members above. The ENGINE-section test splices into the real gamedev template, so it needs T1K_GAMEDEV_PLAYABLE_SKILLS_DIR outside an installed layout. Run them with bun test --max-concurrency=2 <file>.

Every standard or idle flow carries the Cocos board-visible probe as an assertEval: references/scene-probe.md, template assets/templates/idle-board-visible.flow.json, pinned by tests/scene-probe.test.cjs. The probe reads the Cocos scene graph, so it is engine-bound and stays here rather than in theonekit-gamedev.

Game readiness: the boot queue, tutorial overlays and late popups

Section titled “Game readiness: the boot queue, tutorial overlays and late popups”

Engine ready (cc.game inited, frames rendering) is not game ready: a template game with a boot queue is still on its loading screen then, and the tutorial overlay and late boot-queue popups (offline earnings, no-ads packs) land after that. Two pieces cover it (#1984):

  • createAdapter({ readiness: { probe, overlays } }) — game-supplied page expressions waitReady polls after the engine phase (see the contract table above).
  • assets/templates/game-ready-boot-queue.flow.json — the capture-flow shape of the same wait: settle the probes, screenshot, re-assert both after an idle window so an overlay that renders and is replaced still fails. Copy it and set the GAME_READY / OVERLAYS_SETTLED probe strings; dismissal taps for an overlay that will not auto-dismiss stay in your flow between the steps.

The page adapter and the QA helpers are scripts run through preview-verify.cjs; the skill is read-only guidance. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.