Skip to content

t1k:playablelabs:ci:jenkins

FieldValue
Moduleci
Version1.17.3
Effortmedium
Tools—

Keywords: packer jenkins pipeline, PlayablePacker, PlayablePacker Jenkinsfile

/t1k:playablelabs:ci:jenkins
[parameter | stage | gotcha]

Scope: how Jenkinsfile/PlayablePacker in the packer repo builds, packs, smokes, uploads and publishes a playable. Creating or cloning Jenkins jobs is core t1k-jenkins-job / t1k-jenkins-cocos (link only). Cocos project setup is the Cocos kit’s t1k-cocos-h5-jenkins-setup / t1k-cocos-playable-pipeline (link only). Web/none games with no Windows need: prefer t1k-playablelabs-ci-arc-workflow. QA the newest Quick Play build in a Discord channel and reply the verdict there: t1k-playablelabs-ci-build-qa. Read the Jenkinsfile itself before editing it; the packer’s rule is not to edit it unless your brief says so (PlaybleEngine .claude/skills/playable-engine/references/jenkinsfile.md General rule).

agent { label agentLabelForHost(params.PARAM_ENGINE_HOST) } (Jenkinsfile agentLabelForHost()):

  • Cocos (cocos-3.8) always runs on the Windows cocos agent. Creator is Windows-only here and its steps run through git-bash. PARAM_AGENT_LABEL=web-linux on a Cocos build is refused with an error (refuseWebLinuxOnCocos()), never silently ignored.
  • Web and none run on the Linux web-linux agents when PARAM_AGENT_LABEL=web-linux (opt-in; choices auto-cocos | web-linux). Left at auto-cocos they still map to cocos. Origin and design pointer: references/verification-history.md.
  • web-linux agents are Alpine inbound-agent containers with git/ssh/curl/docker and NO node, python3 or Chromium. webSh() runs each node step in a node:22-bookworm container (workspace mounted), the smoke stage in the pinned Playwright image (Chromium included), and provisionWebpUnix() installs a pinned libwebp 1.6.0 cwebp checked by sha256. onWebLinux() is true only for a non-Cocos build whose NODE_LABELS contain web-linux.
  • Web builds write the private-registry npm auth (withWebNpmAuth(), game/.npmrc) before the job’s npm clean install and restore the game’s own .npmrc afterwards; a failed auth is UNSTABLE, not red.

What the Jenkinsfile declares is not a live proof: confirm a Linux run from its console log ([web-build] npm run build exit 0, the web-linux: echoes), not from this text.

Parameters (names and defaults verified; 38 declared in the file)

