t1k:playablelabs:ci:jenkins
| Field | Value |
|---|---|
| Module | ci |
| Version | 1.17.3 |
| Effort | medium |
| Tools | — |
Keywords: packer jenkins pipeline, PlayablePacker, PlayablePacker Jenkinsfile
How to invoke
Section titled “How to invoke”/t1k:playablelabs:ci:jenkins[parameter | stage | gotcha]PlayablePacker Jenkins pipeline
Section titled “PlayablePacker Jenkins pipeline”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 and why
Section titled “Agent and why”agent { label agentLabelForHost(params.PARAM_ENGINE_HOST) } (Jenkinsfile agentLabelForHost()):
- Cocos (
cocos-3.8) always runs on the Windowscocosagent. Creator is Windows-only here and its steps run through git-bash.PARAM_AGENT_LABEL=web-linuxon a Cocos build is refused with an error (refuseWebLinuxOnCocos()), never silently ignored. - Web and none run on the Linux
web-linuxagents whenPARAM_AGENT_LABEL=web-linux(opt-in; choicesauto-cocos|web-linux). Left atauto-cocosthey still map tococos. 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 anode:22-bookwormcontainer (workspace mounted), the smoke stage in the pinned Playwright image (Chromium included), andprovisionWebpUnix()installs a pinned libwebp 1.6.0cwebpchecked by sha256.onWebLinux()is true only for a non-Cocos build whoseNODE_LABELScontainweb-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.npmrcafterwards; 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)”| Param | Default | Meaning |
|---|---|---|
PARAM_GAME_REPO / PARAM_GAME_BRANCH | '' (required) / develop | SSH URL + branch of the game; cloned to game/ |
PARAM_BUILD_FILE_NAME, PARAM_BUILD_VERSION | '', 1.0.0 | playable name, version |
PARAM_ENGINE_HOST | choice cocos-3.8 (first), none, web | cocos-3.8 Creator build; web npm build into dist/; none pre-built dist/ |
PARAM_NETWORKS | all | comma list or all |
PARAM_DEFLATE, PARAM_WEBP | true, true | forwarded as --deflate, --webp |
PARAM_OPTIMIZE | choice off (first), lossless, all | opt-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_ASSETS | choice auto (first), off, all | web 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_LAYOUT | flat | superhtml changes EVERY R2 path; smoke/netlint read flat only |
PARAM_FAIL_ON_BUDGET | true | red build when a network is over its ceiling |
PARAM_SMOKE | false | run scripts/smoke.cjs stage |
PARAM_CANARY | false | M3 runtime canary; needs PARAM_SMOKE (else UNSTABLE) |
PARAM_NETLINT | false | static per-network validator stage |
PARAM_PLAYABLE_VERSION_ID | '' | UUID; empty skips the Publish stage |
PARAM_PLAYABLELABS_ORG | default | string, 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_ASSETS | false / false | Cocos only; Remove needs Upload |
PARAM_ENGINE_SHA | '' | '', pinned, or 40-hex cocos-engine SHA (Cocos only) |
PARAM_AGENT_LABEL | choice auto-cocos (first), web-linux | web-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_ID | 1551151691749920860 | Discord 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.
Set up a build by engine
Section titled “Set up a build by engine”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:
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:
| Engine | Signal | PARAM_ENGINE_HOST / PARAM_AGENT_LABEL |
|---|---|---|
| Cocos Creator | assets/ + 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 |
| web | package.json scripts.build, no Creator markers (the job installs and builds it with npm in buildWebGame() and needs dist/index.html) | web / web-linux |
| prebuilt | dist/index.html, no build script | none / 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:
- 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.jsonmust be on that commit. Build the game locally sodist/exists, then runbun "<web-lazy-load skill dir>/scripts/gen-playable-lazy.cjs" --build <dist> --out public/playable-lazy.json(or--checkwhen 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_ASSETSkeeps its job defaultauto; the script does not set it. - Run the script; show the user
paramsandwarnings; resolve what the warnings name (PARAM_START_SCENE, a non-SSH repo URL, the proposedPARAM_BUILD_FILE_NAME). - Trigger with the Jenkins MCP
triggerBuildonCocosPlayableLabs/PlayablePacker, passingparamsas-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. - Resolve YOUR build — never by
lastBuild. Another team’s build on the shared job can start first and take the next number, and “the firstlastBuildgreater than the previous” then reports their result as yours.- Take the queue item
triggerBuildreturns (getQueueItem); if the tool omits the id, read it from the responseLocationheader (or thegetQueuelist). Poll it untilexecutable.numberappears — that number is your build. - Second check, before you wait or report: read the build’s
ParametersActionand assertPARAM_GAME_REPO,PARAM_GAME_BRANCHandPARAM_DISCORD_THREAD_IDare 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
lastBuildalone. - 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.
- Take the queue item
- Watch with
getBuild(andgetBuildLogon 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. Onweb-linuxthe log also carriesweb-linux:echoes from the Chromium and cwebp steps. - 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).
Stages, in file order
Section titled “Stages, in file order”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
(
32bad params,34unexpected); then assertsbuild/web-mobileexists. Web:buildWebGame()runs the game’s npm clean install andbuildscript ingame/and requiresdist/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 unlessPARAM_FAIL_ON_BUDGET=false, then UNSTABLE), exit 2 usage error.--engine-hostis 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 != flatsmoke 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.engineTypeis sent only forweb(WEB);cocos-3.8->COCOSandnone->CUSTOMexist in the table but are never sent. - Discord:
notifyDiscordPackermust never fail the build; everycatchcallsrethrowIfAborted(err)first.
Hard rules
Section titled “Hard rules”- Script globals need
@groovy.transform.Fieldto be read from a top-leveldef(STAGE_MARKS). - Sandbox:
JsonOutput.toJson(List)is blacklisted (SECURITY-538) on a from-SCM job; pass a Map or join per-elementtoJson(Map)(PlaybleEngine.claude/skills/playable-engine/references/jenkinsfile.mdgotcha 1; not re-run here). - Branch canary: job
PackerCanary/PlayablePacker-Canaryruns any packer branch viaPACKER_REFand never publishes:isBranchCanaryJob()keys onJOB_BASE_NAME == 'PlayablePacker-Canary'and refusesPARAM_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. masteris unprotected and Jenkins packs from it: a merge is a production deploy (.claude/skills/playable-engine/SKILL.mdWorking 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 hasinQueue=falseand anexecutable.number;bun "$D" trigger-batch --batch-file <json>(t1k-playablelabs-ci-deliver) does this.
Verified against
Section titled “Verified against”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.
Executed by
Section titled “Executed by”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”.
| Step | Agent |
|---|---|
Run packer-params.cjs, tabulate params, cleared, warnings | the 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 build | t1k-playablelabs-base-packer-engineer (sonnet, native) |