Skip to content

t1k:playablelabs:web:host-contract

FieldValue
Moduleweb
Version1.18.2
Effortmedium
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

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

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:

Terminal window
pla-pack --build <dist dir> --out <out dir> --engine-host web --json > pack-report.json
bun <packer>/scripts/smoke.cjs --out <out dir> --report pack-report.json \
--out-report ./smoke-report.json --engine-host web

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

Detail, exact semantics and a console one-liner per item: references/game-contract-checklist.md.

  1. At the very start of game code, window.__PLA_SCENE_WATCH__ = true, but only if item 2 is real.
  2. After the first frame of the first scene is drawn, window.__PLA_SCENE_UP__ = true.
  3. Once the first scene is built, window.__plaGame__ = { running, scene, nodeCount() }: running boolean kept current (false while paused), scene the current scene name as a string, nodeCount() returns the object count in it, at least 1.
  4. The CTA calls the compat shim on window.super_html (download(); order with game_end() is in t1k-playablelabs-base-engine-hosts), never a network SDK directly. No MRAID code of your own.
  5. --canary is not used: it is Cocos-only and the smoke rejects it on web / none.
  6. 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.

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.

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:

  1. window.__plaSplash.hide(), called when the first frame is drawn.
  2. window.__PLA_SCENE_UP__ = true (item 2 of the checklist), on the next drawn frame.
  3. Automatic: the packer finished replaying scripts and the game set neither __PLA_SCENE_WATCH__ nor called setProgress; 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.

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.

  • 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__ has running: false, a nodeCount() of 0, or was assigned before the scene was built and never updated. Publish it after the first scene.
  • nodeCount is a value, not a function — the smoke calls it; assign a function.
  • Smoke says not booted and failedRequests 404s assets/fonts/*.ttf — a font was loaded from a URL (new FontFace(family, 'url(...)'), a CSS @font-face src: url(...), FontFaceSet.load()). A CSS-initiated font request bypasses the packed page’s fetch/XHR/element.src VFS interceptors, so it 404s and face.load() rejects with NetworkError. Fetch the bytes first, then parse them: new FontFace(family, await (await fetch(url)).arrayBuffer()). Full row: t1k-playablelabs-web-port references/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 loading is queued by the packer and opened once on ready, 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 call setProgress(0)) synchronously in the entry script, then release with hide() 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-host to both.
  • --canary with web / 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=0 for scripted runs.

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.