菜单
Manage the Valkur Unity asset import pipeline — sprite import policies, atlas building, PPU configuration, pivot normalization, audio import. Covers ValkurAssetPostprocessor, CharacterAtlasBuilder, TileAtlasBuilder, TilePaletteBuilder.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | asset-pipeline |
| description | Manage the Valkur Unity asset import pipeline — sprite import policies, atlas building, PPU configuration, pivot normalization, audio import. Covers ValkurAssetPostprocessor, CharacterAtlasBuilder, TileAtlasBuilder, TilePaletteBuilder. |
| argument-hint | Describe the asset category or pipeline task |
| Category | PPU | FilterMode | Compression | Pivot | Atlas Group |
|---|---|---|---|---|---|
| Tiles | 32 | Point | None | Center | env-tiles |
| Characters | 16 | Point | None | Bottom-center | characters |
| NPC | 16 | Point | None | Bottom-center | npc |
| Projectiles | 16 | Point | None | Center | spells |
| Spell VFX | 16 | Point | None | Center | spells |
| Explosions | 16 | Point | None | Center | vfx |
| Items | 16 | Point | None | Center | items |
| UI | 100 | Bilinear | None | Center | ui |
| Particles | 16 | Point | None | Center | vfx |
| Buildings | 32 | Point | None | Bottom-center | buildings |
| Audio SFX | — | — | DecompressOnLoad / PCM | — | — |
| Audio Music | — | — | Streaming / Vorbis 0.7 | — | — |
Top-level folders are PascalCase (Unity convention); everything inside is snake_case.
Assets/_Project/Art/
├── Buildings/
│ ├── backgrounds/
│ ├── castles/
│ ├── houses/
│ └── ...
├── Characters/
│ ├── barbarian/
│ ├── dwarf/
│ ├── elven/
│ └── ...
├── Items/
│ ├── alchemy/
│ ├── cook/
│ ├── mining/
│ └── ...
├── NPC/ (enemies + neutral NPCs)
├── Spells/
├── Tiles/
│ ├── dungeon/
│ ├── palettes/
│ └── tile_assets/
├── UI/
│ ├── editors/ (per-editor icon subfolders)
│ ├── hud/
│ ├── intro/
│ └── shared/
├── VFX/
│ └── Vendor/ (asset-store packs)
└── Misc/
Assets/_Project/Audio/
├── Music/
│ ├── biomes/
│ ├── zones/
│ ├── bosses/
│ ├── events/
│ └── stingers/
└── SFX/
├── ambient/
├── clash/
├── inventory/
├── menu/
├── npc/
├── player/
└── spells/
Assets/_Project/SpriteAtlases/ ← single home for *.spriteatlas
Assets/_Project/Resources/ ← only files actually loaded via Resources.Load
Assets/_Project/Data/Catalogs/ ← all ScriptableObject catalogs
Vendor / asset-store packs live under <Layer>/Vendor/<PackName>/ (e.g. Art/VFX/Vendor/SlashVFX/). Never at Assets/ root.
Resources/ is loaded whole into the build. Keep it minimal: only put assets that are actually loaded via Resources.Load<T> (the canonical example is AudioCatalog.asset, SpellCatalog.asset, input action assets). Everything else → direct references or Addressables.
ValkurAssetPostprocessor.cs auto-applies import settings on every reimport based on path:
FilterMode.Point for pixel artDrop a new sprite into the appropriate folder and Unity handles the rest.
| Tool | Purpose |
|---|---|
CharacterAtlasBuilder.cs | Pack character sprite sheets |
TileAtlasBuilder.cs | Pack tile sprites |
TilePaletteBuilder.cs | Generate Unity TilePalette assets |
SpriteAtlasBuilder.cs | Generate SpriteAtlas for runtime packing |
BulkReimportTool.cs | Force-reimport a folder applying current postprocessor rules |
[category]_[entity]_[variant]_[state]_[direction]_[frame].png
Examples:
char_warrior_idle_down_01.png
tile_grass_01.png
spell_fireball_projectile_01.png
item_sword_iron.png
ui_btn_primary.png
Hard rules for every asset under Assets/_Project/:
snake_case (lowercase + underscores). Never PascalCase, kebab-case, spaces, or accented characters..png (not .PNG), .ogg, .wav, .asset. Mixed case breaks Linux/macOS imports.vaciar_*, pintar_*, imagen_*. Translate at import time.ChatGPT Image *.png, screenshot_2025_*.png, untitled.png, *_copy.png, *_old.png, *_new.png, *_final.png. Rename before committing.| Layer | Convention | Example |
|---|---|---|
Top-level under _Project/ | PascalCase | Art/, Audio/, Data/, Prefabs/, Resources/, Scenes/, Scripts/, Settings/, Shaders/, SpriteAtlases/ |
| Domain subfolders | snake_case (lowercase) | art/items/alchemy/, audio/sfx/inventory/, art/buildings/houses/ |
| Vendor / asset-store packs | _Project/<Layer>/Vendor/<PackName>/ | _Project/Art/VFX/Vendor/SlashVFX/ |
Vendor packs keep their original internal structure intact (the Demo/, Materials/, Prefabs/ PascalCase subfolders that ship with the pack) so they can be updated by re-importing from the Asset Store without merge conflicts. The snake_case rule applies to folders we author, not to third-party drops.
| Backups | NEVER inside Assets/ — git is the backup | (deleted) |
| Tier-2 recovery | _Project/Data/Backups/ — whitelisted exception | maintained by BuildingsDataGuard + MapEditorDataGuard |
| Catalog buckets | _Project/Data/Catalogs/<Name>/ keeps PascalCase — whitelisted exception | loaded by string name via Resources.Load("Catalogs/<Name>"); renaming forces matching path edits in many call sites |
| Empty folders | Don't keep folders with only .meta and no children | (deleted) |
The two-tier rule (PascalCase for top-level, snake_case for everything below) keeps Unity's standard project layout (Resources/, StreamingAssets/, Scenes/) intact while giving every domain folder a single, predictable convention.
The lint script tools/atlas/audit_asset_conventions.py enforces all of these (the EditMode test AssetConventionsTests runs the same checks inside Unity so CI catches violations).
| Pattern | Why it's forbidden |
|---|---|
*.PNG, *.JPG, *.OGG (uppercase ext) | Case-sensitive filesystems break |
Files in Assets/ root that aren't _Project/, Tests/, Settings/, StreamingAssets/, TextMesh Pro/, Scenes/, Screenshots/, Resources/, or Unity-required SO | Flat root is unmanageable |
Assets/_Project/Resources/*.png (loose at root) | Resources/ is loaded whole at build → bloat |
Folders named _backups, Backups, backup, OLD, *_old under Assets/ (whitelisted exceptions: _Project/Data/Backups/ — tier-2 recovery maintained by BuildingsDataGuard / MapEditorDataGuard — and any _Project/Scripts/**/Backups/ C# code namespace such as the Map editor's MapBackupBrowserUI) | Git is the backup |
Filenames containing ChatGPT, (space), (, ), ,, ' | Tooling-hostile |
Filenames ending in _old.png, _copy.png, _new.png, _final.png, _v2.png | Indicates uncommitted iteration; rename or delete |
InitTestScene*.unity committed (test runner artifact) | Already in .gitignore; older committed copies must be git rm'd |
Standalone Python utilities under tools/atlas/ (Pillow + stdlib only):
| Script | Use |
|---|---|
tools/atlas/audit_tile_sizes.py | Audit/fix tile dimensions; verifies 32×32 PPU=32 invariant |
tools/atlas/normalize_tiles.py | Bulk normalize tiles to 32×32 RGBA |
tools/atlas/unity_asset_audit.py | Per-file report → tools/cache/atlas/unity_asset_audit.json |
tools/atlas/generate_atlas_doc.py | Render the audit JSON as unity/Fase 2_v1_Atlas.md |
| Issue | Cause | Fix |
|---|---|---|
| Sprites blurry | FilterMode set to Bilinear | Set to Point (no filter) |
| Sprites wrong size | PPU mismatch | Verify PPU matches category table |
| Sprites offset | Wrong pivot | Set pivot per category rules |
| Pink sprites | Missing URP shader | Apply Sprite-Lit-Default material |
| Memory spike | No atlas packing | Build SpriteAtlas per domain |
| Tile overlap / "sand patch" | Oversized source PNG | Run tools/atlas/audit_tile_sizes.py --fix |
SpriteAtlas groups built and validatedasset_map.csv finalized as the manifest of every art asset (id, target path, atlas group, owner system)Performance diagnosis + optimization for Valkur — Profiler/Recorder API workflow, three-axis bottleneck model (CPU main / CPU render / GPU), URP HDR/shadow/post-process tuning, UGUI canvas pipeline, GC reduction patterns (hoisted buffers, no per-frame allocations), tick-rate throttling, and the catalog of optimizations already applied. Load whenever chasing low FPS, frame-time spikes, GC pauses, or memory pressure.
Performance diagnosis and optimization for the Valkur Unity project. Use when chasing low FPS, frame-time spikes, GC pauses, expensive Updates, GPU bottlenecks, render-thread stalls, or memory pressure. Covers Profiler/Recorder API workflow, hot-path patterns, URP/UGUI specifics, GC reduction, and Valkur's catalog of previously-applied optimizations.
Valkur Unity asset import pipeline — sprite import policies, atlas grouping, ValkurAssetPostprocessor, CharacterAtlasBuilder, TileAtlasBuilder, audio import. Load when importing, organizing, or validating assets.
One-stop quick reference for Valkur conventions — assemblies, layers, sorting, code style, the cardinal "console must be clean" rule, key gotchas. Load this skill at the start of any non-trivial task to keep the rules close to hand.
General Unity development for the Valkur project. Use when writing or refactoring Unity C# scripts, designing systems, working with MCP for Unity tools, debugging runtime issues, configuring assemblies/layers/ScriptableObjects, or troubleshooting domain-reload, Cinemachine, URP 2D, Tilemap, UI Toolkit/uGUI, or input issues. Covers MCP workflow, console verification, performance patterns, hot-reload safety, and project conventions.
Markdown documentation conventions for Valkur — markdownlint config, MD028 (no blank lines inside blockquotes), MD029 disabled globally for ordered lists, frontmatter style, table layout. Load when creating or editing any `.md` file (roadmaps, audits, checklists, migration guides) so lint warnings stay at zero.