t1k:playablelabs:base:params
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | medium |
| Tools | — |
Keywords: engineType WEB, packer dashboard parameters, parameter publish web game, pla-params, sdk-bridge
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:params[--deflate] [--engine-host web] [PARAM_PLAYABLE_VERSION_ID]Packer Parameters (dashboard values to a packed page)
Section titled “Packer Parameters (dashboard values to a packed page)”How PlayableLabs dashboard parameters reach a packed playable and how the Jenkins job publishes a game’s
parameter definitions. Boundary: authoring parameters INSIDE a Cocos game (the in-engine Parameter Tool,
ParameterController) is the Cocos kit’s (t1k-cocos-playable-parameter*, link only). Nothing here may
change Cocos behaviour: new behaviour is gated on web (see t1k-playablelabs-base-engine-hosts).
Runtime: how values arrive
Section titled “Runtime: how values arrive”- The packer seals the page. The PlayableLabs platform export then appends the game’s parameters as
<script id="sdk-bridge">AFTER sealing. The game reads them throughmainTheOneSdk.getParameterValue(key)(the bridge installs it via awindow.mainTheOneSdksetter trap). The packer never writes that script. - Raw bridge (default): the platform appends the bridge text as-is. Asset parameters (GLB, images, audio) ride in it as raw base64 data URIs, outside the compressed payload.
- Compressed bridge (
pla-pack --deflateonly): the packer emits- a
<meta name="pla-params" content="v1;deflate-raw;<encoding>">in<head>,<encoding>=base64orbase122(the row’s own blob encoding, so the platform must encode with the SAME one); window.__plaParams(encoded): decodes with the page’s own__plaDecode+ synchronous__plaInflateRaw(fflate), then executes the bridge text as a script. Synchronous on purpose: the bridge must run before the game createsmainTheOneSdk. Without--deflatethere is no marker and no hook (the inflater is the identity function), so the platform keeps sending the raw script. Failure is loud (console.error) and never fatal: the game keeps its compiled-in defaults.
- a
Source: src/runtime/params-hook.ts; emitted from src/cli.ts (renderParamsMarker), src/runtime/boot.ts.
The engine-matrix PARAMS probe (scripts/lib/params-probe.cjs) proves both bridge formats on a packed
page; run the packer’s own tests rather than reimplementing it.
Live updates: a visual parameter never needs a reload
Section titled “Live updates: a visual parameter never needs a reload”Rule. Every VISUAL parameter (judged by what is seen: colour, image, text, position, size, visibility, font
size) must show a dashboard edit in the running playable with no page reload. A gameplay DIAL (counts, speeds,
durations, difficulty, the Feel preset) must apply live too: one applyDials(progress) re-reads every dial,
setup calls it with zero progress and a PLA.onChange listener calls it with the progress so far, so a live edit
never leaves a value copied at setup. A STRUCTURAL dial (it shapes a board or layout built at setup) may rebuild
in place so the result equals a fresh load; say so per dial. Applies to Cocos and web alike.
Contract. The wrapper changes the value, calls mainTheOnePlayable.onParameterUpdated({key}) (Voodoo name:
mainPlayable), then the game re-reads getParameterValue(key). key is the top-level key; a group’s children
arrive as one object. Cocos: the parameter tool’s per-parameter onUpdate does this. Web: the core defines the
hook and drops its cached SDK read (PLA.refresh); a game must read visual values at draw time, or rebuild
what it cached in a PLA.onChange handler. Details and pitfalls: references/live-updates.md.
Verify, and make it go red first. In a game directory: bun ../_tools/audit.cjs --full --live applies every
parameter that has a region or a state probe AFTER load through that hook, demands the same pixel change as the
reload audit, and compares a LIVE page with a RELOAD page carrying the same value (whole state() deep-equal plus
a full-frame diff). state() must expose the APPLIED values, not parameter reads, or a stale dial hides. On a build
without the hook every probe fails (“no mainTheOnePlayable.onParameterUpdated hook”), and a dial copied at setup
fails with the differing state path (game.spawnMs reload=250 live=500): those are the negative controls. The
audit changes a dial at round start only, so also test one change mid-round (elapsed time kept, entities kept). By hand: the local test host’s /dashboard/<Game> tags each row live or restarts; drag a slider or
colour and the game must update without restarting.
Unverified. Proven against a mock wrapper and the parameter tool’s documented adapter contract, not against the packer’s web host or the real dashboard (the packer repo was not available). Confirm there before relying on it.
playable-config.json (shared contract, Cocos and web)
Section titled “playable-config.json (shared contract, Cocos and web)”The parameter DEFINITIONS (keys, types, defaults, min/max) the dashboard reads. It is an editor/game OUTPUT,
not a runtime input: nothing in a running playable loads it, and it lives in the game repo, not the packer.
For web the Jenkins job reads it at the game repo root (game/playable-config.json). Runtime values arrive
through window.mainTheOneSdk.getParameterValue(key) (see Runtime above); the game reads through it and
falls back to the compiled-in default when it returns null. The mechanic is the same for both engines; only
the author of the file and the applier of the values differ:
Cocos (cocos-3.8) | Web (web) | |
|---|---|---|
| Authors the json | Parameter Tool (assets/ParameterToolBuild/playable-config.json) | bun run gen:config (scripts/gen-playable-config.mjs) derived from src/platform/PlayableConfig.ts via the parameter-tool serializer (--check fails on drift); repo root, never in dist/ |
| Applies values | ParameterController | game code (web ParameterController reading through mainTheOneSdk) |
PARAM_UPLOAD_ASSETS | allowed | refused (image defaults stay local repo paths) |
networksUrl | sent by the Cocos fleet | opt-in PARAM_PUBLISH_NETWORKS_URL |
playable-config-advance.json (unfiltered, written by the Cocos Parameter Tool) is read by neither Jenkins
pipeline.
Audit / parity checklist (what legitimately differs per engine)
Section titled “Audit / parity checklist (what legitimately differs per engine)”- Leaf-key diff of the web json against the Cocos repo’s
assets/ParameterToolBuild/playable-config.json(read it withgit show origin/develop:<path>, not by pulling into a dirty clone): 0 differences. - List every definition-only key (defined so the dashboard shows it, not applied by the web game yet; it logs one console warning).
- Deliberate default divergences get a pinned-baseline companion test (assert by identity, both directions).
- Image/asset defaults: web defaults are local paths the dashboard cannot load. Until assets are uploaded or the default is an https URL, expect broken previews (open gap).
- Endpoint reachability: GET the API host before a publish run (see Gotchas).
Publishing (Jenkinsfile/PlayablePacker, stage “Publish parameters to PlayableLabs”)
Section titled “Publishing (Jenkinsfile/PlayablePacker, stage “Publish parameters to PlayableLabs”)”- Runs only when
PARAM_PLAYABLE_VERSION_IDis set (trimmed, validated as an 8-4-4-4-12 hex id), AFTER the R2 upload stage. Credential idplayablelabs-api-token. Missing config file => builderror. PARAM_ENGINE_HOSTcocos-3.8andwebpublish;noneis REFUSED up front with a version id set.engineTypeis sent forwebonly (publishParameters). TableengineTypeForHost:cocos-3.8: COCOS,none: CUSTOM,web: WEB(mirrors the dashboard’sENGINE_HOST_TO_ENGINE_TYPE, PlayableLabspackages/shared/src/engine-capabilities.ts, pinned bytests/jenkinsfile-publish-engine-type.test.js). Forcocos-3.8/nonethe PUT body stays exactly{"paramContent": ...}with noengineTypekey.- Why: the dashboard’s stored engineType is unreliable for production Cocos games (many are stored as UNITY, the version default), so Cocos must never overwrite it. Gate any new behaviour on WEB only.
- The dashboard answers 409 when a WEB switch hits a version that already has builds.
networksUrl(PARAM_PUBLISH_NETWORKS_URL). Opt-in, default false,web/noneonly; refused oncocos-3.8up front (the Cocos PUT body stays exactly{paramContent}). When on, after theparamContentPUT the job uploadsdashboard-upload.zip(built bypackDashboardTree,--layout superhtml) to R2 and PUTs{networksUrl: <cdn>/<R2_PREFIX>/dashboard-upload.zip}viabuilder.uploadJsonToPlayableVersionApi. The server ingests the zip and overwritesconfig.networksUrlwith its own CDN URL, so it OVERWRITES the version’s build.- Ingest gates on the
super_htmlsubstring, not onwindow.__zip; a missing__ziponly disables the store-link rewrite. The old Jenkinsfile comment withholding networksUrl because the packer emits__PLA_VFS__was wrong.
Evidence (PR, commit, pinned char counts, endpoint check): references/publish-notes.md.
Verified against
Section titled “Verified against”PlaybleEngine@5c6dba7 (networksUrl) and PlaybleEngine@4ee4272 (the rest). Exact file list and
what each pin covers: references/publish-notes.md.
Hard rules
Section titled “Hard rules”-
--deflateis the whole switch. A page packed without it advertises nopla-paramsmarker; sending it a compressed bridge does nothing. Marker encoding must match the platform’s encoder. -
The
engineTypepin moves with the dashboard. If PlayableLabs changes its table, the Jenkinsfile table and its pinned test fail together; re-pin both, never one. -
param-runtime-map.mddescribes the Cocos runtime (PlayableParamterTool,window.mainVsdk/mainTheOneSdkglobals, SDK value wins over the compiled-in default,nullwrites nothing). It is a Cocos-side report; do not assume a web game’s parameter code matches it. -
Local asset paths. With
PARAM_UPLOAD_ASSETSfalse a Cocos publish warns about local asset paths inplayable-config.json; web refusesPARAM_UPLOAD_ASSETSoutright. -
A new pipeline parameter registers only after a build of the new Jenkinsfile starts. The first trigger after merging silently drops it. Run once, then trigger again with the flag set.
-
Stale API endpoint.
playablelabs.studioanddev.playablelabs.studionow 301 toplayablelabs.ai; the host a publish PUT succeeds against ishttps://api.playablelabs.ai. The packer’sPARAM_PLAYABLE_API_ENDPOINTdefault is stale (its own description says so): override it on every run. PUT with the Bearer key from Jenkins credentialplayablelabs-api-token(never write a key into a skill); web body{paramContent, engineType:"WEB"};networksUrlis a separate PUT. -
pipeline{}has two size guards — a method budget and a growth guard (< 550 code chars vs base, comment lines excluded). Put logic in a top-leveldef, keep parameter descriptions short; a long parameter description alone can fail the growth guard (references/publish-notes.md). -
Publish needs the right org and a
$schemakey.PARAM_PLAYABLELABS_ORGmust be the vault org that owns the version (theonefor the reporting game); the default org returns HTTP 404. The web template’sgen:configemits$schemafirst; a bare{parameters}gets 400 “Missing required field: version”.