Skip to content

t1k:cocos:base:asset-import

FieldValue
Modulebase
Version4.51.9
Effortmedium
Tools—

Keywords: asset-bundle, asset-import, asset-pipeline, incoming, promote

/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.

gamedev-adapter.json in t1k-cocos-base-gamedev-adapter binds the neutral skill’s Step 0 to these values.

SlotCocos value
scan / validate / promotescripts/scan-incoming.cjs, scripts/validate-naming.cjs, scripts/promote-assets.cjs (below)
kitDefaultsreferences/default-manifest-schema.md (Cocos prefixes, budgets, folder map)
incomingRootassets/_Incoming/ (override with the project manifest’s incomingRoot)
sidecarthe .meta file: always co-moved, never regenerated or rewritten
registerfolderMap[targetFolder].bundle names the Asset Bundle; bundle membership is config-driven
extraChecksmissing-meta, invalid-meta-uuid, invalid-submeta-uuid (references/triage-rules.md)
applyNeedsnothing 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).

  • 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 with destination-collision and exit 1.
  • The .meta moves 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 .meta move is rolled back.
  • If <src>.meta is 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 via AskUserQuestion before meta-less files promote.
  • Idempotent: skip when the destination exists with a matching SHA.
  • --apply --no-promote-warnings moves only ACCEPTED-CLEAN files.
  • Every exit path emits the JSON envelope, including an unexpected throw (marked partial: true with the operations completed so far).
  1. Asset root is assets/ (lowercase). Incoming root: assets/_Incoming/.
  2. .meta files are JSON sidecars. ALWAYS co-move with the asset. NEVER regenerate — UUID changes break every reference in scenes/prefabs.
  3. No MCP — promote uses plain shell mv (or git mv if file is tracked).
  4. Asset Bundles replace Addressables. folderMap[targetFolder].bundle names the bundle; consumer’s editor cc.AssetManager / bundle config picks it up. No manage_addressables equivalent — bundle membership is config-driven.
  5. Default prefixes: T_, S_, M_, SFX_, BGM_, VFX_, SO_, Sh_, Prefab_, Scene_. No Anim_ / Ctrl_ / Vcam_ (Cocos uses different animation/camera workflows; consumer manifest may add them).
  6. Extension hints: .scene, .prefab, .effect (shader), .mtl (material), .png/.jpg/.webp (texture), .mp3/.wav (audio), .asset.json (Cocos plugin asset).
  7. Budgets mirror the mobile target. No DOTS-specific constraints.
