t1k:playablelabs:web:port
| Field | Value |
|---|---|
| Module | web |
| Version | 1.18.2 |
| Effort | medium |
| Tools | — |
Keywords: cocos to three.js port, port game to web host, port vs keep cocos, web engine host dist contract, web playable gotchas
How to invoke
Section titled “How to invoke”/t1k:playablelabs:web:port[<game dir> | decision | dist | gotchas]Porting a game onto the web / none engine hosts
Section titled “Porting a game onto the web / none engine hosts”Scope: getting a game’s build to satisfy the packer on the web host — the port-vs-keep decision,
the method that worked, the dist/ contract the packer needs, and a symptom → cause → fix table of
porting gotchas. Host mechanics, the flag table and the build-layout rules are t1k-playablelabs-base-engine-hosts
(link); packing and smoke flags are t1k-playablelabs-base-pack / t1k-playablelabs-base-smoke; the
runtime globals the game must publish are t1k-playablelabs-web-host-contract; the measured frame
playbook is t1k-playablelabs-web-perf.
Port, or keep Cocos?
Section titled “Port, or keep Cocos?”Decide before writing code. Full table with the cost anchors: references/port-vs-keep.md.
Port to web when | Keep cocos-3.8 when |
|---|---|
| The game must build on Linux/ARC CI — a Creator build needs a Windows agent | The game leans on a shim gap (list in the reference) |
| Artefact size matters (one measured port packed ~24.7 % smaller) | The Cocos build already meets size and fps on target devices |
| Most logic is engine-free (a large share copies verbatim) | Artists will keep iterating in Creator after launch |
| You can fund a QA harness that pairs the two builds | You cannot |
Unsupported by a three.js runtime shim today: physics, bundles and resources.loadDir, VideoPlayer,
sprite TILED, bitmap fonts and RichText tags other than <color>/<outline>, Button colour/sprite transitions, particle
noise/trails/sub-emitters. Budget these before choosing.
The method that worked
Section titled “The method that worked”Detail: references/port-method.md. Order matters — the first step prevents the rework the rest avoids.
- Contract first. One shared shape (asset slug rule, manifest shape, scene-data JSON shape, target layout, packer contract, lane rules) pasted verbatim into every parallel brief. Agents in isolated contexts cannot see each other’s code; a shape guessed twice differs twice.
- Scene-data extraction with prefab override resolution. Prefab instances expanded with overrides applied; asset ids mapped to manifest ids; effects summarised to drive shader re-implementation. Any non-zero “unresolved” row is a failed extraction.
- Meshes to glTF, clips retargeted. FBX carries no animation takes; the clips come from the source
engine’s
.animfiles retargeted into the GLBs against a reference skeleton, validated by bounding boxes per clip. - A source-engine-like runtime shim, so components port by changing imports. Re-implement only the used surface; a ported file differs from the original only in import lines plus a marked change site.
- Verbatim domain copy behind an architecture gate. Files that import no engine are copied byte for byte with their tests; the gate computes the layer rules from the real import graph.
- Port map plus parallel feature lanes, one lane per worktree.
- Autopilot QA pairing both builds by game time — real input, real GPU, state read from game objects, a numbered findings table re-judged each pass. Root-cause each finding before fixing it.
- Pack and smoke on the web host (see the contract below), then fold the same commands into CI.
The dist/ contract the packer needs
Section titled “The dist/ contract the packer needs”The packer reads the bundler output and classifies files. What it needs, and the bundler wiring that
produces it, is references/dist-and-packer-contract.md. In short:
dist/index.htmlat the root; game code as ONE top-leveldist/*.js, no content hash, classic script (<script defer src="./game.js">, not a modern bundler’s defaulttype="module"tag); runtime assets underdist/assets/**.- No
.gitkeepand noplayable-config.jsoninsidedist/— the packer would ship them as runtime assets. Keep the config at the project root. - Always pass
--engine-host webto BOTH pack and smoke; nothing warns you when it is missing. (The host flag selection rules are base-engine-hosts’.)
The pack itself runs in CI. Your job is the dist/ above; CI runs the packer and the smoke harness and
reports per-network sizes and a boot verdict.
Visual parity: colour, saturation, contrast (mandatory on the port’s polish pass)
Section titled “Visual parity: colour, saturation, contrast (mandatory on the port’s polish pass)”A port that matches in layout, geometry and timing can still ship duller and flatter than the
original — that is a real shipped defect, not a nicety (Colony Flow, below). On the packed build
vs the reference, at the same state and viewport, measure per named region (board, characters, ui):
mean HSV saturation S̄ (±0.04), luma stddev σ_L (±0.03) and per-channel means (±8/255). Root-cause
any delta through colour space, tone mapping, lighting/specular model, ambient, premultiplied alpha and
post effects before touching grading; a contrast/saturation grade is allowed only as a documented,
parameterised last step with the measured before/after. Outside tolerance blocks the Discord build
post unless the post discloses the delta. Full procedure, bands and root-cause order:
skills/t1k-playablelabs-base-clean-room/references/visual-parity.md (gate G9).
Runtime performance: the packed build against the original (mandatory)
Section titled “Runtime performance: the packed build against the original (mandatory)”A port can match every state, pass every gate and still run at a third of the original’s frame rate
on a phone — that is a real shipped defect (Colony Flow, FoodHunt, Hungry Gecko), and no other gate
measures it. Profile the PACKED build, not dist/ and not the dev server: the packer is where the
regression is introduced. Check first that the engine half of game.js ships un-obfuscated (split
build, /*! javascript-obfuscator:disable */, game half only; pack-log growth < ~5%) — the packer
obfuscating three.js and the cc runtime made every port ~2.3x slower in JS per frame. Then run the perf
harness on the packed artifact vs the Cocos original at the same state and viewport, start and mid-game:
draw calls, triangles, JS ms/frame p50/p95, alloc KB/frame; trust ratios and counts, not absolute ms, on
a loaded machine. A regression blocks the Discord build post unless the post discloses it. Full
procedure, known costs (double-drawn transparent double-sided, per-frame instance compares, setters
recomputing on unchanged values, UI batcher rewriting unchanged batches, spine allocations, pixel-ratio
cap) and the 60 fps / documented-floor target:
skills/t1k-playablelabs-base-clean-room/references/runtime-performance.md (gate G11).
Hard rules
Section titled “Hard rules”The full table (symptom → root cause → fix) is references/port-symptoms.md. The ones that cost the most time:
- Colony Flow shipped less saturated and lower contrast than the Cocos original with every gate green — strips, playthrough and top-face colour rows pass because none measures a distribution. Run the visual-parity gate above on the packed build; a uniform grade is the bug wearing a fix.
- Every web port ran ~2.3x slower than its Cocos original with every gate green — the packer
obfuscated the whole
game.js, three.js and the cc runtime included. Thedistthat was profiled was never the artifact a phone runs. Ship engine code un-obfuscated, profile the packed build; a regression against the original is disclosed in the build post or it does not ship. - Lighting is darker and bluer than the source engine — the source scene used HDR lighting and ACES tone mapping with raw light colours; a port that assumes LDR and sRGB-decodes the lights is wrong. Mean 30 px block colour distance 38.3 → about 16 after the fix.
- Still ~8 % dark after that — the source engine’s
sRGBToLinearisc * c, not the sRGB curve; textures must bind as raw bytes with a squaring map replacement. - A light does not reach meshes under a camera with a different layer mask — the renderer filters lights by the camera layer mask too. Give every light and the ambient an all-layers mask, and warm up per camera with the same layer culling.
- Imported skinned models have no clips — FBX animation takes are empty; retarget the source
engine’s
.animclips into the GLBs. - Phone-only: background zoomed / blurry / mis-framed, correct at DPR 1 — view scale returned CSS
px per design unit where the engine reports device px. Pixel ratio is
min(devicePixelRatio, 2). - Game runs in slow motion below 20 fps — a clamped
dt; pass the real frame delta and only replace a stall over 1 s. - A fresh build’s preview URL 404s for about an hour — the URL was polled before the upload
finished and the 404 was cached (
max-age=3600). Never poll before the job reports done; if a 404 is cached, append any query string (?r=1) — it is a different cache key. - Packed build 404s on HUD images and fonts that exist in
dist/: the packer runtime serves onlyfetch, XHR and.src; CSSurl()and@font-face srcbypass it. Load them by script (blob URL,FontFace) and grep-gateurl(./assetsinsrc/. - A ported runtime component ignores a changed property until another one changes (a
LabelfontSizeapplied only whenstringchanged) — the redraw is gated by adirtyflag that only some setters set. Make every property that feeds a cached raster an accessor that marks dirty on a real change (references/port-symptoms.mdrow 34).
Dev-server crashes that leave the loading splash up, runtime-shim traps (audio decode, writable anchors,
hover-as-input) and iPhone silent audio are in references/port-symptoms-dev-loop-runtime-audio.md. Check the
browser console before reading code: a stuck splash is almost always an uncaught module error.
Dashboard parameters on a web port: shared contract and audit checklist are t1k-playablelabs-base-params;
web-only deltas (gen:config, definition-only keys, CRLF artefact) are in references/port-symptoms.md.
Four of the gotchas (lighting, mip shimmer, DPR scale, quality cuts) were found by a human on a phone after the automated tests were green. Treat a phone pass as a required gate, not a nicety: the unit tests alone did not catch them.
Verified against
Section titled “Verified against”The packer’s web-port-guide reference as read on 2026-10-13 (the port it documents completed
2026-10-06). Numbers are from that one completed port; where a claim rested on it, the reference files
say so and are marked unverified where the source gave no basis. Re-measure on your target devices
before promising a frame rate.