t1k:cocos:base:asset-import
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | medium |
| Tools | — |
Keywords: asset-bundle, asset-import, asset-pipeline, incoming, promote
How to invoke
Section titled “How to invoke”/t1k:cocos:base:asset-importt1k-cocos-base-asset-import
Section titled “t1k-cocos-base-asset-import”The Cocos Creator 3.x side of the asset import pipeline. The process is the same for every engine and lives in
theonekit-gamedev: t1k-gamedev-assets-import-pipeline (module theonekit-gamedev:assets, a dependency of this
module). It owns the triage verdicts (ACCEPTED-CLEAN / ACCEPTED-WITH-WARNING / REJECTED-ERROR), the report-only
default and the --apply gate, the ask step, the two-layer manifest merge, rename suggestions and the report
template. Read it for the workflow; this skill carries only what Cocos adds.
Engine slots (the x-assets capability)
Section titled “Engine slots (the x-assets capability)”gamedev-adapter.json in t1k-cocos-base-gamedev-adapter binds the neutral skill’s Step 0 to these values.
| Slot | Cocos value |
|---|---|
scan / validate / promote | scripts/scan-incoming.cjs, scripts/validate-naming.cjs, scripts/promote-assets.cjs (below) |
kitDefaults | references/default-manifest-schema.md (Cocos prefixes, budgets, folder map) |
incomingRoot | assets/_Incoming/ (override with the project manifest’s incomingRoot) |
sidecar | the .meta file: always co-moved, never regenerated or rewritten |
register | folderMap[targetFolder].bundle names the Asset Bundle; bundle membership is config-driven |
extraChecks | missing-meta, invalid-meta-uuid, invalid-submeta-uuid (references/triage-rules.md) |
applyNeeds | nothing running: promote is a plain shell mv (or git mv for a tracked file) |
Project override: <project-root>/.claude/asset-pipeline.json (references/project-override-pattern.md).
Promote (promote-assets.cjs --apply)
Section titled “Promote (promote-assets.cjs --apply)”- Each accepted file moves as a pair with its
.meta, or not at all: both destinations are checked before either move runs, and a collision on either member aborts the pair withdestination-collisionand exit 1. - The
.metamoves first, then the asset, the only order whose interrupted state a re-run repairs. The reverse would leave a meta-less asset in the live tree, where Cocos assigns it a fresh UUID and breaks every reference. If the asset move fails, the.metamove is rolled back. - If
<src>.metais missing, log a WARNING and skip the meta move; the editor regenerates it on next refresh and the UUID changes, breaking refs. The project owner approves viaAskUserQuestionbefore meta-less files promote. - Idempotent: skip when the destination exists with a matching SHA.
--apply --no-promote-warningsmoves onlyACCEPTED-CLEANfiles.- Every exit path emits the JSON envelope, including an unexpected throw (marked
partial: truewith the operations completed so far).
Cocos-specific rules
Section titled “Cocos-specific rules”- Asset root is
assets/(lowercase). Incoming root:assets/_Incoming/. .metafiles are JSON sidecars. ALWAYS co-move with the asset. NEVER regenerate — UUID changes break every reference in scenes/prefabs.- No MCP — promote uses plain shell
mv(orgit mvif file is tracked). - Asset Bundles replace Addressables.
folderMap[targetFolder].bundlenames the bundle; consumer’s editorcc.AssetManager/ bundle config picks it up. Nomanage_addressablesequivalent — bundle membership is config-driven. - Default prefixes:
T_,S_,M_,SFX_,BGM_,VFX_,SO_,Sh_,Prefab_,Scene_. NoAnim_/Ctrl_/Vcam_(Cocos uses different animation/camera workflows; consumer manifest may add them). - Extension hints:
.scene,.prefab,.effect(shader),.mtl(material),.png/.jpg/.webp(texture),.mp3/.wav(audio),.asset.json(Cocos plugin asset). - Budgets mirror the mobile target. No DOTS-specific constraints.
Scripts
Section titled “Scripts”# Scan only — emits JSON inventorybun scripts/scan-incoming.cjs <project-root>
# Validate against manifest — emits JSON report with triagebun scripts/validate-naming.cjs <project-root>
# Promote (dry-run by default; --apply commits)bun scripts/promote-assets.cjs <project-root>bun scripts/promote-assets.cjs <project-root> --applybun scripts/promote-assets.cjs <project-root> --apply --no-promote-warnings
# Publish gate — blocks a build that still carries an un-reskinned crawled placeholderbun scripts/check-crawled-provenance.cjs <repo> --hashes <crawled-hashes.txt>bun scripts/check-crawled-provenance.cjs <repo> --hashes <crawled-hashes.txt> --build <dir-or-zip>Crawled-asset provenance gate
Section titled “Crawled-asset provenance gate”A crawled itch.io asset (260928-game-data-source flywheel) may enter a PLA repo as an Asset
Slot placeholder via <repo>/provenance/crawled-assets.json (written by the crawler’s gc provenance-export, not by this skill) — but it must never survive un-reskinned into a publish
build. scripts/check-crawled-provenance.cjs gates that: exit 0 clean, exit 1 on any violation
(a crawled file present unchanged, a manifest row deleted/renamed but the bytes still present
anywhere under assets/, a corrupt manifest, or a crawled file surviving into a --build
artifact), exit 2 on a usage error. Full manifest schema, hash-list format, and check-by-check
detail: references/crawled-provenance.md. This script does not run itself — wiring it into a
project’s actual publish step is a separate piece of work this skill does not own (see that
reference’s “Where it runs”).
Executed by
Section titled “Executed by”Scanning and tabulating is mechanical (t1k-list-classifier runs scan-incoming.cjs, validate-naming.cjs and
check-crawled-provenance.cjs report-only); promote-assets.cjs --apply is a write, so it goes to
t1k-cocos-base-developer (t1k-list-classifier has no Edit/Write). Ambiguous renames stay on the reasoning tier.
The neutral skill’s Executed-by table covers the rest.
References
Section titled “References”references/default-manifest-schema.md— full default manifest with Cocos prefixes and budgetsreferences/triage-rules.md— Cocos reason codes and thresholds on top of the neutral triage treereferences/project-override-pattern.md— how project.claude/asset-pipeline.jsonoverrides kit defaults, and whatvalidate-naming.cjsrefuses to gradereferences/asset-slot-handoff.md— Asset Slot handoff mechanics: the UUID-identity load-bearing fact,.metadiscipline, compressed-UUID scene/prefab diffs, Asset Bundle folder-keying, and the Cocos-side acceptance checklist for a vendor/outsourced asset deliveryreferences/crawled-provenance.md— crawled-asset provenance manifest schema, the hash-list format, andcheck-crawled-provenance.cjs’s four checks (a)-(d)references/meta-pairing-gate.md—check-meta-pairing.cjs: fails a change whose asset/.ts/folder lacks its.meta, a.metadeleted under a kept asset, or an image.metawith non-fixed subMeta ids (6c48a/f9941); how to wire it as pre-commit and CIreferences/audio-container-registration.md— audio clip naming, import,AudioContainer.audioListregistration and the optional MP3 encode (scripts/encode_mp3.py)
Hard rules
Section titled “Hard rules”-
Commit every asset with its
.metain the SAME commit, and never hand-write a PNG.meta’s subMeta ids. Enforced byscripts/check-meta-pairing.cjs --staged(pre-commit) /--range(CI); seereferences/meta-pairing-gate.md. -
NEVER regenerate
.meta. Cocos UUIDs live in.meta; regenerating breaks every reference. If a.metais missing, promoting forces the editor to regenerate on next refresh → UUID changes → broken refs in scenes/prefabs/components. Always co-move or skip. -
Atlas textures count under
texture.atlasbudget, nottexture. Project manifest must declare which textures are atlas pages via a label or folder convention (art/2d/atlases/). -
assets/_Incoming/is scratch space — never check it into the Cocos build’s Asset Bundle config. Promoted files inherit theirtargetFolder’s bundle. -
Audio formats (
.mp3,.wav) triggeraudio.sfxoraudio.bgmbased on prefix, not extension.BGM_*.mp3→audio.bgm;SFX_*.mp3→audio.sfx. -
Shell
mvvsgit mv: if the source file is git-tracked (rare for incoming raw assets, but possible), usegit mvto preserve history.promote-assets.cjsdetects this automatically. -
Folder-mirrored staging is NOT supported —
targetFolderresolves from the filename STEM alone, never the incoming subfolder.validate-naming.cjsstrips the path topath.basename(file.path)before matching a prefix, andpromote-assets.cjswrites the destination aspath.posix.join('assets', f.targetFolder, path.basename(f.path))— basename only, both ends. So staging the same stem under two different subfolders (a convention where the destination is implied by_Incoming/<assets-relative-target-path>/file.ext) makes both files resolve to the SAME destination; the second eitherskip-idempotents (if byte-identical to the first) or harddestination-collisions (promote-assets.cjsexit 1) — and if the collision happens to be a.gltf/.binpair with a byte-identical sibling texture, the loser can promote as a silently textureless mesh (no promote-time error at all). Workaround: rename the colliding stem before staging and give it its ownprefixesentry (e.g.enviroment.gltf→enviroment_ice.gltf+ a matchingbuffers[0].uriedit inside the renamed json), or stage the colliding copy under_overwrite/(already excluded from promotion) and place it by hand. A project whose staging convention is genuinely folder-mirrored needs a directory-mirror-move tool instead of this pipeline’s prefix-lookup resolver — promoting by relative directory path rather than by stem. -
scan-incoming.cjsignores the manifest’sincomingRoot. It hardcodes'assets/_Incoming'as its default and only overrides via the--incoming-rootCLI flag — unlikevalidate-naming.cjs, which DOES readincomingRootfrom.claude/asset-pipeline.json. A project that sets a customincomingRootin its manifest but doesn’t also pass--incoming-rooton thescan-incoming.cjsinvocation gets silently scanned at the wrong path. -
Cocos 3.8.7 cannot import
EXT_meshopt_compressionglTFs — and fails in a way that reads as a Cocos bug, not a format problem. Compressed playable-ad models (anything run throughgltfpack, which is the common pipeline) fail with:RangeError: Offset is outside the bounds of the DataViewat GltfConverter._readAccessor (gltf-converter.ccc)The log warns
Unsupported glTF extension: EXT_meshopt_compression/KHR_mesh_quantization, then the.metalandsimported: falsewith zero subMetas — no mesh, no material, no prefab, and the asset renders nothing. Two traps make this expensive to diagnose:manage_asset action=reimportreturns{"success":true,"message":"Asset reimported successfully"}while the asset stays dead. Never trust that response — verify from the.metaimportedflag plus a non-emptysubMetascontaininggltf-mesh.- The
RangeErrornames neither meshopt nor quantization, so it points at the decompressor rather than the real cause.
Fix:
bunx @gltf-transform/cli@4.5.0 dequantize <in.gltf> <out.gltf>(writes<out>.binalongside; copy both back in place, keeping.metafiles intact), then refresh. ConfirmextensionsRequiredis empty before reimport. Verified: 5/5 models went fromimported: false/ 0 meshes toimported: truewith full meshes, materials and prefabs. -
Check
extensionsRequiredbefore promoting any glTF. A model can importimported: trueyet still be wrong, so gate on the extension list:EXT_meshopt_compressionandKHR_mesh_quantizationinextensionsRequiredare the two known Cocos-3.8.7 blockers.KHR_materials_specularonly warns (cosmetic) and is safe. -
meshCompress.quantizeON garbles a GLB’s second UV set (TEXCOORD_1/a_texCoord1) when the engine dequantizes the mesh at load — keep it OFF on any GLB whose shader reads a second UV set. Measured (3.8.7, CookingCozy3DPLA): a GLB carrying per-vertex light flags inTEXCOORD_1held(1, 0)but the shader read(8.28, 1.59), so lit walls burnt white and dough balls went near black. The import succeeds, the primary UV and the normals look correct, and nothing flags it, so it reads as a lighting or shader bug. A GLB with noTEXCOORD_1but withCOLOR_0(normalized u8 VEC4) imported with quantize on keptCOLOR_0intact, so the damage is specific to the second UV stream, not to vertex attributes in general. Fix: setmeshCompress.quantize: falsein the model’s.metauserData(patch viaJSON.parse/JSON.stringify, then reimport and re-read the.metafrom disk). Verify by sampling the attribute in the running preview (a debug shader output or a read of the uploaded vertex buffer), never by the import succeeding. Promotion-time gate: flag a glTF/GLB with aTEXCOORD_1accessor that is about to import with quantize on. -
A shared material’s
USE_VERTEX_COLORdefine is flipped ON by ANY primitive that carriesCOLOR_0, not per-primitive — a sibling mesh with noCOLOR_0sharing that material samples black and renders pitch black, with no import error. Measured (3.8.7,character.glb): five tier meshes sharedAtlasMat/StickmanMat. Only one of the five had aCOLOR_0stream, and it was all-white(1,1,1,1)— carrying zero visual information — but its mere presence was enough to set_defines[0].USE_VERTEX_COLOR: trueon both materials at build time. The four meshes with noCOLOR_0then sampled black vertex color and rendered pitch black. This stays hidden as long as every mesh sharing the material is drawn at once (the black draws sit under the others), and only surfaces once fewer of them are active — read as “this one tier went invisible” rather than a material defect. Check: read the built material JSON atlibrary/<uuid[0:2]>/<uuid>@<id>.jsonfor_defines[0].USE_VERTEX_COLOR. Fix: strip the all-whiteCOLOR_0attribute before import (lossless — it carries no color information the mesh needs), or give every primitive sharing the material a matching all-whiteCOLOR_0. Promotion-time gate: flag a glTF/GLB whose primitives disagree onCOLOR_0presence when two or more of them reference the SAME material.three.js’s ownGLTFLoadersetsvertexColorsper-primitive, so a reference playable built on three.js can render this exact asset correctly while the Cocos port of the same file renders black — the divergence is real, not a porting mistake. -
Every glTF/FBX animation clip imports with
wrapMode: 2(Loop) — the Cocos importer has no source “loop” flag to read, so a death/one-shot clip replays forever unless corrected after import. Fix in the model’s.meta, in BOTH places:subMetas[<clip-id>].userData.wrapModefor the clip’s own sub-asset, ANDuserData.animationImportSettings[].splits[].wrapMode— set each to1(Normal)..metafiles are CRLF on Windows; patch viaJSON.parse/re-JSON.stringify, never a string/regex anchor on the raw text, or the line endings corrupt. Reimport, then re-read the.metaback from disk — the editor’s own reimport pass can rewrite it and silently restorewrapMode: 2, so a write that isn’t verified this way is not verified at all. When porting from a reference asset, the source DCC’s own import metadata is often the citable authority for correct intent: Unity’s importer meta for the reference’sStickman@Death.fbxcarriedloopTime: 0(andloopTime: 1forStickman@Idle.fbx) — glTF has no equivalent field, which is exactly why the Cocos importer cannot infer it and always guesses Loop. -
Copying a material from another project: resolve its
_effectAssetuuid first — a non-builtin effect whose.effectyou did NOT copy reverts the material to default at runtime (404 on the effect’s import json), and “uuid not found in source assets” is NOT proof the uuid is builtin. A material (.mtl, or a.glbwith embedded materials) stores its shader as a bare_effectAsset.__uuid__reference — no effect body. Copy the.mtl/.glbalone and the uuid points at nothing resolvable in the target. A uuid whose effect is an engine builtin resolves regardless (builtins are registered by uuid in the engine), so the material looks fine — which is exactly why a non-builtin copy is easy to ship broken: the failure surfaces only at runtime as a 404 on the effect’s import json, with the material silently falling back to default. Resolve every_effectAssetuuid before importing. If it is not a builtin, i.e. it resolves to a project.effect(a common case: abuiltin-standardcopy carrying brightness/saturation/contrast tweaks), copy that.effecttogether with its.meta, byte-for-byte, so the uuid survives — same UUID-identity contract the rest of this pipeline enforces for assets (references/asset-slot-handoff.md), applied to the shader. “uuid not found in the source project’s assets” does NOT mean builtin — that check only searchedassets/, and a builtin is in the engine, not inassets/. Grep the source project’s.metafiles for the uuid to settle it: a hit = a project asset you must copy; no hit anywhere = a real builtin. Evidence: FairShotPLAPlus.effectc9baf904-eb08-4307-af41-e0b5356a9878, abuiltin-standardcopy. -
APK port: import is not wiring. Every original asset imported must also be referenced by a prefab slot or loader; an unwired list that is not empty fails the port. After deleting an asset, a grep must cover the full uuid, the COMPRESSED uuid, the path and the file name, then purge it from the pod guest AND its build copy (
t1k-cocos-base-apk-portreferences/speed-and-pod.md).