godot-organize-files

name	godot-organize-files
version	3.0.0
displayName	Organize Project File Structure
description	Use when Godot project has scattered files with no clear organization. Detects assets, scripts, scenes, and resources in root or inconsistent locations. Automatically creates organized directory structure following Godot best practices, moves files preserving references, and updates all dependencies.
author	Asreonn
license	MIT
category	game-development
type	tool
difficulty	beginner
audience	["developers"]
keywords	["godot","file-organization","directory-structure","project-cleanup","best-practices","asset-management","gdscript","godot-project"]
platforms	["macos","linux","windows"]
repository	https://github.com/asreonn/godot-superpowers
homepage	https://github.com/asreonn/godot-superpowers#readme
permissions	{"filesystem":{"read":["*"],"write":["*"],"move":true,"delete":false},"git":true}
behavior	{"auto_rollback":true,"validation":true,"git_commits":true}
outputs	Organized directory structure, moved files with preserved references, git commits
requirements	Git repository, Godot 4.x
execution	Fully automatic with reference preservation
integration	Part of godot-organize-project orchestrator, works with organize-assets and organize-scripts

Organize Project File Structure

Core Principle

Clear structure = easy navigation. Files should be where you expect them.

What This Skill Does

Finds projects like:

my_game/
├── project.godot
├── player.gd
├── enemy.gd
├── sprite1.png
├── sound.wav
├── level1.tscn
├── main_menu.tscn
├── utility.gd
└── ... (50 more files in root)

Transforms to:

my_game/
├── project.godot
├── assets/
│   ├── sprites/
│   │   └── sprite1.png
│   └── audio/
│       └── sound.wav
├── scenes/
│   ├── levels/
│   │   └── level1.tscn
│   └── ui/
│       └── main_menu.tscn
└── scripts/
    ├── player.gd
    ├── enemy.gd
    └── utility.gd

Detection Patterns

Identifies:

• Files in root directory that should be organized
• Inconsistent naming (CamelCase, snake_case mixed)
• Assets mixed with code
• No logical grouping by type or domain

When to Use

Starting New Project

Establish structure from the beginning.

Inheriting Legacy Project

Project has grown organically without structure.

Preparing for Collaboration

Team needs consistent file locations.

Before Major Refactoring

Clean structure makes refactoring easier.

Process

1. Scan - Inventory all project files and current structure
2. Analyze - Determine file types and relationships
3. Plan - Create target directory structure
4. Move - Relocate files preserving all references
5. Update - Fix paths in .tscn, .gd, project.godot
6. Validate - Ensure all references still work
7. Commit - Git commit per logical grouping moved

Standard Structure

Recommended Organization

project_root/
├── project.godot
├── assets/
│   ├── sprites/
│   │   ├── characters/
│   │   ├── enemies/
│   │   ├── items/
│   │   └── environment/
│   ├── audio/
│   │   ├── music/
│   │   ├── sfx/
│   │   └── voice/
│   ├── fonts/
│   ├── materials/
│   ├── shaders/
│   └── models/       # For 3D projects
├── scenes/
│   ├── characters/
│   ├── enemies/
│   ├── levels/
│   ├── ui/
│   └── components/
├── scripts/
│   ├── characters/
│   ├── enemies/
│   ├── components/
│   ├── managers/
│   └── utility/
├── resources/
│   ├── items/
│   ├── enemies/
│   └── abilities/
├── addons/           # Third-party plugins
└── docs/             # Documentation (optional)

What Gets Created

• Organized directory structure
• Moved files with preserved references
• Updated .tscn files with new paths
• Updated script preload() paths
• Updated project.godot autoloads
• Git commits documenting organization

Smart Analysis

Detects file types:

• Assets - .png, .jpg, .wav, .ogg, .ttf, .glb
• Scenes - .tscn, .scn
• Scripts - .gd, .cs
• Resources - .tres, .res
• Config - .cfg, .json, project.godot

Determines grouping:

• By type (sprites, scripts, scenes)
• By domain (characters, enemies, ui)
• By function (components, managers, utilities)

Integration

Works with:

• godot-organize-assets - Further organizes asset files
• godot-organize-scripts - Further organizes script files
• godot-organize-project (orchestrator) - Runs as part of full organization

Safety

• All file references preserved during moves
• Godot's .import files updated automatically
• Rollback on validation failure
• Original structure preserved in git history

When NOT to Use

Don't reorganize if:

• Project already has clear structure
• Mid-development sprint (bad timing)
• Custom structure intentionally different
• External tools rely on current paths

Path Updates

Script Updates

# Before
var scene = preload("res://player.tscn")

# After
var scene = preload("res://scenes/characters/player.tscn")

Scene Updates

# Before
[ext_resource path="res://player.gd" type="Script"]

# After
[ext_resource path="res://scripts/characters/player.gd" type="Script"]

Autoload Updates

# Before
[autoload]
GameManager="*res://game_manager.gd"

# After
[autoload]
GameManager="*res://scripts/managers/game_manager.gd"

Organization Strategies

By Type (Simple Projects)

Group all sprites together, all scripts together.

By Domain (Medium Projects)

Group by game concept (characters, enemies, levels).

By Feature (Large Projects)

Group by feature (combat system, inventory system).

Hybrid

Combine strategies (assets by type, scripts by domain).

Benefits

• Discoverability - Find files where you expect them
• Scalability - Structure supports growth
• Onboarding - New team members navigate easily
• Consistency - Same structure across projects
• Tooling - Tools work better with organized projects

Common Patterns

Before	After
player.gd in root	scripts/characters/player.gd
sprite.png in root	assets/sprites/characters/sprite.png
level.tscn in root	scenes/levels/level.tscn
item_data.tres in root	resources/items/item_data.tres

Configuration

Can be customized for:

• Different naming conventions
• Alternative structures (src/ instead of scripts/)
• Project-specific requirements
• Team preferences

Default follows Godot best practices and community standards.