Organize Asset Files

Organize Asset Files

Core Principle

Assets organized by type and purpose. Easy to find, easy to maintain, easy to optimize.

What This Skill Does

Finds asset directories like:

assets/
├── player_sprite.png
├── enemy1.png
├── enemy2.png
├── jump.wav
├── background_music.ogg
├── font.ttf
├── tile1.png
├── tile2.png
└── ... (100 more mixed assets)

Transforms to:

assets/
├── sprites/
│   ├── characters/
│   │   └── player_sprite.png
│   ├── enemies/
│   │   ├── enemy1.png
│   │   └── enemy2.png
│   └── environment/
│       ├── tiles/
│       │   ├── tile1.png
│       │   └── tile2.png
│       └── atlases/
│           └── environment_atlas.png  # Combined tiles
├── audio/
│   ├── music/
│   │   └── background_music.ogg
│   └── sfx/
│       └── jump.wav
└── fonts/
    └── font.ttf

Detection Patterns

Identifies:

• Assets in wrong categories
• No subdirectory organization
• Inconsistent naming conventions
• Potential sprite atlas opportunities
• Unused/​duplicate assets

When to Use

Building Asset-Heavy Game

Games with many sprites, sounds, or visual assets.

Optimizing Performance

Creating sprite atlases reduces draw calls.

Managing Large Asset Library

Finding specific asset becomes difficult.

Preparing for Asset Pipeline

Clean structure enables automated processing.

Process

1. Scan - Inventory all asset files by type
2. Analyze - Determine logical groupings
3. Group - Identify related assets (animation frames, tile sets)
4. Optimize - Create sprite atlases where beneficial
5. Move - Relocate assets to organized structure
6. Update - Fix all references in scenes and scripts
7. Validate - Ensure assets load correctly
8. Commit - Git commit per asset category

Organization Strategies

By Asset Type

Primary organization: sprites, audio, fonts, materials.

By Domain

Secondary organization: characters, enemies, environment, ui.

By Purpose

Tertiary organization: animations, icons, backgrounds, effects.

Sprite Organization

sprites/
├── characters/
│   ├── player/
│   │   ├── idle/
│   │   │   ├── idle_01.png
│   │   │   ├── idle_02.png
│   │   │   └── idle_03.png
│   │   ├── run/
│   │   └── jump/
│   └── npc/
├── enemies/
│   ├── goblin/
│   ├── orc/
│   └── dragon/
├── items/
│   ├── weapons/
│   ├── consumables/
│   └── collectibles/
├── environment/
│   ├── tiles/
│   ├── props/
│   └── backgrounds/
└── ui/
    ├── icons/
    ├── buttons/
    └── panels/

Audio Organization

audio/
├── music/
│   ├── main_theme.ogg
│   ├── battle_music.ogg
│   └── ambient/
│       ├── forest.ogg
│       └── cave.ogg
├── sfx/
│   ├── player/
│   │   ├── jump.wav
│   │   ├── land.wav
│   │   └── attack.wav
│   ├── enemies/
│   │   ├── hit.wav
│   │   └── death.wav
│   ├── ui/
│   │   ├── click.wav
│   │   └── hover.wav
│   └── environment/
│       ├── door_open.wav
│       └── chest_open.wav
└── voice/  # For games with voice acting

Sprite Atlas Creation

Detects atlas opportunities:

• Multiple small sprites used together (UI icons)
• Animation frames (8+ frames in sequence)
• Tileset pieces (can be combined)
• Related sprites loaded simultaneously

Creates atlases when:

• 4+ sprites under 128x128 pixels
• Related sprites (same domain)
• Performance benefit (reduce draw calls)

Example:

# Before: 20 separate UI icon files (20 draw calls)
ui/​icons/​health_icon.png
ui/​icons/​mana_icon.png
... (18 more)

# After: 1 atlas texture (1 draw call)
ui/​atlases/​ui_icons_atlas.png
ui/​atlases/​ui_icons_atlas.png.import  # Atlas regions defined

Naming Conventions

Sprites

• character_player_idle_01.png
• enemy_goblin_attack_03.png
• item_sword_iron.png

Audio

• music_main_theme.ogg
• sfx_player_jump.wav
• ambient_forest_birds.ogg

Materials

• mat_character_player.tres
• mat_environment_grass.tres

Consistent naming enables:

• Alphabetical sorting groups related assets
• Easy searching and filtering
• Automated processing scripts

What Gets Created

• Organized asset directories by type
• Subdirectories by domain/​purpose
• Sprite atlases where beneficial
• Renamed files for consistency (optional)
• Updated references in all scenes/​scripts
• Git commits per asset category

Smart Analysis

Detects usage patterns:

• Frequently used together → group together
• Animation sequences → organize in frames
• UI elements → candidate for atlas
• Unused assets → flag for review

Optimizes based on:

• File size (small sprites → atlas)
• Load frequency (often used → optimize)
• Relationships (animation frames → folder)

Integration

Works with:

• godot-organize-files - Base organization first
• godot-organize-scripts - Parallel script organization
• godot-organize-project (orchestrator) - Full project organization

Safety

• All asset references preserved during moves
• Godot .import files regenerated correctly
• Sprite atlas creation validates regions
• Rollback on validation failure
• Original structure in git history

When NOT to Use

Don't reorganize if:

• Assets already well organized
• External asset management tool in use
• Mid-production (bad timing for large changes)
• Custom organization required by pipeline

Benefits

• Performance - Sprite atlases reduce draw calls
• Organization - Find assets quickly
• Workflow - Import new assets to correct location
• Scalability - Structure supports more assets
• Collaboration - Team knows where assets belong

Atlas Performance

Without atlases:

• 20 UI icons = 20 separate textures = 20 draw calls
• 30 enemy sprites = 30 textures = 30 draw calls

With atlases:

• 20 UI icons = 1 atlas texture = 1 draw call
• 30 enemy sprites = 2-3 atlases = 2-3 draw calls

Significant performance improvement, especially for mobile.

Common Transformations

Configuration Options

• Enable/​disable sprite atlas creation
• Minimum atlas sprite count (default: 4)
• Maximum atlas size (default: 4096x4096)
• Naming convention style
• Organization depth (flat vs deep hierarchy)

Defaults follow Godot best practices and performance guidelines.