Skip to content

t1k:unity:base:asset-import

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: asset import, asset naming check, asset pipeline, import assets, incoming assets, promote assets, validate assets

/t1k:unity:base:asset-import

Unity Asset Import: bindings for the gamedev import pipeline

Section titled “Unity Asset Import: bindings for the gamedev import pipeline”

The process (two-layer manifest, workflow, triage verdicts, report, rename suggestions, constraints) is the engine-neutral skill t1k:gamedev:assets:import-pipeline of theonekit-gamedev (module assets, a dependency of this module). Read and follow it; this skill only binds its engine slots to Unity. The adapter entry is capabilities.x-assets of t1k-unity-base-gamedev-adapter/gamedev-adapter.json.

SlotUnity value
incomingRootAssets/_Game/<GameName>/_Incoming, exactly this shape; scan-incoming.cjs rejects unsafe game names, traversal, absolute paths and symlink or junction escapes
scanscripts/scan-incoming.cjs
validatescripts/validate-naming.cjs (prefix regex, size budget, folderMap target)
promotescripts/promote-assets.cjs, report-only; --apply emits plan.cli[] directives that run through t1k unity eval (AssetDatabase.MoveAsset, then the Addressables group and labels call). Editor closed: move the file and its .meta together instead (t1k-unity-blind-edit-assets)
kitDefaultsreferences/default-manifest-schema.md (inline JSON: prefixes, budgets, folderMap, label families)
sidecar.meta: moves with the asset in lockstep or not at all, never rewritten, never processed as an asset
registerAddressables: folderMap[targetFolder] gives {group, labels} (below)
extensionsByTypethe table below; a mismatch is unknown-ext, not a hard reject by default
extraChecksno-realm-tag (ACCEPTED-WITH-WARNING: realm:auto requested, no suffix match; the token is dropped) and the per-asset-type validators below (advisory in v1.0, read from the .meta when it exists)

Project override: .claude/asset-pipeline.json, deep-merged over the kit defaults as the neutral skill’s manifest contract describes. Smoke 5 files first when the batch is over 10 (rules/preview-first-batch.md).

Commands (the three slot commands, as run)

Section titled “Commands (the three slot commands, as run)”
Terminal window
S=.claude/skills/t1k-unity-base-asset-import/scripts
bun $S/scan-incoming.cjs --project-root . --incoming-root "Assets/_Game/<GameName>/_Incoming"
bun $S/validate-naming.cjs --files-json <scan-output> --manifest <merged-manifest>
bun $S/promote-assets.cjs --triage-json <validate-output> --project-root . --game-name <GameName> [--apply]

scan-incoming.cjs prints {incomingRoot, fileCount, files: [{path, name, ext, sizeBytes}]} and skips *.meta, hidden files and directories. --apply first runs t1k unity status (Editor unreachable: take the Editor-closed path); per ACCEPTED file it runs the plan’s two cli[] directives through t1k unity eval (move, then the Addressables group and labels), then verifies with t1k unity eval 'UnityEditor.AssetDatabase.LoadMainAssetAtPath("<destination>") != null'. The whole batch is canonicalized before any directive is emitted: sources stay under Assets/_Game/<GameName>/_Incoming, targets under the same game root, duplicate and colliding directives are suppressed.

SymptomCauseRecovery
MoveAsset eval fails with “destination locked”Unity is mid-importwait and retry; never kill Unity (unity-forbidden-operations.md)
Addressables “group not found”the group is missingpre-create it with t1k-unity-base-addressables, re-run
.meta orphaned at the sourcemove incompletet1k unity eval 'UnityEditor.AssetDatabase.ImportAsset("<destination>")'
TypeExtensions
texture, texture.atlas.png, .jpg, .tga, .psd, .exr
sprite.png, .psd
material.mat
audio.sfx, audio.bgm.wav, .ogg, .mp3
vfx.vfx, .prefab
scriptableobject.asset
animation.clip.anim, .fbx
animation.controller.controller
shader.shader, .shadergraph, .hlsl
prefab, prefab.camera.prefab

Labels follow three families (manifest addressables.labelFamilies):

  • kind_*: always assigned from the folder type (kind_art, kind_audio, kind_vfx, kind_scene, kind_data).
  • realm_*: assigned by the realmAutoDetect regex against the filename suffix (_Primal gives realm_primal).
  • tier_*: tier_base unless the filename matches _expansion_N or _liveops.
TypeChecks
texturemax dimension (manifest budgets.texture.maxSize), sRGB ON for albedo (_D suffix), mip maps OFF for UI sprites
texture.atlashigher maxSize budget; warn if not in an Addressable sprite atlas group
audio.sfxmono, ADPCM or Vorbis, load type DecompressOnLoad, under 1 MB
audio.bgmstereo, Vorbis, load type Streaming, under 5 MB
animation.cliproot motion OFF unless under Cinematic/; duration under 30 s
spritePPU 100, filter mode Bilinear, no mip maps; a stretched sprite also passes references/slicing.md (border, FullRect, drawing path)
  1. Every move must carry the .meta or Unity loses the GUID. AssetDatabase.MoveAsset (the plan.cli[] directive) does it; a raw mv does not.
  2. The Addressables group must already exist: registration does not create one. Pre-create it with t1k-unity-base-addressables.
  3. labelFamilies.realm is replaced whole when the project sets it (arrays do not merge); prefixes merges key by key.
  4. _Incoming/ is gitignored by convention: never commit raw incoming files.
  5. A zero spriteBorder on a Type.Sliced image draws Simple, silently. A border in a code table is not the sprite’s border, and an importer that applies it only on first import skips every file copied with its .meta. Derive the border from the original m_Border, write it into the .meta, and run the checklist and the border test in references/slicing.md before calling a panel, frame or bar done.

Runs inline in the main session (or an inline sub-agent Bash call): the three scripts are deterministic invocations, not reasoning or orchestration. No sub-agent fan-out.

Scripts: scripts/scan-incoming.cjs, scripts/validate-naming.cjs, scripts/promote-assets.cjs. Related: t1k-unity-base-addressables (group and label registration), t1k-unity-base-code-conventions (naming, project-folder-structure.md), t1k-unity-editor-cli (runs the directives promote-assets.cjs emits).