godot-organize-scripts

name	godot-organize-scripts
version	3.0.0
displayName	Organize Script Files
description	Use when Godot project has scripts scattered without clear organization. Detects scripts and organizes them by category (characters, enemies, components, managers, utilities). Creates clear structure showing architectural layers and relationships. Preserves all references and class_name declarations.
author	Asreonn
license	MIT
category	game-development
type	tool
difficulty	beginner
audience	["developers"]
keywords	["godot","script-organization","gdscript","file-structure","code-architecture","components","managers","best-practices"]
platforms	["macos","linux","windows"]
repository	https://github.com/asreonn/godot-superpowers
homepage	https://github.com/asreonn/godot-superpowers#readme
permissions	{"filesystem":{"read":[".gd"],"write":["*"],"move":true,"delete":false},"git":true}
behavior	{"auto_rollback":true,"validation":true,"git_commits":true}
outputs	Organized script directories, 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 godot-split-scripts

Organize Script Files

Core Principle

Scripts organized by architectural layer and responsibility. Code structure reveals design.

What This Skill Does

Finds script directories like:

scripts/
├── player.gd
├── enemy.gd
├── health_component.gd
├── game_manager.gd
├── utility.gd
├── inventory.gd
├── ui_manager.gd
└── ... (50 more scripts)

Transforms to:

scripts/
├── characters/
│   ├── player.gd
│   └── character_base.gd
├── enemies/
│   ├── enemy.gd
│   ├── goblin.gd
│   └── enemy_ai.gd
├── components/
│   ├── health_component.gd
│   ├── movement_component.gd
│   └── combat_component.gd
├── managers/
│   ├── game_manager.gd
│   ├── ui_manager.gd
│   └── audio_manager.gd
├── systems/
│   └── inventory.gd
└── utility/
    ├── math_helper.gd
    └── constants.gd

Detection Patterns

Identifies:

• Scripts by architectural role
• Base classes vs implementations
• Reusable components vs specific entities
• System/manager scripts
• Utility/helper scripts

When to Use

Growing Codebase

Scripts have multiplied and organization is lost.

Understanding Architecture

Want folder structure to reflect design.

Team Onboarding

New developers need to navigate code quickly.

Before Major Refactoring

Clean organization makes refactoring safer.

Process

1. Scan - Inventory all .gd files and analyze content
2. Classify - Determine category based on role and naming
3. Group - Find related scripts (inheritance, dependencies)
4. Plan - Create target directory structure
5. Move - Relocate scripts preserving references
6. Update - Fix paths in preload(), extends, scenes
7. Validate - Ensure all scripts load correctly
8. Commit - Git commit per category moved

Organization Structure

Characters

Scripts for player and NPCs.

characters/
├── player.gd
├── npc.gd
├── character_base.gd
└── character_state_machine.gd

Enemies

Scripts for enemy entities and AI.

enemies/
├── enemy_base.gd
├── goblin.gd
├── orc.gd
├── ai/
│   ├── enemy_ai.gd
│   ├── patrol_ai.gd
│   └── chase_ai.gd
└── behaviors/
    ├── attack_behavior.gd
    └── flee_behavior.gd

Components

Reusable component scripts.

components/
├── health_component.gd
├── movement_component.gd
├── combat_component.gd
├── inventory_component.gd
└── hitbox_component.gd

Managers

Singleton-style manager scripts.

managers/
├── game_manager.gd
├── audio_manager.gd
├── scene_manager.gd
├── save_manager.gd
└── input_manager.gd

Systems

Game systems (inventory, quests, dialog).

systems/
├── inventory_system.gd
├── quest_system.gd
├── dialog_system.gd
└── crafting_system.gd

UI

UI-specific scripts.

ui/
├── main_menu.gd
├── pause_menu.gd
├── hud.gd
├── inventory_ui.gd
└── widgets/
    ├── health_bar.gd
    └── button_hover.gd

Utility

Helper and utility scripts.

utility/
├── constants.gd
├── math_helper.gd
├── vector_utils.gd
└── debug_draw.gd

Resources (Script Definitions)

Custom Resource class definitions.

resources/
├── item_data.gd
├── enemy_stats.gd
├── ability_definition.gd
└── level_config.gd

Classification Logic

Character Scripts

• Names contain "player", "npc", "character"
• Extend CharacterBody2D or custom character base
• Handle player/NPC-specific logic

Enemy Scripts

• Names contain "enemy", "monster", mob types
• Extend enemy base or have AI logic
• Handle hostile entity behavior

Component Scripts

• Names end with "_component"
• Designed for reuse across entities
• Single responsibility (health, movement, etc.)

Manager Scripts

• Names end with "_manager"
• Often autoloaded singletons
• Manage global state or services

System Scripts

• Names end with "_system"
• Handle game mechanics (inventory, quests)
• Domain-specific logic

Utility Scripts

• Names like "helper", "utils", "constants"
• Stateless helper functions
• Mathematical or string utilities

What Gets Created

• Organized script directories by category
• Subdirectories for specialized groupings
• Moved scripts with preserved references
• Updated class_name references
• Updated autoload paths in project.godot
• Git commits per category

Smart Analysis

Detects relationships:

• Inheritance (base classes with implementations)
• Dependencies (scripts that preload others)
• Naming patterns (conventions reveal purpose)

Maintains cohesion:

• Related scripts stay together
• Base + derived classes in same category
• Component families grouped

Reference Updates

Script Preloads

# Before
const EnemyScene = preload("res://enemy.gd")

# After
const EnemyScene = preload("res://scripts/enemies/enemy.gd")

Class Extends

# Before
extends "res://character_base.gd"

# After
extends "res://scripts/characters/character_base.gd"

Scene Script Attachments

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

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

Integration

Works with:

• godot-split-scripts - Split first, then organize
• godot-organize-files - Base file organization
• godot-organize-project (orchestrator) - Full project organization

Safety

• All script references preserved
• class_name declarations work correctly
• Autoload paths updated automatically
• Rollback on validation failure
• Original structure in git history

When NOT to Use

Don't reorganize if:

• Scripts already well organized
• Custom structure required by architecture
• Mid-sprint (bad timing)
• External tools rely on current paths

Benefits

• Discoverability - Find scripts by responsibility
• Architecture Visibility - Structure reflects design
• Onboarding - New developers navigate easily
• Refactoring - Clear boundaries for changes
• Testing - Easier to test by layer

Naming Conventions

Optional: Rename during organization

• PlayerController.gd → player_controller.gd (snake_case)
• EnemyAI.gd → enemy_ai.gd

Godot convention prefers snake_case for file names.

Architecture Layers

Typical hierarchy:

1. Entities - characters/, enemies/
2. Components - components/
3. Systems - systems/, managers/
4. UI - ui/
5. Utilities - utility/

Organization reflects dependency direction (utilities depend on nothing, entities depend on everything).

Common Transformations

Before	After
player.gd in scripts/	scripts/characters/player.gd
enemy_ai.gd in scripts/	scripts/enemies/ai/enemy_ai.gd
health_component.gd mixed	scripts/components/health_component.gd
game_manager.gd in root	scripts/managers/game_manager.gd
utils.gd scattered	scripts/utility/math_helper.gd

Configuration

Can be customized for:

• Different architectural patterns (MVC, ECS-like, etc.)
• Team-specific categories
• Domain-specific groupings
• Depth of organization (flat vs deep)

Defaults follow Godot component-based architecture patterns.