Skip to content

t1k:cocos:playable:ref-port

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
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

/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.

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.

IntentPath
“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-heavyanimations[].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 yetcreate it from the playable template first (t1k-cocos-playable-preproduction), then ref-port-init

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.

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.

#PhaseLeadExecutes / citesArtifact
1Decode + measure the reft1k-cocos-base-developer runs the shipped scripts; Explore inventoriesreference-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)
2Port 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-validatebase-flow-map.md (filled), the composition root, constants-verification.md, .tests/, divergence-register.md (opened)
3Rebuild 3D layout + camerat1k-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 outlayout-3d.md (references/layout-3d.md); t1k-cocos-base-editor-mcp-truth; t1k-cocos-playable-tooling-gotchasscene-layout.json (every ref-rendered node carries a renderer), scene-wiring-table.md, EDITOR-HANDOFF.md
4Port 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-directorui-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, -parameterui-spec.json, audio-cue-table.md, sdk-cta-wiring.md, reports/ui-parity-<date>/
5Match materials + lighting — generation (gen-materials) runs unblocked; only the compare needs a running scene and is blocked on HARD-GATE-PLAYABLE-SLICEt1k-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.mdref-materials.json, reports/color-parity-<date>/
6Match VFX, animation + motion — generation (tools/gen-vfx.cjs) runs unblocked; only the compare needs a running scene and is blocked on HARD-GATE-PLAYABLE-SLICEt1k-cocos-base-developer (generators, frozen-time + time-series probes) · t1k-gamedev-playable-runtime-verifier (CDP probes) · t1k-gamedev-playable-visual-directorvfx-match.md (references/vfx-match.md); t1k-cocos-playable-unity-particle, -particle-ui, -juice; t1k-cocos-base-spinetools/gen-vfx.cjs, one reports/<effect>-<date>/ per effect, reports/motion-<date>/
7Fidelity 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-debuggerfidelity-audit.md (references/fidelity-audit.md); t1k-gamedev-playable-preview-verify; t1k-cocos-playable-build-size; t1k-cocos-playable-parameter-auditparity-audit/, closed register, verify-report.json, build-report.json, parameter-coverage.json, reports/motion-<date>/ (pass 8 re-run on the gated build)

(Gate 1) No Phase 2+ work starts until 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. Override: 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.

(Gate 2) Before the first 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. Override: --no-editor — Phases 3–5 emit EDITOR-HANDOFF.md for a human and make no editor write.

(Gate 3) Before any parity comparison/adjudication is written — Phase 4’s 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. Override: none for (a)-(c) or 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).

(Gate 4) A parity claim is accepted only when (a) it was produced by 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. Override: the owner accepts a named row with a stated reason, recorded in the register; for (e), 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.

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.

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.

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.

Six that make a build silently wrong; the catalogue lives in the phase references.

  • Colour space is measured, never assumed — three.js legacyMode treats authored hex as linear; Cocos linear: true squares on upload (material-match.md § 2–3).
  • _projection: 0 is ORTHO; MainCamera is owned by the dashboard AND any per-tick follow/state code — one owner only (#39; layout-3d.md § 2).
  • bunx tsc --noEmit is a false green on these projects — bun run typecheck, judged by path, after ref-port-init confirmed 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 create drops transforms, mesh and materials (#27); a save from a stale soft_reload/open overwrites 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).

  • t1k-gamedev-playable-extract — URL-only static analysis; orientation input, never a cite
  • t1k-gamedev-playable-preview-verify — the only automated runtime gate (Phase 7, ref-side driver)
  • t1k-gamedev-playable-ref-tools — owns the measurement scripts and the flow.json template, at .claude/skills/t1k-gamedev-playable-ref-tools/scripts/; Phase 1’s decoder calls and gate3-checks.cjs read it by sibling path
  • t1k-cocos-playable-tooling-gotchas § Quick Decision Guide — every editor/MCP trap cited by number
  • t1k-cocos-base-editor-mcp-truth — Gate 2’s preflight and read-back protocol
  • t1k-cocos-base-effect-authoring, t1k-cocos-base-unity-shader-port — materials and colour-space SSOT
  • t1k-cocos-playable-unity-particle, -particle-ui, -juice — VFX mechanics
  • t1k-cocos-playable-build-size, t1k-cocos-playable-parameter-audit — the size and coverage gates
  • t1k-cocos-base-knowledge-sweep — prior art before any phase builds something
  • rules/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

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.