Section titled “Parameters (names and defaults verified; 38 declared in the file)”
ParamDefaultMeaning
PARAM_GAME_REPO / PARAM_GAME_BRANCH'' (required) / developSSH URL + branch of the game; cloned to game/
PARAM_BUILD_FILE_NAME, PARAM_BUILD_VERSION'', 1.0.0playable name, version
PARAM_ENGINE_HOSTchoice cocos-3.8 (first), none, webcocos-3.8 Creator build; web npm build into dist/; none pre-built dist/
PARAM_NETWORKSallcomma list or all
PARAM_DEFLATE, PARAM_WEBPtrue, trueforwarded as --deflate, --webp
PARAM_OPTIMIZEchoice off (first), lossless, allopt-in optimize passes on BOTH pack calls (main and dashboard tree). off adds nothing: the pack command is unchanged. lossless = explicit lossless pass flags only (metadata-strip, audio-silence-trim, font-subset; on web also js-minify, and js-base64-repack with PARAM_DEFLATE), never texture-downscale or audio-mono. all = --optimize, which on Cocos INCLUDES the lossy texture-downscale. Mapping SSOT scripts/optimize-flags.cjs; non-off logs an optimize-audit summary first. Not verified on a live job
PARAM_LAZY_ASSETSchoice auto (first), off, allweb and none only; cocos-3.8 gets an empty flag for auto and off, and a red build for all (the packer exits 2). auto = --lazy-assets --lazy-assets-scope default (the rows whose network adapter declares lazyAssetsDefault, google today, read from the packer’s registry, so a new row needs no Jenkins edit). all = --lazy-assets on every row. Passed on BOTH pack calls. Flag facts and the game’s playable-lazy.json: t1k-playablelabs-base-pack, t1k-playablelabs-web-lazy-load. Not verified on a live job
PARAM_LAYOUTflatsuperhtml changes EVERY R2 path; smoke/netlint read flat only
PARAM_FAIL_ON_BUDGETtruered build when a network is over its ceiling
PARAM_SMOKEfalserun scripts/smoke.cjs stage
PARAM_CANARYfalseM3 runtime canary; needs PARAM_SMOKE (else UNSTABLE)
PARAM_NETLINTfalsestatic per-network validator stage
PARAM_PLAYABLE_VERSION_ID''UUID; empty skips the Publish stage
PARAM_PLAYABLELABS_ORGdefaultstring, not a choice: adding an org needs NO Jenkinsfile edit. default = the org owning Jenkins credential playablelabs-api-token. Any other value NAME (after trim + lowercase, must match ^[a-z0-9][a-z0-9-]{0,40}$, else the build errors up front) = studio-vault secret playablelabs-api-token:NAME on https://api.playablelabs.ai; add it with t1k vault request playablelabs-api-token:NAME and grant the Jenkins vault key (svc:key:vault-jenkins) read access. PARAM_PLAYABLE_API_ENDPOINT must stay at its default for a non-default org. rollic keeps an explicit row in PLAYABLELABS_ORGS (the per-org override table). Not verified on a live job
PARAM_UPLOAD_ASSETS / PARAM_REMOVE_ASSETSfalse / falseCocos only; Remove needs Upload
PARAM_ENGINE_SHA'''', pinned, or 40-hex cocos-engine SHA (Cocos only)
PARAM_AGENT_LABELchoice auto-cocos (first), web-linuxweb-linux runs a web/none build on the Linux agents; refused on Cocos
PARAM_START_SCENE, PARAM_SCENE_INCLUDED'', ''Cocos start scene UUID / included scenes; no file records the start scene
PARAM_DISCORD_THREAD_ID1551151691749920860Discord thread the result embed is posted to. Jenkins itself holds the bot token (credential discord-bot-token, bound as DISCORD_BOT_TOKEN), so this path needs no repo secret

Other params exist (PARAM_COCOS_TOOL_NAME Cocos 3.8.7, PARAM_ORIENTATION_TYPE landscape, BUNDLE_MODE asmjs, PARAM_AUTO_CROP_MODULES, PARAM_SUPERHTML_PARITY, PARAM_ENGINE_DIR_DIAG, Voodoo params, PARAM_WIPE_OUT_WORKSPACE, PARAM_SHOULD_NOTIFY_TO_CHAT_CHANNEL): the full name list is scripts/packer-params.data.json; or grep parameters { in the file. Never add env.X ?: defaults: they freeze the last-used value (file comment at PARAM_NETWORKS).

Voodoo (VOODOO=true, every engine host). An extra deliverable built after the R2 upload from the applovin build: PARAM_NETWORKS must contain applovin or all, PARAM_UPLOAD_ASSETS / PARAM_REMOVE_ASSETS must be off, and PARAM_ENGINE_HOST must be cocos-3.8 or web (none has no playable-config.json for it to read); all refused up front by refuseVoodooMisconfig(). It clones The1Studio/VoodooTemplate, runs scripts/voodoo-prepare.cjs (no window.__zip splice: the page is normalised by dropping html/head/body tags outside scripts; the config is conformed to Voodoo’s closed schema, one voodoo-prepare: adjusted ... log line per change: root storeLinks/metadata dropped, number min/max/step -> range or dropped, 8-digit colour -> #RRGGBB, an asset param with an empty default removed (Voodoo needs a real file; no placeholder is invented), a table inside an object refused), the template’s npm install, scripts/voodoo-validate.cjs (the template’s own ajv + schema, exact field paths instead of ply pack’s opaque Invalid build configuration), the template’s pack script, and publishes <PARAM_BUILD_FILE_NAME>_Voodoo.zip to <R2 prefix>/voodoo/ (the fleet job’s Cocos<name>_Voodoo.zip under its upload url is NOT used here; look for the new name and path), then lists it as a Voodoo ZIP link in the Discord embed. Every asset default in the game’s playable-config.json must be a REAL path relative to the game project (game/): voodoo-prepare resolves it literally, never searches by file name, and refuses a missing file; an empty ("") asset default is removed by voodoo-prepare (one adjusted line per parameter). Store links come from PARAM_STORE_LINK_ANDROID / PARAM_STORE_LINK_IOS. Still refused on the branch-canary job.

PlayablePacker is one shared job (CocosPlayableLabs/PlayablePacker). Setting up a game is choosing parameters, not creating a job. Run the script on a checkout of the game repo:

Terminal window
bun scripts/packer-params.cjs <game-dir> [--repo-url git@github.com:Org/Game.git] [--branch develop] \
[--name Game] [--networks applovin,google|all] [--orientation landscape|portrait] [--engine cocos-3.8|web|none]

It prints JSON {engine, agentLabel, params, cleared, warnings}. Detection is read-only and reads no credentials:

EngineSignalPARAM_ENGINE_HOST / PARAM_AGENT_LABEL
Cocos Creatorassets/ + settings/v2/packages/, or package.json creator, or .creator (same signals as the project-detection reference of core t1k-jenkins-cocos; capital Assets/ is Unity, not Cocos). Fleet layout: with no markers at the root, a Cocos<Name>/ child directory that has them (the Jenkinsfile builds game/Cocos${PARAM_BUILD_FILE_NAME}); PARAM_BUILD_FILE_NAME defaults to <Name>, one child only (several: exit 3 listing them)cocos-3.8 / auto-cocos
webpackage.json scripts.build, no Creator markers (the job installs and builds it with npm in buildWebGame() and needs dist/index.html)web / web-linux
prebuiltdist/index.html, no build scriptnone / web-linux

For web/none every Cocos-only parameter the Jenkinsfile refuses (refuseCocosOnlyParams()) is set explicitly off in params and listed in cleared: PARAM_CANARY, PARAM_AUTO_CROP_MODULES, PARAM_ENGINE_SHA, PARAM_ENGINE_DIR_DIAG, PARAM_UPLOAD_ASSETS, PARAM_REMOVE_ASSETS, PARAM_SUPERHTML_PARITY, plus PARAM_PLAYABLE_VERSION_ID for none only (web may publish). Exit codes: 0 ok, 2 usage, 3 engine undetectable or ambiguous (reason printed; --engine overrides), 4 drift (--check-drift). A Cocos result never sets PARAM_START_SCENE (a product decision; the warning says so) and leaves PARAM_COCOS_TOOL_NAME at the job default when the Creator version is not readable. Creator-version detection is unconfirmed against a real checkout (same caveat as core’s detector).

Workflow:

  1. Web or none game that targets Google: commit the lazy policy first. The job builds a web game from the commit it clones, so public/playable-lazy.json must be on that commit. Build the game locally so dist/ exists, then run bun "<web-lazy-load skill dir>/scripts/gen-playable-lazy.cjs" --build <dist> --out public/playable-lazy.json (or --check when the file already exists) and commit the file. Modes, exit codes and the policy contract: t1k-playablelabs-web-lazy-load. Skip for Cocos. PARAM_LAZY_ASSETS keeps its job default auto; the script does not set it.
  2. Run the script; show the user params and warnings; resolve what the warnings name (PARAM_START_SCENE, a non-SSH repo URL, the proposed PARAM_BUILD_FILE_NAME).
  3. Trigger with the Jenkins MCP triggerBuild on CocosPlayableLabs/PlayablePacker, passing params as-is (parameters not listed keep the job defaults). PlayablePacker is shared by every project, so the build number it returns is not yours until you prove it is.
  4. Resolve YOUR build — never by lastBuild. Another team’s build on the shared job can start first and take the next number, and “the first lastBuild greater than the previous” then reports their result as yours.
    • Take the queue item triggerBuild returns (getQueueItem); if the tool omits the id, read it from the response Location header (or the getQueue list). Poll it until executable.number appears — that number is your build.
    • Second check, before you wait or report: read the build’s ParametersAction and assert PARAM_GAME_REPO, PARAM_GAME_BRANCH and PARAM_DISCORD_THREAD_ID are the values you sent. A mismatch is not your build: go back to the queue item, never report it.
    • No queue id anywhere: match parameters across the recent builds for your repo + branch + thread. Still never lastBuild alone.
    • Confirm the commit actually built: the console may not print the game SHA, so compare the branch head (or the merge time) against the build’s start, or have the notify carry the SHA.
  5. Watch with getBuild (and getBuildLog on red) on that resolved number. Read the console, not the colour. A web build must show [web-build] npm run build exit 0; a Cocos build shows the Creator exit 36/0 line. On web-linux the log also carries web-linux: echoes from the Chromium and cwebp steps.
  6. The Discord embed lands in PARAM_DISCORD_THREAD_ID (default and token ownership: the parameter table above); check the thread, not just the build result. GET-verify each CDN play link (200) before you post or report it.

The legacy per-game job built from Jenkinsfile/Cocos (one Jenkins job per game, created from a stored spec) is core t1k-jenkins-cocos: it still applies when a team owns such a job or needs a plain Creator build outside the packer. New playables go through PlayablePacker. Do not restate that skill here.

Drift. scripts/packer-params.data.json is the only copy of the parameter and refusal lists and mirrors the Jenkinsfile. When the parameters {} block, refuseCocosOnlyParams() or agentLabelForHost() change in the packer: re-sync the data file, run bun scripts/packer-params.cjs --check-drift <PlaybleEngine>/Jenkinsfile/PlayablePacker (exit 4 lists each difference), then re-stamp verifiedAt and “Verified against” below. Tests: bun test scripts/packer-params.test.cjs (set PLAYABLE_ENGINE_DIR to a packer clone to also check it).

Clean and sync -> PlayableLabs builder setup -> Upload Assets* -> Remove Assets* -> Auto-crop modules* -> Build client -> Provision WebP encoder (when PARAM_WEBP) -> Pack all networks -> Netlint* -> Smoke test packed playables* -> Upload every network to R2 -> Publish parameters to PlayableLabs* -> Build Voodoo* -> SuperHtml parity baseline*. * = when-gated (Cocos-only for Upload/Remove/Auto-crop/ parity; Build Voodoo runs on VOODOO for every engine host; param-gated for the rest). post always cleans up and posts to Discord.

  • Build client, Cocos: Creator exit 36 is success (also 0); anything else errors (32 bad params, 34 unexpected); then asserts build/web-mobile exists. Web: buildWebGame() runs the game’s npm clean install and build script in game/ and requires dist/index.html; marker [web-build] npm run build exit 0. Web skips Creator, scene config, engine SHA and Cocos tool path.
  • Pack: the job runs dist/cli.js --build ... --network ... --layout ... under Node; exit 1 over budget (error unless PARAM_FAIL_ON_BUDGET=false, then UNSTABLE), exit 2 usage error. --engine-host is forwarded only for non-Cocos.
  • Smoke: exit 0 pass; 2 or 3 -> UNSTABLE; any other -> error. A failed smoke fails the build, so the R2 stage (a later stage) never runs: no upload on smoke failure. Under PARAM_LAYOUT != flat smoke is skipped as UNSTABLE, never a silent pass.
  • R2 upload: one object per call (folder mode sends an empty tagging header, R2 answers 501), prefix jobs/<JOB_NAME>/<build#>/Build/Client/Cocos/<name>-<ver>-<build#>; skipped on the canary job.
  • Publish: only with PARAM_PLAYABLE_VERSION_ID; id must be a UUID. engineType is sent only for web (WEB); cocos-3.8 -> COCOS and none -> CUSTOM exist in the table but are never sent.
  • Discord: notifyDiscordPacker must never fail the build; every catch calls rethrowIfAborted(err) first.
  • Script globals need @groovy.transform.Field to be read from a top-level def (STAGE_MARKS).
  • Sandbox: JsonOutput.toJson(List) is blacklisted (SECURITY-538) on a from-SCM job; pass a Map or join per-element toJson(Map) (PlaybleEngine .claude/skills/playable-engine/references/jenkinsfile.md gotcha 1; not re-run here).
  • Branch canary: job PackerCanary/PlayablePacker-Canary runs any packer branch via PACKER_REF and never publishes: isBranchCanaryJob() keys on JOB_BASE_NAME == 'PlayablePacker-Canary' and refuses PARAM_PLAYABLE_VERSION_ID, PARAM_UPLOAD_ASSETS, PARAM_REMOVE_ASSETS, VOODOO, skips R2 and Discord; folder-scoped dummy credentials back it up. Never copy the job out of that folder.
  • master is unprotected and Jenkins packs from it: a merge is a production deploy (.claude/skills/playable-engine/SKILL.md Working Rules).
  • Concurrency: disableConcurrentBuilds(abortPrevious: true): the newest build aborts the older.
  • Batch triggers must be serialized. The job is throttled to 1 running build, so queuing N at once makes each newer one abort an older in-flight build (a 16-build batch lost 10 as NOT_BUILT/FAILURE). Trigger the next only after the previous queue item has inQueue=false and an executable.number; bun "$D" trigger-batch --batch-file <json> (t1k-playablelabs-ci-deliver) does this.

PlaybleEngine@3ab658b (master): Jenkinsfile/PlayablePacker, the PARAM_LAZY_ASSETS choice and lazyAssetsArg(); --check-drift clean against that file (38 parameters, 8 Cocos-only refusals; PARAM_PLAYABLELABS_ORG is not one of them). The data file’s verifiedAt carries the same SHA. Earlier, PlaybleEngine@b730306, and PlaybleEngine@98a014f: VOODOO is no longer a refusal, and its own up-front none refusal lives in refuseVoodooMisconfig(), outside the data file. Per-section detail, the live-job caveat and what was not re-read: references/verification-history.md. The web build and pack commands are re-read at PlaybleEngine@2f4443f (buildWebGame() :1926-1939, pack :2848). Not verified: a live web-linux run.

Running scripts/packer-params.cjs (and --check-drift) and reading build status is mechanical; choosing the start scene, networks, or whether a red build is a packer fault is not. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run packer-params.cjs, tabulate params, cleared, warningsthe calling agent itself, or t1k-investigator for a read-only report
Watch a triggered build to a verdict (status only)t1k-ci-watcher
Decide the start scene or networks, or judge a red buildt1k-playablelabs-base-packer-engineer (sonnet, native)