t1k:cocos:playable:ref-port
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: 3d layout, audio parity, base flow, colour parity, composition root, coordinate conversion, divergence register, fidelity audit, fov, handedness, html reference, hud parity, hybrid engine ref, integrate gameplay, luna port, match the reference, material colour match, motion parity, parity gate, phaser port, pixi port, playable factory port, playable slice, playcanvas port, port playable, port to cocos, rebuild scene, ref port, reference playable, three.js port, vfx parity, wire gameplay components
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:ref-port<ref.html | ref-dir> [--project <cocos-project-dir>] [--phase decode|logic|layout|surface|materials|vfx|audit] [--no-editor] [--client-unity <package>]Cocos Playable — Reference Port (HTML ref → matching Cocos build)
Section titled “Cocos Playable — Reference Port (HTML ref → matching Cocos build)”One reference HTML playable becomes one Cocos Creator 3.8 project that implements and wires a
playable slice matching the ref: same gameplay logic and constants, same 3D layout and camera,
same materials, effects and pacing, numerically. The UI/game flow follows the base template
(GameView/LoadingView/EndCardView) carrying the ref’s own HUD/sounds/end-card content — a
structural difference the base flow causes is recorded as a base-flow non-divergence, not a
parity failure. Every known difference is written down and decided by the owner. Distilled from two
shipped ports — Hunter (AnimalHunterWildPLA: Luna/PlayCanvas ref + client Unity env) and
FlopHouse (FlopHousePLA: Three.js + Rapier) — whose plans, measurements and reports are the
evidence behind every rule here.
Orchestrator, main session, one phase per session. This skill sequences seven phases, holds
four HARD-GATEs and asks the owner every decision; it spawns one named agent per lane and
therefore does not declare context: fork (a forked skill has no Agent tool). It does not
decode, measure, port, author scenes or compare pixels itself — each phase names the agent that
does and the sibling skill that owns the mechanics. theonekit-core/.claude/skills/t1k-cook/references/workflow-gates.md is the HARD-GATE
contract; the gates below carry only their condition and override. Per-phase inputs, outputs,
agents and waves: phase-contract.md (references/phase-contract.md) — read it before the first spawn.
Principles
Section titled “Principles”P1 Integrate continuously, never last — attached, wired into the composition root, observed live, same phase (FlopHouse wired its root last: 28 commits match dead|wire|unwired|never|inert).
P2 Playable slice before parity — no comparison/audit before HARD-GATE-PLAYABLE-SLICE (Hunter: a 584-line audit written while the camera was ORTHO).
P3 Base flow owns the UI; the ref owns the gameplay — map every ref screen onto the base mechanism; a base-flow-caused structural difference is a non-divergence, never a parity failure.
P4 Fail loud at seams — no NULL-port/no-op fallback for an unbound @property; throw at boot naming the slot (FlopHouse shipped 19 NULL_*_PORT fallbacks that hid unwired seams for two days).
P5 Test the seam, not only the controller — at least one test drives the composition-root/signal path production uses.
P6 Template overrides are audited before they bite — seed the node’s ref value, or remove after a consumer scan (the recommended procedure; the incidents are in base-flow-integration.md § 5). Seeding alone is not enough once the port’s own per-tick code writes the same node too — derive from the param’s live value, never a duplicate constant, or the seed is silently overwritten (layout-3d.md § 2, base-flow-integration.md § 5).
Mechanics: implementation-port.md (references/implementation-port.md) (P1,P2,P4,P5), base-flow-integration.md (references/base-flow-integration.md) (P3,P6).
/t1k:cocos:playable:ref-port <ref.html | ref-dir> [--project <cocos-project-dir>] [--phase decode|logic|layout|surface|materials|vfx|audit] [--no-editor] [--client-unity <package>]Scaffold once with ref-port-init.cjs (flags, templates and what it writes: references/scaffold-and-runners.md).
Two test runners, name yours: vitest collects assets/scripts/<Project>/**/.tests/** ONLY; plan-dir
tools run under bun test; a “tests green” claim must name which runner produced it.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “Port this reference playable to Cocos” (fresh) | all phases in order → Pipeline |
| “Decode / measure the ref only” | --phase decode → reference-decode.md (references/reference-decode.md) |
| “Ref is decoded, port the logic” | --phase logic — needs Gate 1 passed (ref-spec-validate.cjs --gate --ladder exit 0); ships a wired Presentation slice per module, not domain/application alone → implementation-port.md (references/implementation-port.md) |
| “Rebuild / fix the 3D scene” | --phase layout → layout-3d.md (references/layout-3d.md) |
| “HUD / audio / end card / input / params differ” | --phase surface → ui-audio-sdk.md (references/ui-audio-sdk.md); base flow owns the UI → base-flow-integration.md (references/base-flow-integration.md) |
| “Colours / lighting differ” | --phase materials → material-match.md (references/material-match.md) |
| “Particles / effects / animation / pacing differ” | --phase vfx → vfx-match.md (references/vfx-match.md) |
| “Is it done? Audit parity, decide divergences” | --phase audit → fidelity-audit.md (references/fidelity-audit.md) |
| Ref is 2D-only (Pixi / Phaser / Cocos 2D) | engine.dimension: 2d; Phases 3/5/6 declared empty in ref-spec.json, Phase 4 is the port → reference-decode.md § 7 |
Ref is Cocos-built (index.html + assets/ + cocos-js/) | pass the dir; transform is identity; rank 1 = the build’s own import/**/*.json → reference-decode.md § 7 |
Ref is Unity WebGL without a Luna layer (UnityFS in Build/*.data) | no decode family: --client-unity is rank 1, else the behavioural-spec override → reference-decode.md § 7 |
Ref is a Playable Factory export (pf-namespaced globals, a hidden mime-less data:;base64, bundle) | engine.family: "playable-factory", hybrid engine.runtimes (e.g. ["threejs","pixi"]); no serialized scene asset → rank-2 dashboardParams + rank-3 bundle cite → reference-decode.md § 7 |
| Ref is Spine-heavy | animations[].runtime: spine + mix per transition; t1k-cocos-base-spine → vfx-match.md § 5 |
| “Analyse a competitor bundle from a URL, no port” | not this skill → t1k-gamedev-playable-extract |
| “Design a UI from a picture / Figma, no reference build” | not this skill → t1k-cocos-playable-ui-from-image, t1k-cocos-base-figma-to-ui |
| No Cocos project exists yet | create it from the playable template first (t1k-cocos-playable-preproduction), then ref-port-init |
Prerequisites
Section titled “Prerequisites”Prerequisites (bundle on disk, editor bridge via t1k-cocos-base-editor-doctor, knowledge MCP, headless
Chrome, Cocos CLI, optional client Unity source) and what to do when each is missing:
references/prerequisites.md. Check them before Phase 1.
Pipeline
Section titled “Pipeline”Seven phases; each leaves a committed artifact under plans/research/<ref-slug>/ or
plans/<yymmdd>-<ref-slug>/ (templates in assets/templates/) that the next phase reads — never
the previous phase’s chat. The critical path is one editor lane, not phase order: disk-only
generation for 3, 4, 5 and 6 fans out (own folders, no worktree), editor binds serialize through one
t1k-cocos-base-editor-operator lane, and the two compares run in parallel (phase-contract.md § Ordering).
Owner agents per lane are in phase-contract.md; the table names the lead only.
| # | Phase | Lead | Executes / cites | Artifact |
|---|---|---|---|---|
| 1 | Decode + measure the ref | t1k-cocos-base-developer runs the shipped scripts; Explore inventories | reference-decode.md (references/reference-decode.md) | authority-ladder.md, ref-spec.json (seeded, then gated with the ladder), asset-derived-facts.md, baseline.md, measurements/, base-flow-map.md (screen/flow inventory) |
| 2 | Port logic + integrate (2a base-flow map + template-override audit; 2b composition root skeleton; 2c per-module domain/app + tests + Presentation + root wiring + live-observed effect) | t1k-cocos-base-developer (port + composition root + Vitest) · t1k-cocos-base-editor-operator (attaches each module) · t1k-cocos-base-validator (labels the constants table) · t1k-cocos-base-reviewer (flow parity, line-ranged brief) | implementation-port.md (references/implementation-port.md); base-flow-integration.md (references/base-flow-integration.md); t1k-game-arch, t1k-cocos-base-clean-architecture, t1k-cocos-base-tsc-validate | base-flow-map.md (filled), the composition root, constants-verification.md, .tests/, divergence-register.md (opened) |
| 3 | Rebuild 3D layout + camera | t1k-cocos-base-developer (transform + disk JSON) · t1k-cocos-base-editor-operator (Gate 2 probe, every editor write, scene-dump.json) · t1k-cocos-base-validator (wiring table); lanes led by t1k-cocos-base-debugger when they fan out | layout-3d.md (references/layout-3d.md); t1k-cocos-base-editor-mcp-truth; t1k-cocos-playable-tooling-gotchas | scene-layout.json (every ref-rendered node carries a renderer), scene-wiring-table.md, EDITOR-HANDOFF.md |
| 4 | Port the 2D surface, base-flow first — HUD, fonts, strings, audio, boot, end card/CTA, input, params (own worktree, merged before its editor half) | t1k-cocos-base-developer · t1k-cocos-base-editor-operator · t1k-gamedev-playable-visual-director | ui-audio-sdk.md (references/ui-audio-sdk.md); base-flow-integration.md (references/base-flow-integration.md); t1k-cocos-playable-ui-from-image, -font-service, -localize, -gameflow, -sdk-core, -input-service, -layout, -parameter | ui-spec.json, audio-cue-table.md, sdk-cta-wiring.md, reports/ui-parity-<date>/ |
| 5 | Match materials + lighting — generation (gen-materials) runs unblocked; only the compare needs a running scene and is blocked on HARD-GATE-PLAYABLE-SLICE | t1k-cocos-base-developer (gen-materials, frame-compare.cjs) · t1k-cocos-base-editor-operator (shadowPcf) · t1k-gamedev-playable-runtime-verifier (same-pose frames) · t1k-gamedev-playable-visual-director (review) | material-match.md (references/material-match.md); t1k-cocos-base-effect-authoring § 5; skills/t1k-cocos-base-unity-shader-port/references/color-space.md | ref-materials.json, reports/color-parity-<date>/ |
| 6 | Match VFX, animation + motion — generation (tools/gen-vfx.cjs) runs unblocked; only the compare needs a running scene and is blocked on HARD-GATE-PLAYABLE-SLICE | t1k-cocos-base-developer (generators, frozen-time + time-series probes) · t1k-gamedev-playable-runtime-verifier (CDP probes) · t1k-gamedev-playable-visual-director | vfx-match.md (references/vfx-match.md); t1k-cocos-playable-unity-particle, -particle-ui, -juice; t1k-cocos-base-spine | tools/gen-vfx.cjs, one reports/<effect>-<date>/ per effect, reports/motion-<date>/ |
| 7 | Fidelity audit + gates (nine passes, incl. base-flow conformance) | t1k-gamedev-playable-runtime-verifier (gated build, flow with expectCta, diffs) · t1k-cocos-base-reviewer (register + base-flow conformance) · t1k-cocos-base-optimizer (performance, size) · t1k-cocos-base-validator (coverage) · t1k-gamedev-playable-visual-director (final pass); fix waves led by t1k-cocos-base-debugger | fidelity-audit.md (references/fidelity-audit.md); t1k-gamedev-playable-preview-verify; t1k-cocos-playable-build-size; t1k-cocos-playable-parameter-audit | parity-audit/, closed register, verify-report.json, build-report.json, parameter-coverage.json, reports/motion-<date>/ (pass 8 re-run on the gated build) |
bun <skill>/scripts/ref-spec-validate.cjs ref-spec.json --gate --ladder authority-ladder.md exits 0: the schema; every authority-ladder.md row carrying a rank (scene-serialized asset > shipped config asset > code default; live dump = cross-check; model summaries never a source) and a path, or its class declared empty with the command that proved it; designSize, cameras, lights and materials at rank ≤ 2 or rank 3 with a measured live artifact; every live-vs-asset disagreement carrying its override cite or a DECISION; the seven 2D sections present or declared empty with {reason, command, scope}.
A rank 1 or 2 citation may never be a bare live measurement (a live dump is a cross-check, never a citation); the remaining ladder and parameters[] rules: references/gates-detail.md § Gate 1.
A hollow warning (more than three sections declared empty, or an unreviewed parameters[] counted the same way) is answered by the owner, not silently accepted. behavioural-spec — the owner declares a class undecodable; the ladder records it as behavioural-spec (owner, date) and every port constant in that class is a DECISION row.
mcp__cocos-creator__* write of the session,
t1k-cocos-base-editor-doctor reports the bridge healthy, t1k-cocos-base-editor-operator reports
manage_project present in its own tools (a routed hop arrives without it), and its
manage_project get_info path equals the target checkout (uuid is inherited from the
template and proves nothing). FlopHouse spent a session writing every scene mutation into another
project, each call reporting success. --no-editor — Phases 3–5 emit EDITOR-HANDOFF.md for a human and make no editor
write.
reports/ui-parity-<date>/ review, Phase 5/6 compares, Phase 7’s audit; never before Phase 4’s own implementation, which may run ahead of this gate: an ungated preview build served by preview-verify --serve-dir --flow playable-slice-flow.json --adapter <page-adapter> (template shipped; one per viewport — pixel coordinates, not design units; never --url/editor screenshots), whose steps are until predicates, never a bare eval (a bare eval never fails the gate — only a until’s test does; implementation-port.md § 9 has the exact expressions): (a) boot/params-ready leaves 'loading', (b) tap/drag past the start gate, (c) a gameplay-state value the port owns changes after input vs. before, (d) a named ref-rendered node chain has an active MeshRenderer/SkinnedMeshRenderer with a mesh, (e) GameView.getCurrentState() (read through the engine, no debug global) reaches lowercase 'win'/'lose'; for a ref whose skipEndCardStage/failToStore path redirects with no end card, drop that until and set top-level "expectCta": "any" (the recorder is drained per step, so an in-page read misses an earlier CTA); at both viewports; exit 0; plus bun <skill>/scripts/gate3-checks.cjs (camera pose/fov, light presence, centre-region colour delta vs. a saved ref screenshot) exits 0 — closes the gap where (a)-(e) passed on a shipped run with zero lights and a 3.3x oversize model. Long-level route for clause (e) (solver replay through REAL input, never an onWin/onLose call or state poke; name the route used): references/gates-detail.md § Gate 3. gate3-checks.cjs; (d)/(e) only for a ref with no 3D / no end card, declared in ref-spec.json (engine.dimension: "2d" / endCard_declaredEmpty).
t1k-gamedev-playable-preview-verify --serve-dir <gated-build-dir> --flow <flow.json> --adapter <page-adapter> whose flow carries "expectCta", at two viewports — never --url/editor screenshots; (b) it names every open row of divergence-register.md, including physics/dynamic-body rows a screenshot cannot see; (c) every material, VFX, HUD-region, audio-cue and motion comparison quotes a measured number (frame-compare.cjs medians and mean |Δ|, diffPercent, particle counts at frozen T, curve-compare.cjs lag and duration ratio, cue start times from audio-timeline.json), not “looks the same”; (d) the size gate (playable-build.cjs --gate) and the parameter-coverage pass ran; (e) bun <skill>/scripts/divergence-register-gate.cjs divergence-register.md exits 0 — no camera/lighting/colour/scale/motion row left OPEN/DEFERRED. Clauses (a)-(d) are mechanically decided by parity-claim-gate.cjs (it checks a number exists, never that it is acceptable); how clause (e) reads the register: references/gates-detail.md § Gate 4. divergence-register-gate.cjs --override "<reason>".
Every DECISION row (accept vs must-fix, a feel constant, an asset slot) is the owner’s — batch
them into AskUserQuestion (max 4 per call) at the end of each phase. Never settle one silently;
never re-ask one already recorded. A phase-lead sub-agent cannot ask; it returns its DECISION
rows for the main session to batch.
Executed by
Section titled “Executed by”The owner’s judgment (rank a constant, accept a divergence) stays with a reasoning tier plus the owner via
AskUserQuestion; the mechanical fact-gathering is delegated per step — Phase 1 scripts to
t1k-cocos-base-developer, constants labelling to t1k-cocos-base-validator, preview-verify/curve-compare and
Gate 3 to t1k-gamedev-playable-runtime-verifier, size gate to t1k-cocos-base-optimizer, Phase 2c code then wiring to
t1k-cocos-base-developer then t1k-cocos-base-editor-operator. Full step-to-agent table: references/executed-by.md.
Sub-agent briefs
Section titled “Sub-agent briefs”Copy the brief template in phase-contract.md (references/phase-contract.md) (paths not payloads, owned file set, commit-by-pathspec,
four-heading delivery). Verification lanes get the anti-avoidance preamble and verify only, do not fix — brief guard details:
references/subagent-routing-facts.md § Brief template notes.
Routing facts every brief respects (MCP forwarding on routed hops, Write-less operator, who judges
images, tester vs runtime-verifier, debugger depth cap): references/subagent-routing-facts.md.
A developer brief never assumes the MCP.
After each phase — step 4b
Section titled “After each phase — step 4b”Restate the literal next invocation in the reply and the artifact’s ## Next action, then ask via
AskUserQuestion (next-phase / apply-this / review-first). One phase per session — end the session
at 4b, resume with --phase <next>. Before saying “finished”, divergence-register-gate.cjs plans/<port>/divergence-register.md must exit 0 (or a named --override). A lesson about this
skill goes to plans/<port>/lessons-queue.md, never mid-port; no port step blocks on a PR check or CI
watch. Full text: references/after-each-phase.md.
Hard rules
Section titled “Hard rules”Six that make a build silently wrong; the catalogue lives in the phase references.
- Colour space is measured, never assumed — three.js
legacyModetreats authored hex as linear; Cocoslinear: truesquares on upload (material-match.md§ 2–3). _projection: 0is ORTHO;MainCamerais owned by the dashboard AND any per-tick follow/state code — one owner only (#39;layout-3d.md§ 2).bunx tsc --noEmitis a false green on these projects —bun run typecheck, judged by path, afterref-port-initconfirmed the glob matches files (fidelity-audit.md§ 7).- Release build ≠ editor preview —
[...map.values()]becomes[].concat(iterator); a same-origin CDP re-probe runs the OLD bundle (rules/code-conventions-cocos.md). manage_prefab createdrops transforms, mesh and materials (#27); a save from a stalesoft_reload/openoverwrites your edit (#9, #60;layout-3d.md§ 4).
Turning a reference HTML playable into a Cocos 3.8 project whose gameplay logic, constants,
layout, materials, VFX and motion match the ref numerically, and whose composition root/
Presentation layer is implemented and wired into a gated playable slice — not artifacts alone; the
UI/game flow follows the base template with the ref’s content, by delegating each phase to the
named agent and skill. Not for: competitor analysis with no port (t1k-gamedev-playable-extract), UI
designed from a picture with no reference build (t1k-cocos-playable-ui-from-image), Unity→Cocos
of a project you own the source of (t1k-cocos-base-unity-shader-port,
t1k-cocos-playable-unity-particle directly), build-size work alone (t1k-cocos-playable-build-size),
scoping/estimating (t1k-cocos-playable-preproduction).
Related
Section titled “Related”t1k-gamedev-playable-extract— URL-only static analysis; orientation input, never a citet1k-gamedev-playable-preview-verify— the only automated runtime gate (Phase 7, ref-side driver)t1k-gamedev-playable-ref-tools— owns the measurement scripts and theflow.jsontemplate, at.claude/skills/t1k-gamedev-playable-ref-tools/scripts/; Phase 1’s decoder calls andgate3-checks.cjsread it by sibling patht1k-cocos-playable-tooling-gotchas§ Quick Decision Guide — every editor/MCP trap cited by numbert1k-cocos-base-editor-mcp-truth— Gate 2’s preflight and read-back protocolt1k-cocos-base-effect-authoring,t1k-cocos-base-unity-shader-port— materials and colour-space SSOTt1k-cocos-playable-unity-particle,-particle-ui,-juice— VFX mechanicst1k-cocos-playable-build-size,t1k-cocos-playable-parameter-audit— the size and coverage gatest1k-cocos-base-knowledge-sweep— prior art before any phase builds somethingrules/code-conventions-cocos.md,rules/prefab-only-construction-cocos.md,theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.md,theonekit-core/.claude/modules/t1k-verification/rules/wired-not-just-present.md
Visual change notice
Section titled “Visual change notice”Rule visual-change-discord-notice: porting a reference scene is a visible change. Capture OLD before the first edit and NEW after the last (preview-verify shot steps, or the image file itself for a 2D asset), return the paths and a draft Discord post (what changed, undo = revert the PR) to the orchestrator, who posts; never post from here. Logic-only: no visible change. No capture possible: screenshots pending: <reason>, never a mock image. The PR needs the Discord link or visual-notice-waiver: <reason>; the owning agent’s Visual change notice section has the full steps.