Skip to content

t1k:cocos:playable:studio-engine

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
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

/t1k:cocos:playable:studio-engine

Cocos 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:

EngineHow the build gets itLanded by
Stock — the editor’s bundled engineNothing. This is the default for every build to date—
Studio — a Creator copy whose built-in engine dir is a git overlay of the forkA separate Creator install, named by a Jenkins toolPath A
Pinned checkout — a cocos-engine commit fetched and prepared per runThe --engine flag on the build commandPath 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 compiles

Registered 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 studio
PARAM_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()):

ValueMeaning
empty (default)The editor-bundled stock engine — every build to date
pinnedThe sha field in engine/studio-pin.json
a full 40-hex SHAThat 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:

  1. pinned is NOT the studio engine. engine/studio-pin.json’s sha is 6a204c1b… — the upstream tag commit the branch is pinned to. studio/3.8.7’s head is two commits ahead of it (471241d38a → bd524c27e1). So pinned builds 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.
  2. --engine does not work on 3.8.7. Builds #34/#36/#41 exited -1 in ~0.35 s with no output. The root cause recorded in plans/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 -1 is measured. Do not plan around --engine on 3.8.7.
  3. bun install --frozen-lockfile, never bun 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 Custom under Native Module too if the build needs native functionality — that covers the native/ 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:

CheckWhat 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: lineWhich editor ran — the studio copy’s path
pack-report.json → engine (ref/custom/source), engine.checkout, engine.classBreakdownWhich 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.

EngineRevert
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

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:

  1. Creator’s per-project module switches / build config (settings/v2/packages/engine.json includeModules + cache._value) — see t1k-cocos-playable-build-size
  2. Packer runtime/adapter code in the packer repo
  3. A minimal, isolated patch on studio/3.8.7, recorded in the fork’s PATCHES.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.

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:

StepAgent
Grep a build output for the marker; read pack-report.json’s engine fields and tabulate what each check provedt1k-metrics-reporter
Read a Jenkins build log for the Cocos Creator at: line and report which editor resolvedt1k-metrics-reporter
Judge WHICH engine path applies (A / B / C), or whether a need justifies a fork patchstays 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.mdstays on a write-capable, reasoning tier — never cheap tier

t1k-metrics-reporter has no Edit/Write tool, which matches these steps’ read-only shape.

#SymptomCauseFix
1Build looks identical to stock, marker absentPARAM_ENGINE_SHA=pinned resolves the upstream tag commit, not the studio headPin the branch head, or use Path A
2CocosCreator.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
3Build fails instead of falling back to stockTool name contains studio and the tool is missingRegister the tool, or fix the name — the refusal is deliberate
4Engine-manager change appears to do nothingEditor not restartedRelaunch the editor; the preference applies on next launch
5A project you did not touch changed enginesEngine Manager is a global preference for that Creator versionUse a separate Creator install (Path A), never a preference flip on the agent
6bun install --frozen-lockfile fails in a prepared checkoutbun install was used and the tree floatedUse bun install --frozen-lockfile; the checkout is prepared once per SHA and cached
7Marker found in a dist/ you did not just buildA stale build outputRebuild before verifying; state the commit the output came from
  • t1k-cocos-playable-build-size — engine module cropping, which needs no engine at all and is the supported first lever before any fork patch
  • t1k-cocos-playable-tooling-gotchas — Cocos MCP and editor-tool failure modes
  • t1k-cocos-playable-pipeline — binding a playable to its Jenkins job and Plane module