godot-organize-assets

name	godot-organize-assets
version	3.0.0
displayName	Organize Asset Files
description	Use when Godot project has disorganized assets (sprites, audio, fonts, materials). Detects scattered asset files and organizes them into clear categories with consistent naming. Creates sprite atlases where beneficial, organizes audio by type, and groups related assets together.
author	Asreonn
license	MIT
category	game-development
type	tool
difficulty	beginner
audience	["developers"]
keywords	["godot","asset-organization","sprites","audio","sprite-atlases","file-structure","performance","assets"]
platforms	["macos","linux","windows"]
repository	https://github.com/asreonn/godot-superpowers
homepage	https://github.com/asreonn/godot-superpowers#readme
permissions	{"filesystem":{"read":[".png",".jpg",".wav",".ogg",".ttf",".glb",".tres"],"write":["*"],"move":true,"delete":false},"git":true}
behavior	{"auto_rollback":true,"validation":true,"git_commits":true}
outputs	Organized asset directories, moved files, sprite atlases, naming consistency, git commits
requirements	Git repository, Godot 4.x
execution	Fully automatic with reference preservation
integration	Part of godot-organize-project orchestrator, works with godot-organize-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

Before	After
player.png in root	assets/sprites/characters/player/idle.png
sound.wav mixed	assets/audio/sfx/player/jump.wav
20 icons scattered	assets/sprites/ui/atlases/ui_atlas.png
font.ttf in assets	assets/fonts/main_font.ttf

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.