t1k:cocos:playable:studio-engine
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: built-in engine, cocos-engine, custom engine, engine customization, engine manager, engine provenance, engine sha, param_engine_sha, patches.md, studio engine, use custom engine
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:studio-engineCocos Playable — Studio Engine Install & Use
Section titled “Cocos Playable — Studio Engine Install & Use”Point a Cocos Creator 3.8.7 build at the studio engine fork
(The1Studio/cocos-engine, branch studio/3.8.7) instead of the engine the editor
ships, and prove the built artefact came from that source rather than assuming it.
Covers three engines and the install path for each, the provenance check, the revert,
and when a fork patch is even allowed.
Does NOT own: which engine modules are cropped (t1k-cocos-playable-build-size),
Cocos MCP behaviour (t1k-cocos-playable-tooling-gotchas), or Jenkins job/Plane setup
(t1k-cocos-playable-pipeline).
Which engine is this build actually running?
Section titled “Which engine is this build actually running?”Three engines can be in play, and the answer is a measurement, not an inference — two of them produce a byte-identical-looking build until the marker is checked:
| Engine | How the build gets it | Landed by |
|---|---|---|
| Stock — the editor’s bundled engine | Nothing. This is the default for every build to date | — |
| Studio — a Creator copy whose built-in engine dir is a git overlay of the fork | A separate Creator install, named by a Jenkins tool | Path A |
| Pinned checkout — a cocos-engine commit fetched and prepared per run | The --engine flag on the build command | Path B |
The live mechanism is Path A — a dedicated Creator copy on the agent. Path B still exists in the Jenkinsfile but the current plan does not use it, and on 3.8.7 it is a dead end (see Path B). A developer’s own machine uses Path C.
Before telling anyone to build against the studio engine, ask which of the three they mean. They are not interchangeable: A and C select an engine for every build that editor/tool serves, B selects one for one run.
Path A — the studio Creator copy (the live mechanism)
Section titled “Path A — the studio Creator copy (the live mechanism)”The mechanism is a second Creator install whose own built-in engine directory has been
replaced by a git overlay of The1Studio/cocos-engine branch studio/3.8.7:
C:\cocos-studio\Creator\3.8.7-studio\ ← the studio Creator copy resources\resources\3d\engine\ ← the overlay; this is what compilesRegistered on Jenkins as the Custom Tool Cocos 3.8.7 studio, so a build selects it by
setting PARAM_COCOS_TOOL_NAME — no --engine, no PARAM_ENGINE_SHA:
PARAM_COCOS_TOOL_NAME = Cocos 3.8.7 studioPARAM_ENGINE_SHA = <empty>Why a whole separate install rather than a preference flip: Creator’s engine-path preference is a global setting for that Creator version, so switching the stock install’s engine would repoint every project on it at once. A separate install keeps the two engines side-by-side and makes the choice per-build.
The Jenkinsfile refuses to fall back when a tool name contains studio — a misspelled
Cocos 3.8.7 studio fails the build instead of silently building on stock. Read the
resolution and refusal rules before changing a tool name:
references/jenkins-engine-selection.md.
Verify the build used it (the Cocos Creator at: line names the resolved editor):
Cocos Creator at: C:\cocos-studio\Creator\3.8.7-studio\Then confirm the marker, below — the path proves which editor ran, the marker proves which engine source compiled.
Path B — a per-run checkout: PARAM_ENGINE_SHA (kept, not used by the current plan)
Section titled “Path B — a per-run checkout: PARAM_ENGINE_SHA (kept, not used by the current plan)”PARAM_ENGINE_SHA accepts exactly three shapes (resolvedEngineSha()):
| Value | Meaning |
|---|---|
| empty (default) | The editor-bundled stock engine — every build to date |
pinned | The sha field in engine/studio-pin.json |
| a full 40-hex SHA | That commit of The1Studio/cocos-engine |
Any non-empty value fetches that commit, prepares it once per SHA under
C:/cocos-engines/<sha> (shallow fetch → populate native/external → bun install --frozen-lockfile →
build:declaration + build:adapter → a .ready-v2 marker), passes it via --engine for
that run only, and records the SHA in pack-report.json.
Three facts that decide whether this is the right lever:
pinnedis NOT the studio engine.engine/studio-pin.json’sshais6a204c1b…— the upstream tag commit the branch is pinned to.studio/3.8.7’s head is two commits ahead of it (471241d38a→bd524c27e1). Sopinnedbuilds the upstream tag: it carries neither the Creator WebGL delta nor the provenance marker. Pin the branch head explicitly if you want the studio source.--enginedoes not work on 3.8.7. Builds #34/#36/#41 exited-1in ~0.35 s with no output. The root cause recorded inplans/engine-module-crop-3.8.7.md(F2 — the flag is parsed only by the bundled effect-compiler, not the launcher) is marked UNVERIFIED there; the-1is measured. Do not plan around--engineon 3.8.7.bun install --frozen-lockfile, neverbun install, for the checkout. The repo’s own build is not a lockfile install and floats.
Full parameter semantics, the preparation steps, and PARAM_ENGINE_DIR_DIAG:
references/jenkins-engine-selection.md.
Path C — a developer’s machine: Creator’s Engine Manager
Section titled “Path C — a developer’s machine: Creator’s Engine Manager”To make your Creator 3.8.7 compile a local checkout of the fork, point it at the engine source root:
File -> Preferences -> Engine Manager → the default is Use Built-in → switch to the
Use Custom tab → set the engine source code root directory.
Then:
- Check
Use CustomunderNative Moduletoo if the build needs native functionality — that covers thenative/side, whose path is auto-detected from the engine root. - Restart the editor — or click Relaunch on the panel. The change does not take effect without it.
- The engine-path setting is global to that Creator version, not per project. Use the storage-location control to scope it if you run several projects.
- For TS/web changes, run Developer -> Compile the Engine, which writes a
bin/folder under the engine directory. A first simulator launch may also need Developer -> Rebuild Native Simulator Engine.
Revert: return to Engine Manager, select Use Built-in, and relaunch.
Exact wording, the global-config warning, and the scene-editor side effect:
references/creator-engine-manager.md (Cocos Creator 3.8 manual, retrieved 2026-09-26).
⚠️ On the Jenkins agent, do not open this preference on the stock install — and never on the
3.8.7-studio copy. The agent’s engines are selected by tool, never by preference. A
preference flip there is machine-global and would repoint the stock install at the studio
overlay.
Provenance — proving a build came from the studio engine
Section titled “Provenance — proving a build came from the studio engine”The fork carries a behaviour-free marker, assigned next to the existing engine-version
assignment in cocos/core/global-exports.ts:
const studioEngineBuild = 'studio-3.8.7-1';_global.STUDIO_ENGINE_BUILD = legacyCC.STUDIO_ENGINE_BUILD = studioEngineBuild;export { studioEngineBuild as STUDIO_ENGINE_BUILD };It ships in every web-mobile build: the file is reached via exports/base.ts, and base
is the one feature in cc.config.json with no dependentModules gate and no opt-out, so
includeModules cannot crop it.
Three independent checks, cheapest first — run at least the first two:
| Check | What it proves |
|---|---|
PowerShell Select-String -Path <build-output>\cocos-js\*.js -Pattern 'studio-3.8.7-1' | The engine source that compiled was the fork. Not a bare find/findstr scan |
The build log’s Cocos Creator at: line | Which editor ran — the studio copy’s path |
pack-report.json → engine (ref/custom/source), engine.checkout, engine.classBreakdown | Which engine the packer was told about |
The marker is absent at the pinned upstream SHA 6a204c1b (verified — grepped, zero
matches), which is exactly what makes it discriminating: a build with no marker is stock, and
that is a real answer, not a missing one. Commands, the report fields, and how to read a
negative result: references/provenance-verification.md.
Reverting to the built-in engine
Section titled “Reverting to the built-in engine”| Engine | Revert |
|---|---|
| Path A (studio copy) | Set PARAM_COCOS_TOOL_NAME back to Cocos 3.8.7. The copy stays on disk, unused |
| Path B (per-run checkout) | Clear PARAM_ENGINE_SHA. Nothing else is touched — no editor preference was ever changed |
| Path C (Engine Manager) | Select Use Built-in in Engine Manager and relaunch |
Keep the fork minimal
Section titled “Keep the fork minimal”A studio engine patch is the last resort, not the first tool. When a playable need looks like it needs an engine change, walk this order and stop at the first rung that works:
- Creator’s per-project module switches / build config (
settings/v2/packages/engine.jsonincludeModules+cache._value) — seet1k-cocos-playable-build-size - Packer runtime/adapter code in the packer repo
- A minimal, isolated patch on
studio/3.8.7, recorded in the fork’sPATCHES.md
Never refactor engine code. If you believe only rung 3 works, stop and report rather than patching. Every patch costs a rebase on every version bump, forever.
The fork must stay accountable: a patch with no PATCHES.md row is a bug, not a feature.
Branch and patch inventory, the PATCHES.md row format, and the upstream-watcher files:
references/fork-and-patches.md.
Executed by
Section titled “Executed by”The checks below are read-only aggregation against fixed evidence (a grep result, a log line, a JSON field), which is mechanical; every install or revert decision is a blast-radius change (a fleet-wide editor selection) and stays on a reasoning tier:
| Step | Agent |
|---|---|
Grep a build output for the marker; read pack-report.json’s engine fields and tabulate what each check proved | t1k-metrics-reporter |
Read a Jenkins build log for the Cocos Creator at: line and report which editor resolved | t1k-metrics-reporter |
| Judge WHICH engine path applies (A / B / C), or whether a need justifies a fork patch | stays on a reasoning tier — three engines, and the wrong pick is a fleet-wide change |
Change PARAM_COCOS_TOOL_NAME, register a Jenkins tool, install a Creator copy, or edit PATCHES.md | stays on a write-capable, reasoning tier — never cheap tier |
t1k-metrics-reporter has no Edit/Write tool, which matches these steps’ read-only shape.
Hard rules
Section titled “Hard rules”| # | Symptom | Cause | Fix |
|---|---|---|---|
| 1 | Build looks identical to stock, marker absent | PARAM_ENGINE_SHA=pinned resolves the upstream tag commit, not the studio head | Pin the branch head, or use Path A |
| 2 | CocosCreator.exe exits -1 in ~0.35 s, no output | --engine on 3.8.7 (Path B) | Do not use --engine on 3.8.7 — use Path A |
| 3 | Build fails instead of falling back to stock | Tool name contains studio and the tool is missing | Register the tool, or fix the name — the refusal is deliberate |
| 4 | Engine-manager change appears to do nothing | Editor not restarted | Relaunch the editor; the preference applies on next launch |
| 5 | A project you did not touch changed engines | Engine Manager is a global preference for that Creator version | Use a separate Creator install (Path A), never a preference flip on the agent |
| 6 | bun install --frozen-lockfile fails in a prepared checkout | bun install was used and the tree floated | Use bun install --frozen-lockfile; the checkout is prepared once per SHA and cached |
| 7 | Marker found in a dist/ you did not just build | A stale build output | Rebuild before verifying; state the commit the output came from |
Related
Section titled “Related”t1k-cocos-playable-build-size— engine module cropping, which needs no engine at all and is the supported first lever before any fork patcht1k-cocos-playable-tooling-gotchas— Cocos MCP and editor-tool failure modest1k-cocos-playable-pipeline— binding a playable to its Jenkins job and Plane module