t1k:playablelabs:base:engine-hosts
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | medium |
| Tools | — |
Keywords: --engine-host, engine host cocos-3.8, engine host none, engine host web, engine-host, none-host game contract
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:engine-hosts<cocos-3.8|web|none>Packer engine hosts (--engine-host)
Section titled “Packer engine hosts (--engine-host)”--engine-host <id> tells the packer what kind of build it is packing. It picks two things together: the
in-page runtime provider spliced into the artefact, and the build layout that classifies files and reads
engine info. Flags and exit codes are in t1k-playablelabs-base-pack. Authoring a Cocos 3.8.7 game is the
Cocos kit’s job (t1k-cocos-playable-studio-engine, t1k-cocos-playable-sdk-core); this skill covers only
how the packer treats the build.
New behaviour is gated on web only. A change that alters what the cocos-3.8 host emits or reports breaks
the zero-Cocos-change constraint: read t1k-playablelabs-base-change-proof before touching host code.
Direction: PlayableLabs intends to move building playables off Cocos Creator to its own engine (the web
host: three.js, PixiJS; or none, no Cocos). Cocos stays supported and first-class for existing games; no
dates are promised. The packer’s own build defaults to TypeScript 7 (t1k-playablelabs-base-pack); a game
keeps its own TypeScript version.
The three hosts
Section titled “The three hosts”Registry: ENGINE_HOST_IDS = ['cocos-3.8', 'none', 'web'] (src/runtime/engine-host.ts), equal by test to
the build-layout registry LAYOUTS (src/engine/build-layout.ts). Default is cocos-3.8.
| Host | Build it expects | Runtime provider | Layout / classification |
|---|---|---|---|
cocos-3.8 (default) | Cocos Creator 3.8.x build/web-mobile | real Cocos provider (engine-host-cocos38.ts) | src/engine/cocos38/layout.ts; reads engine version + module list |
web | a bundler output: bun run build writes dist/index.html plus its files (src/engine/web/layout.ts) | the same no-op provider as none | classifies for real: top-level *.js = game code, assets/** by extension (texture/audio/font, rest = data); no engine class |
none | any prebuilt dist, nothing about its shape known | no-op provider: boots VFS, generic interceptors, CTA; warns once | every file classifies other; report declares no engine |
How selection works: parseArgs validates the flag against buildLayoutIds(); an unknown id prints
'<id>' is not a registered engine host. Known: ... and exits 2. the pack path then calls
resolveBuildLayout(args.engineHost), which THROWS on an unregistered id (no silent fallback).
boot.ts branches on engineHost === 'cocos-3.8' for the asset/module/scene-up hooks; any other id gets the
no-op fallbacks.
EngineBuildLayout.detect() exists on the interface, but nothing in src/ or scripts/ calls it at d76f263
(grep \.detect( returns zero hits). Selection is explicit: the packer will not warn you that the flag and
the build disagree. Check yourself that the id matches the build.
Which host for which game
Section titled “Which host for which game”| Your game | Host | --build |
|---|---|---|
| Cocos Creator 3.8.x project | cocos-3.8 (omit the flag) | <project>/build/web-mobile |
| three.js / PixiJS / any 2D or 3D web game with its own bundler | web | the bundler’s dist/ (must hold index.html) |
| prebuilt page you cannot classify, or an engine the packer does not know | none | the dist dir |
Prefer web over none whenever the output is a bundler dist/: none loses the engine/game/assets split.
Cocos-only features refuse other hosts: audit-modules exits 2; naming --optimize-texture-downscale exits 2
(--optimize umbrella just skips it and says so under optimization.skipped).
none / web game contract
Section titled “none / web game contract”The packer cannot inspect the game’s engine, so the game reports its own state through window globals
(source: .claude/skills/playable-engine/references/none-host-game-contract.md in the packer; web packs
through the same provider and smoke probe set, SMOKE_PROBE_SET_BY_ENGINE_HOST in scripts/smoke.cjs):
| Global | Set when | Without it |
|---|---|---|
__PLA_SCENE_WATCH__ = true | game code starts | the 30 s scene-up fallback card never arms |
__PLA_SCENE_UP__ = true | first frame of the first scene drawn | boot-error listener only stops at its 15 s cap |
__plaGame__ = { running, scene, nodeCount() } | first scene built; keep running current | smoke falls back to __PLA_SCENE_UP__ alone |
Set __PLA_SCENE_WATCH__ only if the game also really sets __PLA_SCENE_UP__, or every load shows the card.
CTA: call window.super_html.game_end() then window.super_html.download() (the shim every network row carries), in the same order the Cocos end handler uses; guard a shim that lacks game_end; never a network SDK directly. Per surface: an END-CARD tap fires game_end() exactly once per session (latched, on the first tap) and then download(); every later end-card tap fires download() only, never nothing and never a second game_end(). A HUD install button fires download() once per press and never game_end().
On MRAID networks the packer defers a tap made while the container is loading (renderCtaReadyDeferral,
web and none hosts only), so the game needs no MRAID code. Smoke “booted” on these hosts = at least 3
animation frames plus a running scene with at least one node.
Web host: porting route and dist shape
Section titled “Web host: porting route and dist shape”Porting a Cocos 3.8 game to the web host (three.js): the decision (port vs keep Cocos), the method, the
packer contract and a symptom/cause/fix gotchas table live in the packer repo, not here:
PlaybleEngine:.claude/skills/playable-engine/references/web-port-guide.md (origin and first port:
references/web-host-origin.md). Read it before planning a port; this skill does not duplicate it.
What the packer needs from the game’s dist/ (the guide’s section 3 has the why):
dist/index.htmlat the root; game code as ONE top-leveldist/*.js, no content hash, classic script (<script defer src="./game.js">, not Vite’s defaulttype="module"); runtime assets underdist/assets/**.- No
.gitkeepand noplayable-config.jsoninsidedist/(the packer would ship them as runtime assets); keep the config at the repo root. - Always pass
--engine-host webto BOTH pack and smoke; nothing warns when it is missing. - DPR: match the source engine’s view-scale and device-pixel semantics and its resolution cap exactly (never CSS px where Cocos uses device px); test at DPR 1, 2 and 3. A wrong scale shows only at DPR >= 2.
- Textures: carry the source engine’s sampler and mip settings (the Cocos
.metamip chain); a missing chain shimmers on camera pans. Both are rows in the web-port-guide gotchas table above. --canaryis Cocos-only: refused forwebandnone(smoke exit 2, there is no engine module list to compare); detail int1k-playablelabs-base-smoke.--optimizeruns only engine-neutral passes onweb; naming--optimize-texture-downscaleexits 2.
Verified against
Section titled “Verified against”PlaybleEngine@d76f263 (2026-10-07): src/engine/build-layout.ts, src/engine/noop-layout.ts,
src/engine/web/layout.ts, src/runtime/engine-host.ts, src/runtime/boot.ts, src/cli.ts
(parseEngineHost, resolveBuildLayout call), scripts/smoke.cjs, none-host-game-contract.md,
web-port-guide.md (path exists; content not re-read). git diff 4ee4272 d76f263 over src/, scripts/smoke.cjs, scripts/lib/ and the
contract file touches none of them (only scripts/ notify/canary/bench files), so the 4ee4272 read
stands; .detect( still has zero callers in src/ and scripts/.
Hard rules
Section titled “Hard rules”- Forgetting
--engine-host webon a bundler build packs it with the Cocos layout and the Cocos runtime hooks (which expectcc); classification follows Cocos rules. The packer will not warn you (nodetect()call). Effect on boot is unverified: smoke it. webstill needs the page shell atindex.html;cli.tspulls it out of the scanned files before packing.noneis silent about the missing engine except one stderr warning per run.--engine(provenance, recorded only) is a different flag from--engine-host(selects a provider).