Skip to content
T1KTheOneKit

t1k:cocos:base:asset-import

FieldValue
Modulebase
Version1.10.0
Effortmedium
Tools—

Keywords: asset-bundle, asset-import, asset-pipeline, cocos, cocos-creator, incoming, naming, promote, validate

How to invoke

Section titled “How to invoke”
/t1k:cocos:base:asset-import

t1k-cocos-base-asset-import

Section titled “t1k-cocos-base-asset-import”

Manifest-driven asset import pipeline for Cocos Creator 3.x projects. Reads incoming raw assets from assets/_Incoming/, validates naming and budgets against a project-level .claude/asset-pipeline.json (layered on top of kit defaults), and promotes accepted assets into their canonical folders with .meta co-moved.

This is the Cocos parallel of t1k-unity-base-asset-import. Same triage model (ACCEPTED-CLEAN / ACCEPTED-WITH-WARNING / REJECTED-ERROR), same report format, same override merge — only the engine-specific operations differ.

When to invoke

Section titled “When to invoke”
  • The user drops a batch of raw textures, prefabs, audio, scenes, or .effect shaders into assets/_Incoming/ and wants them promoted.
  • The user asks “validate assets”, “check asset naming”, or “import these into the project”.
  • CI gate: scan-only mode to fail the build on naming/budget violations before merge.

Inputs

Section titled “Inputs”
  • Manifest: project .claude/asset-pipeline.json (project SSOT). If absent, kit defaults from references/default-manifest-schema.md apply. Project values override kit values key-by-key (no deep-merge of arrays — replacement only).
  • Incoming root: assets/_Incoming/ (configurable via incomingRoot).
  • Mode flags:
    • default → report only
    • --apply → perform moves
    • --apply --no-promote-warnings → move only ACCEPTED-CLEAN files; leave warnings in _Incoming/

Workflow

Section titled “Workflow”
  1. Load manifest. Read kit defaults (from this skill’s references/default-manifest-schema.md); overlay project .claude/asset-pipeline.json if present.
  2. Scan. Run scripts/scan-incoming.cjs <project-root> → JSON inventory of files under assets/_Incoming/, with detected type by extension + prefix.
  3. Validate. Run scripts/validate-naming.cjs against the merged manifest. Each file gets:
    • triage: ACCEPTED-CLEAN | ACCEPTED-WITH-WARNING | REJECTED-ERROR
    • reasons[]: regex mismatch, unknown prefix, budget warn/err, unknown extension, missing .meta
    • targetFolder: resolved from manifest prefixes[*].targetFolder
    • bundle: resolved from manifest folderMap[targetFolder].bundle (Cocos Asset Bundle)
  4. Report. Render the markdown report per references/report-format.md. Surface counts per triage level, per-file reasons, and the promotion plan.
  5. Decide via AskUserQuestion. Options: proceed (--apply), proceed-strict (--apply --no-promote-warnings), fix-and-rescan, abort.
  6. Promote (only if user picks proceed). scripts/promote-assets.cjs --apply:
    • For each accepted file, mv <src> <dest> then mv <src>.meta <dest>.meta (co-move).
    • If <src>.meta is missing, log a WARNING and skip the meta move; the editor will regenerate the meta on next refresh — but UUID changes, breaking refs. Project owner must approve via AskUserQuestion before promoting meta-less files.
    • Never regenerate or rewrite .meta content during promote — UUIDs are immutable.
    • Idempotent: skip if dest already exists with matching content (same SHA).

Triage rules

Section titled “Triage rules”

See references/triage-rules.md. Summary:

ConditionTriage
Regex matches + budget within maxSize/maxBytes + .meta presentACCEPTED-CLEAN
Regex matches + budget in warnAbove/warnBytes band, or .meta missingACCEPTED-WITH-WARNING
Regex mismatch (and triage.rejectOnRegexMismatch=true), or budget over errAbove/errBytes (and triage.rejectOnErrCap=true), or unknown prefixREJECTED-ERROR

Cocos-specific deviations from the Unity sibling

Section titled “Cocos-specific deviations from the Unity sibling”
  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/.ogg (audio), .asset.json (Cocos plugin asset).
  7. Budgets mirror the mobile target. No DOTS-specific constraints.

Scripts

Section titled “Scripts”
Terminal window
# Scan only — emits JSON inventory
node scripts/scan-incoming.cjs <project-root>


# Validate against manifest — emits JSON report with triage
node scripts/validate-naming.cjs <project-root>


# Promote (dry-run by default; --apply commits)
node scripts/promote-assets.cjs <project-root>
node scripts/promote-assets.cjs <project-root> --apply
node scripts/promote-assets.cjs <project-root> --apply --no-promote-warnings

References

Section titled “References”
  • references/default-manifest-schema.md — full default manifest with Cocos prefixes and budgets
  • references/workflow.md — step-by-step flow + decision points
  • references/triage-rules.md — exact triage thresholds and reason codes
  • references/report-format.md — markdown report layout
  • references/project-override-pattern.md — how project .claude/asset-pipeline.json overrides kit defaults

Gotchas

Section titled “Gotchas”
  • 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, .ogg) 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.