t1k:playablelabs:web:host-contract
| Field | Value |
|---|---|
| Module | web |
| Version | 1.18.2 |
| Effort | medium |
| Tools | — |
Keywords: __PLA_SCENE_UP__, __PLA_SCENE_WATCH__, __plaGame__, __plaPerf, device probes perf=1, game contract web host, none host game contract, scene-up fallback card, smoke not booted, super_html download
How to invoke
Section titled “How to invoke”/t1k:playablelabs:web:host-contract[checklist | probes | gotchas]Game-side contract for the web / none engine hosts
Section titled “Game-side contract for the web / none engine hosts”Scope: what YOUR game has to expose or do so the pack and the smoke succeed, as a checklist you can verify in your own build, plus the device-probe switches every web playable ships. The packer cannot inspect a web or prebuilt game’s engine, so the game reports its own state. CI runs the packer; you only make the build satisfy it.
Not here, linked instead:
- What each host is, which one fits which game, the flag table and the
dist/layout rules:t1k-playablelabs-base-engine-hosts. Its “none / web game contract” section holds the three-global table and the CTA call order; this skill does not repeat that table, it adds the checks below. - Packing flags and exit codes:
t1k-playablelabs-base-pack. Reading the smoke result:t1k-playablelabs-base-smoke. - Port-vs-keep decision and the
dist/bundler wiring:t1k-playablelabs-web-port.
State the host first
Section titled “State the host first”Say which host the game targets (web, none, or cocos-3.8) in the first message of the task. The
packer does not detect a mismatch between the flag and the build, so a wrong or missing flag fails
silently. Every command below passes the host explicitly:
pla-pack --build <dist dir> --out <out dir> --engine-host web --json > pack-report.jsonbun <packer>/scripts/smoke.cjs --out <out dir> --report pack-report.json \ --out-report ./smoke-report.json --engine-host webUse the SAME --engine-host value for pack and smoke. Use none only for a prebuilt page whose layout
you cannot describe; a bundler dist/ is web.
Checklist (verify in your own build)
Section titled “Checklist (verify in your own build)”Detail, exact semantics and a console one-liner per item: references/game-contract-checklist.md.
- At the very start of game code,
window.__PLA_SCENE_WATCH__ = true, but only if item 2 is real. - After the first frame of the first scene is drawn,
window.__PLA_SCENE_UP__ = true. - Once the first scene is built,
window.__plaGame__ = { running, scene, nodeCount() }:runningboolean kept current (falsewhile paused),scenethe current scene name as a string,nodeCount()returns the object count in it, at least 1. - The CTA calls the compat shim on
window.super_html(download(); order withgame_end()is int1k-playablelabs-base-engine-hosts), never a network SDK directly. No MRAID code of your own. --canaryis not used: it is Cocos-only and the smoke rejects it onweb/none.- A build served with none of the device-probe params in the URL behaves exactly as without the probes.
All three globals are optional, but each one unlocks a check. Without them the smoke can only fall
back to __PLA_SCENE_UP__, and the 30 s scene-up fallback card never arms.
What “booted” means
Section titled “What “booted” means”The smoke counts as booted when it saw at least 3 animation frames AND the game reports a running scene
with at least one node. A game that never publishes __plaGame__ is judged on __PLA_SCENE_UP__ alone.
Page splash (NOT on packer master yet)
Section titled “Page splash (NOT on packer master yet)”Status: the packer splash exists only in the open, unmerged PlaybleEngine PR #265 (feat/web-splash).
On packer master (4e15966) there is no --no-splash, --splash-params, --splash-config (pla-pack
exits 2 on them) and no window.__plaSplash. Do not pass those flags or call __plaSplash until #265
merges; the game’s own page-HTML splash is the path today (rule playablelabs-zero-black-first-load.md).
Re-check pla-pack --help first. The contract below describes what #265 adds.
pla-pack (with #265) paints the PlayableLabs Preloader splash (background, image, logo, progress bar, signature
centred under the bar) from page HTML before the game script runs; --no-splash leaves it out. Its
fields come from the Preloader dashboard group: live SDK value, then --splash-params, then
playable-config.json (--splash-config), then the built-in. The bar tracks real packer stages and
never a timer. The splash leaves on the first of:
window.__plaSplash.hide(), called when the first frame is drawn.window.__PLA_SCENE_UP__ = true(item 2 of the checklist), on the next drawn frame.- Automatic: the packer finished replaying scripts and the game set neither
__PLA_SCENE_WATCH__nor calledsetProgress; it hides after the second drawn frame.
A game that keeps loading after its bundle runs must opt out of 3 synchronously while its entry script
runs: set window.__PLA_SCENE_WATCH__ = true or call window.__plaSplash.setProgress(0) (then
setProgress(p), p in 0..1, monotonic). Later is too late: the splash is gone. Guard
window.__plaSplash with if; a --no-splash or Cocos page does not define it. Full contract:
src/splash/README.md in the packer repo.
Device probes
Section titled “Device probes”A web playable ships URL switches so a phone report becomes “CPU-bound” or “GPU-bound” in one run.
Rules, params, overlay fields and the verdict rule: references/device-probes.md.
Optional: window.__plaPerf (measurement hook, not part of boot)
Section titled “Optional: window.__plaPerf (measurement hook, not part of boot)”__plaPerf = { states, setState(name), passes, setPass(name, on), info() } lets the frame-cost harness
(t1k-playablelabs-optimize-gate) switch scene states, isolate one pass at a time and read per-frame draws.
It is optional: nothing here, in the packer or in the smoke requires it, and the generated template does not
install it. Install it only when the URL carries perf=1, in a QA/perf bundle; it must be stripped or inert in a
release build (no debug overlay or debug global ships), and setPass may only skip a draw. Shape, rules and a
copy-paste snippet: references/plaperf-snippet.md.
Hard rules
Section titled “Hard rules”- Fallback card on every load —
__PLA_SCENE_WATCH__is set but__PLA_SCENE_UP__never is (or is set too late). After 30 s of visible time with the flag still false the card appears. Set the watch flag only when the up flag is real. - Card disappears on its own — expected: it removes itself if
__PLA_SCENE_UP__arrives later. - Boot-error listener runs the full 15 s —
__PLA_SCENE_UP__missing; it only stops at its cap. - Smoke says not booted though the game plays —
__plaGame__hasrunning: false, anodeCount()of 0, or was assigned before the scene was built and never updated. Publish it after the first scene. nodeCountis a value, not a function — the smoke calls it; assign a function.- Smoke says not booted and
failedRequests404sassets/fonts/*.ttf— a font was loaded from a URL (new FontFace(family, 'url(...)'), a CSS@font-facesrc: url(...),FontFaceSet.load()). A CSS-initiated font request bypasses the packed page’sfetch/XHR/element.srcVFS interceptors, so it 404s andface.load()rejects withNetworkError. Fetch the bytes first, then parse them:new FontFace(family, await (await fetch(url)).arrayBuffer()). Full row:t1k-playablelabs-web-portreferences/port-symptoms.md#24. - CTA does nothing on an MRAID network at load — do not add queueing code. A tap while the
container is still
loadingis queued by the packer and opened once onready, bounded at 3 s. - Splash vanishes while the game still loads (blank or black page behind it) (only once PlaybleEngine #265 ships the packer splash) — rule 3 auto-hid it
after two frames because the game did not opt out in time. Set
__PLA_SCENE_WATCH__(or callsetProgress(0)) synchronously in the entry script, then release withhide()or__PLA_SCENE_UP__. - Host flag omitted or different between pack and smoke — the Cocos layout and hooks are applied to
a bundler build with no warning. Pass
--engine-hostto both. --canarywithweb/none— rejected; drop it.- Probe toggles change the shipped frame — a switch must only skip a draw; anything else (scene mutation, rounding the pixel ratio) corrupts the A/B comparison. See the rules in the reference.
- Probe overlay slows the bench — accounting must run only while the overlay is shown; use
perf=1&overlay=0for scripted runs.
Verified against
Section titled “Verified against”The packer’s none-host game contract and device-probes reference, read 2026-10-13. Numbers carry their
basis in the reference files; where the source gave none they are marked unverified. Re-measure on
your target devices.