Skip to content

t1k:playablelabs:base:params

FieldValue
Modulebase
Version2.29.2
Effortmedium
Tools—

Keywords: engineType WEB, packer dashboard parameters, parameter publish web game, pla-params, sdk-bridge

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

  1. 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 through mainTheOneSdk.getParameterValue(key) (the bridge installs it via a window.mainTheOneSdk setter trap). The packer never writes that script.
  2. 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.
  3. Compressed bridge (pla-pack --deflate only): the packer emits
    • a <meta name="pla-params" content="v1;deflate-raw;<encoding>"> in <head>, <encoding> = base64 or base122 (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 creates mainTheOneSdk. Without --deflate there 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.

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 jsonParameter 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 valuesParameterControllergame code (web ParameterController reading through mainTheOneSdk)
PARAM_UPLOAD_ASSETSallowedrefused (image defaults stay local repo paths)
networksUrlsent by the Cocos fleetopt-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)”
  1. Leaf-key diff of the web json against the Cocos repo’s assets/ParameterToolBuild/playable-config.json (read it with git show origin/develop:<path>, not by pulling into a dirty clone): 0 differences.
  2. List every definition-only key (defined so the dashboard shows it, not applied by the web game yet; it logs one console warning).
  3. Deliberate default divergences get a pinned-baseline companion test (assert by identity, both directions).
  4. 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).
  5. 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_ID is set (trimmed, validated as an 8-4-4-4-12 hex id), AFTER the R2 upload stage. Credential id playablelabs-api-token. Missing config file => build error.
  • PARAM_ENGINE_HOST cocos-3.8 and web publish; none is REFUSED up front with a version id set.
  • engineType is sent for web only (publishParameters). Table engineTypeForHost: cocos-3.8: COCOS, none: CUSTOM, web: WEB (mirrors the dashboard’s ENGINE_HOST_TO_ENGINE_TYPE, PlayableLabs packages/shared/src/engine-capabilities.ts, pinned by tests/jenkinsfile-publish-engine-type.test.js). For cocos-3.8/none the PUT body stays exactly {"paramContent": ...} with no engineType key.
  • 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/none only; refused on cocos-3.8 up front (the Cocos PUT body stays exactly {paramContent}). When on, after the paramContent PUT the job uploads dashboard-upload.zip (built by packDashboardTree, --layout superhtml) to R2 and PUTs {networksUrl: <cdn>/<R2_PREFIX>/dashboard-upload.zip} via builder.uploadJsonToPlayableVersionApi. The server ingests the zip and overwrites config.networksUrl with its own CDN URL, so it OVERWRITES the version’s build.
  • Ingest gates on the super_html substring, not on window.__zip; a missing __zip only 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.

PlaybleEngine@5c6dba7 (networksUrl) and PlaybleEngine@4ee4272 (the rest). Exact file list and what each pin covers: references/publish-notes.md.

  • --deflate is the whole switch. A page packed without it advertises no pla-params marker; sending it a compressed bridge does nothing. Marker encoding must match the platform’s encoder.

  • The engineType pin 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.md describes the Cocos runtime (PlayableParamterTool, window.mainVsdk / mainTheOneSdk globals, SDK value wins over the compiled-in default, null writes nothing). It is a Cocos-side report; do not assume a web game’s parameter code matches it.

  • Local asset paths. With PARAM_UPLOAD_ASSETS false a Cocos publish warns about local asset paths in playable-config.json; web refuses PARAM_UPLOAD_ASSETS outright.

  • 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.studio and dev.playablelabs.studio now 301 to playablelabs.ai; the host a publish PUT succeeds against is https://api.playablelabs.ai. The packer’s PARAM_PLAYABLE_API_ENDPOINT default is stale (its own description says so): override it on every run. PUT with the Bearer key from Jenkins credential playablelabs-api-token (never write a key into a skill); web body {paramContent, engineType:"WEB"}; networksUrl is 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-level def, 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 $schema key. PARAM_PLAYABLELABS_ORG must be the vault org that owns the version (theone for the reporting game); the default org returns HTTP 404. The web template’s gen:config emits $schema first; a bare {parameters} gets 400 “Missing required field: version”.