Skip to content

t1k:playablelabs:web:port

FieldValue
Moduleweb
Version1.18.2
Effortmedium
Tools—

Keywords: cocos to three.js port, port game to web host, port vs keep cocos, web engine host dist contract, web playable gotchas

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

Decide before writing code. Full table with the cost anchors: references/port-vs-keep.md.

Port to web whenKeep cocos-3.8 when
The game must build on Linux/ARC CI — a Creator build needs a Windows agentThe 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 buildsYou 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.

Detail: references/port-method.md. Order matters — the first step prevents the rework the rest avoids.

  1. 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.
  2. 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.
  3. Meshes to glTF, clips retargeted. FBX carries no animation takes; the clips come from the source engine’s .anim files retargeted into the GLBs against a reference skeleton, validated by bounding boxes per clip.
  4. 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.
  5. 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.
  6. Port map plus parallel feature lanes, one lane per worktree.
  7. 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.
  8. Pack and smoke on the web host (see the contract below), then fold the same commands into CI.

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.html at the root; game code as ONE top-level dist/*.js, no content hash, classic script (<script defer src="./game.js">, not a modern bundler’s default type="module" tag); runtime assets under dist/assets/**.
  • No .gitkeep and no playable-config.json inside dist/ — the packer would ship them as runtime assets. Keep the config at the project root.
  • Always pass --engine-host web to 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).

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. The dist that 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 sRGBToLinear is c * 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 .anim clips 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 only fetch, XHR and .src; CSS url() and @font-face src bypass it. Load them by script (blob URL, FontFace) and grep-gate url(./assets in src/.
  • A ported runtime component ignores a changed property until another one changes (a Label fontSize applied only when string changed) — the redraw is gated by a dirty flag 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.md row 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.

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.