Skip to content

t1k:playablelabs:base:engine-hosts

FieldValue
Modulebase
Version2.29.2
Effortmedium
Tools—

Keywords: --engine-host, engine host cocos-3.8, engine host none, engine host web, engine-host, none-host game contract

/t1k:playablelabs:base:engine-hosts
<cocos-3.8|web|none>

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

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.

HostBuild it expectsRuntime providerLayout / classification
cocos-3.8 (default)Cocos Creator 3.8.x build/web-mobilereal Cocos provider (engine-host-cocos38.ts)src/engine/cocos38/layout.ts; reads engine version + module list
weba bundler output: bun run build writes dist/index.html plus its files (src/engine/web/layout.ts)the same no-op provider as noneclassifies for real: top-level *.js = game code, assets/** by extension (texture/audio/font, rest = data); no engine class
noneany prebuilt dist, nothing about its shape knownno-op provider: boots VFS, generic interceptors, CTA; warns onceevery 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.

Your gameHost--build
Cocos Creator 3.8.x projectcocos-3.8 (omit the flag)<project>/build/web-mobile
three.js / PixiJS / any 2D or 3D web game with its own bundlerwebthe bundler’s dist/ (must hold index.html)
prebuilt page you cannot classify, or an engine the packer does not knownonethe 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).

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):

GlobalSet whenWithout it
__PLA_SCENE_WATCH__ = truegame code startsthe 30 s scene-up fallback card never arms
__PLA_SCENE_UP__ = truefirst frame of the first scene drawnboot-error listener only stops at its 15 s cap
__plaGame__ = { running, scene, nodeCount() }first scene built; keep running currentsmoke 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.

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.html at the root; game code as ONE top-level dist/*.js, no content hash, classic script (<script defer src="./game.js">, not Vite’s default type="module"); 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 repo root.
  • Always pass --engine-host web to 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 .meta mip chain); a missing chain shimmers on camera pans. Both are rows in the web-port-guide gotchas table above.
  • --canary is Cocos-only: refused for web and none (smoke exit 2, there is no engine module list to compare); detail in t1k-playablelabs-base-smoke.
  • --optimize runs only engine-neutral passes on web; naming --optimize-texture-downscale exits 2.

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

  • Forgetting --engine-host web on a bundler build packs it with the Cocos layout and the Cocos runtime hooks (which expect cc); classification follows Cocos rules. The packer will not warn you (no detect() call). Effect on boot is unverified: smoke it.
  • web still needs the page shell at index.html; cli.ts pulls it out of the scanned files before packing.
  • none is 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).