t1k:cocos:playable:gamedev-adapter
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | low |
| Tools | — |
Keywords: adapter cocos-page-adapter, cocos page adapter, cocos runtime page, preview verify adapter, verify a cocos playable
How to invoke
Section titled “How to invoke”/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.
The one command
Section titled “The one command”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).
What the adapter does (Cocos facts only)
Section titled “What the adapter does (Cocos facts only)”| Member | Cocos 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 |
hookTween | not provided: the tween recorder stays with t1k-gamedev-playable-ref-capture |
QA helpers: the Cocos ENGINE section
Section titled “QA helpers: the Cocos ENGINE section”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>.
Board-visible scene probe
Section titled “Board-visible scene probe”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 expressionswaitReadypolls 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 theGAME_READY/OVERLAYS_SETTLEDprobe strings; dismissal taps for an overlay that will not auto-dismiss stay in your flow between the steps.
Executed by
Section titled “Executed by”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”.