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

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.