t1k:unity:base:asset-import
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: asset import, asset naming check, asset pipeline, import assets, incoming assets, promote assets, validate assets
How to invoke
Section titled “How to invoke”/t1k:unity:base:asset-importUnity 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.
Slot bindings
Section titled “Slot bindings”| Slot | Unity value |
|---|---|
incomingRoot | Assets/_Game/<GameName>/_Incoming, exactly this shape; scan-incoming.cjs rejects unsafe game names, traversal, absolute paths and symlink or junction escapes |
scan | scripts/scan-incoming.cjs |
validate | scripts/validate-naming.cjs (prefix regex, size budget, folderMap target) |
promote | scripts/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) |
kitDefaults | references/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 |
register | Addressables: folderMap[targetFolder] gives {group, labels} (below) |
extensionsByType | the table below; a mismatch is unknown-ext, not a hard reject by default |
extraChecks | no-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)”S=.claude/skills/t1k-unity-base-asset-import/scriptsbun $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.
| Symptom | Cause | Recovery |
|---|---|---|
MoveAsset eval fails with “destination locked” | Unity is mid-import | wait and retry; never kill Unity (unity-forbidden-operations.md) |
| Addressables “group not found” | the group is missing | pre-create it with t1k-unity-base-addressables, re-run |
.meta orphaned at the source | move incomplete | t1k unity eval 'UnityEditor.AssetDatabase.ImportAsset("<destination>")' |
Expected extensions
Section titled “Expected extensions”| Type | Extensions |
|---|---|
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 |
Addressables group and label assignment
Section titled “Addressables group and label assignment”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 therealmAutoDetectregex against the filename suffix (_Primalgivesrealm_primal).tier_*:tier_baseunless the filename matches_expansion_Nor_liveops.
Per-asset-type validators
Section titled “Per-asset-type validators”| Type | Checks |
|---|---|
texture | max dimension (manifest budgets.texture.maxSize), sRGB ON for albedo (_D suffix), mip maps OFF for UI sprites |
texture.atlas | higher maxSize budget; warn if not in an Addressable sprite atlas group |
audio.sfx | mono, ADPCM or Vorbis, load type DecompressOnLoad, under 1 MB |
audio.bgm | stereo, Vorbis, load type Streaming, under 5 MB |
animation.clip | root motion OFF unless under Cinematic/; duration under 30 s |
sprite | PPU 100, filter mode Bilinear, no mip maps; a stretched sprite also passes references/slicing.md (border, FullRect, drawing path) |
Hard rules
Section titled “Hard rules”- Every move must carry the
.metaor Unity loses the GUID.AssetDatabase.MoveAsset(theplan.cli[]directive) does it; a rawmvdoes not. - The Addressables group must already exist: registration does not create one. Pre-create it with
t1k-unity-base-addressables. labelFamilies.realmis replaced whole when the project sets it (arrays do not merge);prefixesmerges key by key._Incoming/is gitignored by convention: never commit raw incoming files.- A zero
spriteBorderon aType.Slicedimage 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 originalm_Border, write it into the.meta, and run the checklist and the border test inreferences/slicing.mdbefore calling a panel, frame or bar done.
Executed by
Section titled “Executed by”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 and related skills
Section titled “Scripts and related skills”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).