/godot-asset-generator

Godot Import Settings Guide

Optimal import settings for different game asset types in Godot 4.x.

Import Settings Overview

When you add an image to a Godot project, it creates a .import file that controls how the image is processed.

Presets Reference

Pixel Art Sprites

For retro/pixel art games with crisp, unfiltered pixels.

Import file settings:

compress/mode=0
mipmaps/generate=false
process/fix_alpha_border=true

Project Settings (also set globally):

rendering/textures/canvas_textures/default_texture_filter = Nearest

HD 2D Sprites

For high-resolution 2D games with smooth scaling.

Import file settings:

compress/mode=2
compress/high_quality=true
mipmaps/generate=true
process/fix_alpha_border=true

UI Elements

For interface elements like buttons, panels, icons.

Backgrounds

For large background images.

Compression Modes

Filter Modes

Nearest (Pixel Art)

Preserves hard pixel edges. Essential for:

• Pixel art sprites
• Retro-style games
• Any asset where you want visible pixels

Linear (Smooth)

Interpolates between pixels. Use for:

• HD sprites
• Painted/illustrated assets
• Photographs
• Backgrounds

Sprite Sheet Configuration

For sprite sheets, configure in the Import dock:

1. Import as: Texture2D (default)
2. Detect 3D: Off
3. Process → Fix Alpha Border: On

Then in your scene:

• Create AnimatedSprite2D node
• Create new SpriteFrames resource
• Add frames by region or auto-slice

Using Sheet Metadata

If using pack-spritesheet.ts with --metadata:

# Load metadata
var meta = JSON.parse_string(FileAccess.open("res://sprites/sheet.json", FileAccess.READ).get_as_text())

# Create frames from metadata
var frames = SpriteFrames.new()
frames.add_animation("walk")

for frame in meta.frames:
    var texture = load("res://sprites/sheet.png")
    var atlas = AtlasTexture.new()
    atlas.atlas = texture
    atlas.region = Rect2(frame.x, frame.y, frame.width, frame.height)
    frames.add_frame("walk", atlas)

AnimatedSprite2D Setup

From Sprite Sheet

1. Add AnimatedSprite2D node
2. Create new SpriteFrames in Sprite Frames property
3. Click SpriteFrames to open animation editor
4. Add animation (e.g., "walk")
5. Click folder icon → "Add Frames from Sprite Sheet"
6. Select your sprite sheet image
7. Configure grid (columns × rows)
8. Select frames for animation
9. Set FPS in animation panel

Recommended FPS

AtlasTexture for Individual Frames

For extracting single sprites from a sheet:

var atlas = AtlasTexture.new()
atlas.atlas = preload("res://sprites/sheet.png")
atlas.region = Rect2(0, 0, 64, 64)  # x, y, width, height

$Sprite2D.texture = atlas

Nine-Patch for UI

For scalable UI elements (panels, buttons):

1. Import as Texture2D with Lossless
2. Create NinePatchRect node
3. Assign texture
4. Set patch margins (left, top, right, bottom)
5. Set draw center as needed

var nine_patch = NinePatchRect.new()
nine_patch.texture = preload("res://ui/panel.png")
nine_patch.patch_margin_left = 16
nine_patch.patch_margin_top = 16
nine_patch.patch_margin_right = 16
nine_patch.patch_margin_bottom = 16

Tileset Setup

For tile-based games:

1. Import tile sheet with Nearest filter (for pixel art)
2. Create TileSet resource
3. Add texture as TileSetAtlasSource
4. Configure tile size (e.g., 16×16, 32×32)
5. Set up collision, navigation as needed

TileMap configuration:

var tilemap = TileMap.new()
tilemap.tile_set = preload("res://tilesets/world.tres")
tilemap.cell_quadrant_size = 16  # Match tile size

Project-Wide Settings

For Pixel Art Games

In Project Settings → Rendering → Textures:

canvas_textures/default_texture_filter = Nearest

In Project Settings → Display → Window:

stretch/mode = viewport
stretch/aspect = keep

For HD Games

In Project Settings → Rendering → Textures:

canvas_textures/default_texture_filter = Linear

Using generate-import-files.ts

# Pixel art preset
deno run scripts/generate-import-files.ts \
  --input ./sprites/player.png --preset pixel-art

# HD sprites
deno run scripts/generate-import-files.ts \
  --input ./hd-sprites/ --preset hd-sprite

# UI elements
deno run scripts/generate-import-files.ts \
  --input ./ui/ --preset ui

Troubleshooting

Sprites Look Blurry

• Check Filter Mode is set to Nearest
• Verify project default texture filter
• Ensure no scaling applied to Sprite2D node

Edge Artifacts / Bleeding

• Enable "Fix Alpha Border" in import
• Add 1-2px transparent padding in sprite sheet
• Use --padding option in pack-spritesheet.ts

Colors Look Wrong

• Check color space settings
• Ensure PNG is saved with correct color profile
• Try Lossless compression mode

File Size Too Large

• Use VRAM compression for large textures
• Lower Lossy quality for backgrounds
• Consider splitting very large sheets