game-asset-pipeline
Use when adding, importing, moving or loading textures, models, audio or scenes - per-platform compression, atlases, LODs, async loading per engine, engine metadata files (.meta, .import, .uid, .uasse
SKILL.mdcatalog/agents/game-developer/skills/game-asset-pipeline/SKILL.md
GitHubGame Asset Pipeline
Overview
Assets are most of a game's size, most of its load time and most of its memory. They also come with engine metadata that silently breaks references when it is lost: a Unity .meta regenerated with a new GUID unhooks every prefab that used the asset. Treat assets like code — reviewed import settings, committed metadata, validated by tests.
Core principle: Compressed for the target platform, loaded asynchronously, committed with its metadata, and never moved outside the engine that owns its references.
Metadata files — commit them, never orphan them
| Engine | Files | Rule |
|---|---|---|
| Unity | <asset>.meta (GUID + import settings) beside every asset and folder |
Commit with the asset; move/rename inside the Editor or move the .meta with it; never delete and regenerate |
| Godot 4 | <asset>.import beside imported assets; .uid beside scripts and shaders (4.4+); .godot/ cache |
Commit .import and .uid; ignore .godot/ |
| Unreal | .uasset / .umap (binary, references by path) |
Move/rename only in the Editor, then "Fix Up Redirectors"; lock binaries (LFS lockable) |
| Web / Bevy | none | Paths are code — update every reference in the same change |
Moving a file with mv in a Unity or Unreal project without its metadata (or outside the editor) is a broken-reference bug even if the build is green.
Git LFS
- Check
.gitattributesfirst; follow the patterns it already has. Typical:*.png *.psd *.fbx *.glb *.wav *.ogg *.uasset *.umap filter=lfs diff=lfs merge=lfs -text, withlockablefor Unreal binaries. - A new binary type the repository does not track yet gets its pattern added in the same change — not a 40 MB
.fbxcommitted as a regular blob. git lfs ls-filesshows what is tracked; ifgit lfsis not installed here, say so instead of committing pointers by hand.
Textures
| Target | Format |
|---|---|
| Desktop / console | BC7 (colour), BC5 (normal maps), BC4 (single channel) |
| Modern mobile | ASTC (block size by quality: 4×4 UI, 6×6–8×8 world) |
| Android fallback | ETC2 |
| Web | KTX2 / Basis Universal (transcoded per GPU at load), WebP/AVIF for UI and 2D |
- Unity: per-platform overrides in the importer; max size per platform; mipmaps on for world textures, off for UI and pixel art; Sprite Atlas for 2D.
- Godot: "VRAM Compressed" for 3D (enable ETC2/ASTC import in project settings for mobile), "Lossless" with filtering off for pixel art; AtlasTexture/TileSet for 2D.
- Unreal: texture groups and compression settings (
TC_Default,TC_Normalmap,TC_Masks), LOD bias per platform. - Web: KTX2 via three.js
KTX2Loader/ Babylon's KTX2 support; packed atlases (TexturePacker JSON) for Phaser/PixiJS. - Power-of-two sizes where mipmaps or block compression need them; no 4K texture on a 64-pixel prop.
Meshes and scenes
- LODs for anything seen at a distance: Unity
LODGroup, Godot automatic mesh LOD on import, Unreal Nanite for static meshes where the platform supports it and classic LODs elsewhere (skeletal meshes, mobile). - Web: glTF/GLB with Draco or meshopt geometry compression and KTX2 textures —
npx @gltf-transform/cli optimize in.glb out.glbis a quick win; check the repository's pipeline first. - Colliders are simplified shapes, not render meshes.
Audio
- Compressed (Vorbis/Opus/AAC); music streamed, short frequent SFX decompressed on load.
- Unity: Load Type per clip (Streaming for music, Decompress On Load for short SFX); Godot:
.oggfor music,.wavfor short SFX; web: a format every target browser decodes, and an audio-unlock on the first user gesture.
Loading without hitches
// ❌ synchronous load mid-gameplay: a visible hitch, and Resources/ ships everything
var prefab = Resources.Load<GameObject>("Enemies/Boss");
// ✅ async, released when done (Addressables)
var handle = Addressables.LoadAssetAsync<GameObject>("enemies/boss");
var prefab = await handle.Task;
// ... later, when the level unloads:
Addressables.Release(handle);
# Godot: threaded load at a loading screen or ahead of need
ResourceLoader.load_threaded_request(LEVEL_PATH)
# poll in _process:
if ResourceLoader.load_threaded_get_status(LEVEL_PATH) == ResourceLoader.THREAD_LOAD_LOADED:
var scene: PackedScene = ResourceLoader.load_threaded_get(LEVEL_PATH)
- Unreal: soft references (
TSoftObjectPtr,TSoftClassPtr) withUAssetManager/FStreamableManager::RequestAsyncLoad; avoid hard references in Blueprints that pull whole asset graphs into memory. - Web: Phaser's loader in a preload scene, PixiJS
Assets.loadBundle, three.jsLoadingManager; code-split per level. - Bevy:
AssetServer::loadreturns a handle immediately; gate the state change on the load state (or the repository's loading plugin).
Validating assets in tests
An import-settings test fails the build when someone drops in an uncompressed 4K texture:
[Test] public void WorldTextures_AreCompressedAndCapped() {
foreach (var guid in AssetDatabase.FindAssets("t:Texture2D", new[] { "Assets/_Project/Art/World" })) {
var path = AssetDatabase.GUIDToAssetPath(guid);
var importer = (TextureImporter)AssetImporter.GetAtPath(path);
Assert.That(importer.maxTextureSize, Is.LessThanOrEqualTo(2048), path);
Assert.That(importer.textureCompression, Is.Not.EqualTo(TextureImporterCompression.Uncompressed), path);
}
}
The same idea elsewhere: a Godot test reading .import files under res://art/world, a Node script checking public/ sizes and formats, a data-validation rule in Unreal.
Common Mistakes
- Moving or renaming assets with
mvand losing.metaGUIDs or Unreal references. - Committing Godot's
.godot/cache or Unreal'sIntermediate/,Saved/,DerivedDataCache/,Binaries/. - Uncompressed or oversized textures; mipmaps on UI sprites.
Resources.Load/ synchronousload()during gameplay.- Loaded assets never released (Addressables handles, three.js textures) — memory grows every level.
Red Flags
- A new binary file in the diff that is not covered by
.gitattributesLFS patterns the repo uses. - An asset in the diff without its
.meta/.import, or a.metawith a changed GUID. - A hitch report and a synchronous load in the same code path.