/assets-pipeline

name: assets-pipeline
description: Use when importing and managing assets — image compression, 3D scene import, audio formats, resource formats, and import configuration

Assets Pipeline in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.

> **Related skills:** **audio-system** for audio playback and bus architecture, **3d-essentials** for 3D materials and lighting, **2d-essentials** for 2D rendering and sprites, **animation-system** for imported animations, **godot-optimization** for asset-related performance, **multithreading** for threaded resource loading.

---

1. How Importing Works

The Import System

When you add a file to `res://`, Godot auto-imports it based on its type. Import settings are stored in `.import` sidecar files alongside the original.

project/
├── textures/
│   ├── player.png           ← original file (committed to VCS)
│   └── player.png.import    ← import settings (committed to VCS)
└── .godot/
    └── imported/            ← compiled cache (NOT committed — .gitignore it)

Key Rules

• **Never modify files in `.godot/imported/`** — they are regenerated from originals
• **Commit `.import` files** to version control — they store your settings
• **Reimport** after changing settings: select file → Import dock → click **Reimport**
• `.godot/` should be in your `.gitignore`

Changing Import Settings

1. Select the file in the **FileSystem** dock 2. Open the **Import** dock (next to Scene dock by default) 3. Change settings 4. Click **Reimport** (or **Reimport All** for batch changes)

> Import settings can also be set via **Advanced Import Settings** for 3D scenes (double-click the `.glb`/`.gltf` file).

---

2. Image Import

Compression Modes

| Mode | Quality | VRAM | File Size | Use For | |----------------|-----------|----------|-----------|----------------------------------| | **Lossless** | Perfect | High | Large | Pixel art, UI elements | | **Lossy** | Good | High | Small | Large photos, backgrounds | | **VRAM Compressed** | Reduced | Low | Small | 3D textures, large 2D sprites | | **VRAM Uncompressed** | Perfect | High | Large | When VRAM compression artifacts are unacceptable | | **Basis Universal** | Reduced | Low | Very small | Cross-platform, multiple GPU formats |

When to Use Each

Pixel art / UI icons       → Lossless (no artifacts, crisp pixels)
2D game sprites            → Lossless (small sprites) or VRAM Compressed (large sprites)
3D textures (albedo, normal) → VRAM Compressed (saves GPU memory)
Large backgrounds          → Lossy or VRAM Compressed
Mobile targets             → VRAM Compressed (essential for memory)

Key Import Settings

| Setting | Description | Default | |--------------------|-----------------------------------------------|-------------| | **Compress > Mode** | Compression algorithm (see table above) | Lossless (VRAM Compressed in the 3D preset; a texture detected in 3D is switched to it) | | **Mipmaps > Generate** | Generate mipmaps for distance rendering | Off (On in the 3D preset) | | **Process > Fix Alpha Border** | Prevents dark outlines on transparent sprites | On | | **Process > Premult Alpha** | Pre-multiply alpha (avoids dark halos) | Off |

Filtering and repeat are not import options in Godot 4: they are `texture_filter` / `texture_repeat` on each `CanvasItem` (or the material's sampler in 3D).

Pixel Art Setup

For crisp pixel art, set these project-wide:

**Project Settings > Rendering > Textures > Canvas Textures > Default Texture Filter** → `Nearest`

Or per node: `CanvasItem.texture_filter` → `Nearest`

Enabling Mipmaps

Mipmaps prevent shimmering on textures viewed at an angle or from a distance. Required for 3D textures; optional for 2D.

• **3D textures:** Always enable mipmaps (Import dock → Mipmaps → Generate → On)
• **2D sprites:** Usually off (unless you use Camera2D zoom)
• **UI textures:** Off (rendered at fixed scale)

> **Godot 4.7+:** DDS import supports the R8 and R8G8 texture formats. ([GH-116307](https://github.com/godotengine/godot/pull/116307))

---

3. 3D Scene Import

Supported Formats

| Format | Extension | Recommendation | |-----------|-------------|----------------------------------------------| | **glTF** | `.gltf`, `.glb` | **Recommended** — open standard, best support | | **Blend** | `.blend` | Direct Blender import (requires Blender installed) | | **FBX** | `.fbx` | Good for legacy pipelines | | **Collada** | `.dae` | Older format, use glTF if possible | | **OBJ** | `.obj` | Static meshes only — no animations/rigs |

> **glTF is the recommended format.** It has the best Godot support, is an open standard, and preserves materials, animations, and rigs accurately.

Node Naming Conventions

Godot auto-creates appropriate node types based on **suffixes** in your 3D model's object names:

| Suffix | Generated Node | Example Name | |-----------------------|---------------------------|----------------------------| | `-col` | StaticBody3D + collision | `Wall-col` | | `-convcol` | ConvexPolygonShape3D | `Rock-convcol` | | `-rigid` | RigidBody3D | `Barrel-rigid` | | `-navmesh` | NavigationRegion3D | `Floor-navmesh` | | `-occ` | OccluderInstance3D (`-occonly` drops the mesh) | `BigWall-occ` |

In Blender:                  In Godot (after import):
Wall-col (mesh object)    →  Wall (MeshInstance3D)
                               └── StaticBody3D
                                   └── CollisionShape3D (auto-generated)

Import Dock Settings

Select the imported `.glb`/`.gltf` in FileSystem, then in the Import dock:

| Setting | Description | |----------------------------|--------------------------------------------------| | **Root Type** | Override root node type (Node3D, RigidBody3D, etc.) | | **Root Name** | Custom name for the root node | | **Meshes > Generate LOD** | Auto-generate LOD levels (on by default) | | **Meshes > Light Baking** | Static or Dynamic for lightm