Terminal window
# Scan only — emits JSON inventory
bun scripts/scan-incoming.cjs <project-root>
# Validate against manifest — emits JSON report with triage
bun 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> --apply
bun scripts/promote-assets.cjs <project-root> --apply --no-promote-warnings
# Publish gate — blocks a build that still carries an un-reskinned crawled placeholder
bun 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>

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”).

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/default-manifest-schema.md — full default manifest with Cocos prefixes and budgets
  • references/triage-rules.md — Cocos reason codes and thresholds on top of the neutral triage tree
  • references/project-override-pattern.md — how project .claude/asset-pipeline.json overrides kit defaults, and what validate-naming.cjs refuses to grade
  • references/asset-slot-handoff.md — Asset Slot handoff mechanics: the UUID-identity load-bearing fact, .meta discipline, compressed-UUID scene/prefab diffs, Asset Bundle folder-keying, and the Cocos-side acceptance checklist for a vendor/outsourced asset delivery
  • references/crawled-provenance.md — crawled-asset provenance manifest schema, the hash-list format, and check-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 .meta deleted under a kept asset, or an image .meta with non-fixed subMeta ids (6c48a/f9941); how to wire it as pre-commit and CI
  • references/audio-container-registration.md — audio clip naming, import, AudioContainer.audioList registration and the optional MP3 encode (scripts/encode_mp3.py)
  • Commit every asset with its .meta in the SAME commit, and never hand-write a PNG .meta’s subMeta ids. Enforced by scripts/check-meta-pairing.cjs --staged (pre-commit) / --range (CI); see references/meta-pairing-gate.md.

  • NEVER regenerate .meta. Cocos UUIDs live in .meta; regenerating breaks every reference. If a .meta is 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.atlas budget, not texture. 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 their targetFolder’s bundle.

  • Audio formats (.mp3, .wav) trigger audio.sfx or audio.bgm based on prefix, not extension. BGM_*.mp3 → audio.bgm; SFX_*.mp3 → audio.sfx.

  • Shell mv vs git mv: if the source file is git-tracked (rare for incoming raw assets, but possible), use git mv to preserve history. promote-assets.cjs detects this automatically.

  • Folder-mirrored staging is NOT supported — targetFolder resolves from the filename STEM alone, never the incoming subfolder. validate-naming.cjs strips the path to path.basename(file.path) before matching a prefix, and promote-assets.cjs writes the destination as path.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 either skip-idempotents (if byte-identical to the first) or hard destination-collisions (promote-assets.cjs exit 1) — and if the collision happens to be a .gltf/.bin pair 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 own prefixes entry (e.g. enviroment.gltf → enviroment_ice.gltf + a matching buffers[0].uri edit 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.cjs ignores the manifest’s incomingRoot. It hardcodes 'assets/_Incoming' as its default and only overrides via the --incoming-root CLI flag — unlike validate-naming.cjs, which DOES read incomingRoot from .claude/asset-pipeline.json. A project that sets a custom incomingRoot in its manifest but doesn’t also pass --incoming-root on the scan-incoming.cjs invocation gets silently scanned at the wrong path.

  • Cocos 3.8.7 cannot import EXT_meshopt_compression glTFs — and fails in a way that reads as a Cocos bug, not a format problem. Compressed playable-ad models (anything run through gltfpack, which is the common pipeline) fail with:

    RangeError: Offset is outside the bounds of the DataView
    at GltfConverter._readAccessor (gltf-converter.ccc)

    The log warns Unsupported glTF extension: EXT_meshopt_compression / KHR_mesh_quantization, then the .meta lands imported: false with zero subMetas — no mesh, no material, no prefab, and the asset renders nothing. Two traps make this expensive to diagnose:

    1. manage_asset action=reimport returns {"success":true,"message":"Asset reimported successfully"} while the asset stays dead. Never trust that response — verify from the .meta imported flag plus a non-empty subMetas containing gltf-mesh.
    2. The RangeError names 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>.bin alongside; copy both back in place, keeping .meta files intact), then refresh. Confirm extensionsRequired is empty before reimport. Verified: 5/5 models went from imported: false / 0 meshes to imported: true with full meshes, materials and prefabs.

  • Check extensionsRequired before promoting any glTF. A model can import imported: true yet still be wrong, so gate on the extension list: EXT_meshopt_compression and KHR_mesh_quantization in extensionsRequired are the two known Cocos-3.8.7 blockers. KHR_materials_specular only warns (cosmetic) and is safe.

  • meshCompress.quantize ON 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 in TEXCOORD_1 held (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 no TEXCOORD_1 but with COLOR_0 (normalized u8 VEC4) imported with quantize on kept COLOR_0 intact, so the damage is specific to the second UV stream, not to vertex attributes in general. Fix: set meshCompress.quantize: false in the model’s .meta userData (patch via JSON.parse/JSON.stringify, then reimport and re-read the .meta from 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 a TEXCOORD_1 accessor that is about to import with quantize on.

  • A shared material’s USE_VERTEX_COLOR define is flipped ON by ANY primitive that carries COLOR_0, not per-primitive — a sibling mesh with no COLOR_0 sharing that material samples black and renders pitch black, with no import error. Measured (3.8.7, character.glb): five tier meshes shared AtlasMat/StickmanMat. Only one of the five had a COLOR_0 stream, 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: true on both materials at build time. The four meshes with no COLOR_0 then 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 at library/<uuid[0:2]>/<uuid>@<id>.json for _defines[0].USE_VERTEX_COLOR. Fix: strip the all-white COLOR_0 attribute before import (lossless — it carries no color information the mesh needs), or give every primitive sharing the material a matching all-white COLOR_0. Promotion-time gate: flag a glTF/GLB whose primitives disagree on COLOR_0 presence when two or more of them reference the SAME material. three.js’s own GLTFLoader sets vertexColors per-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.wrapMode for the clip’s own sub-asset, AND userData.animationImportSettings[].splits[].wrapMode — set each to 1 (Normal). .meta files are CRLF on Windows; patch via JSON.parse/re-JSON.stringify, never a string/regex anchor on the raw text, or the line endings corrupt. Reimport, then re-read the .meta back from disk — the editor’s own reimport pass can rewrite it and silently restore wrapMode: 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’s Stickman@Death.fbx carried loopTime: 0 (and loopTime: 1 for Stickman@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 _effectAsset uuid first — a non-builtin effect whose .effect you 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 .glb with embedded materials) stores its shader as a bare _effectAsset.__uuid__ reference — no effect body. Copy the .mtl/.glb alone 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 _effectAsset uuid before importing. If it is not a builtin, i.e. it resolves to a project .effect (a common case: a builtin-standard copy carrying brightness/saturation/contrast tweaks), copy that .effect together 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 searched assets/, and a builtin is in the engine, not in assets/. Grep the source project’s .meta files for the uuid to settle it: a hit = a project asset you must copy; no hit anywhere = a real builtin. Evidence: FairShotPLA Plus.effect c9baf904-eb08-4307-af41-e0b5356a9878, a builtin-standard copy.

  • 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-port references/speed-and-pod.md).