Combat (lines 101-200)

func take_damage(amount): ... func attack(): ... func die(): ...

Inventory (lines 201-350)

func add_item(item): ... func remove_item(item): ... func use_item(item): ...

UI (lines 351-500)

func update_health_bar(): ... func show_inventory(): ...


Transforms to:
```gdscript
# player.gd - 50 lines (orchestrator)
class_name Player
extends CharacterBody2D

@onready var movement = $MovementComponent
@onready var combat = $CombatComponent
@onready var inventory = $InventoryComponent
@onready var ui = $UIComponent

# Delegates to components

Detection Patterns

Identifies scripts that:

Exceed 150 lines
Have multiple logical sections (comments like "# Movement", "# Combat")
Handle unrelated concerns (physics + UI + data management)
Have many exported variables for different systems
Mix different levels of abstraction

When to Use

You're Building New Features

Adding new functionality to already-large script makes it worse.

You're Debugging Complex Code

Large scripts are hard to reason about and test.

You're Preparing for Team Work

Smaller scripts reduce merge conflicts and improve code review.

You're Adding Tests

Single-responsibility scripts are easier to test in isolation.

Process

Scan - Find scripts exceeding 150 lines
Analyze - Identify logical groupings and responsibilities
Split - Extract each responsibility to its own script
Preserve - Ensure behavior remains exactly the same
Validate - Run tests to confirm no regressions
Commit - Git commit per split operation

Example Transformation

Before (player.gd - 300 lines):

extends CharacterBody2D

const SPEED = 300.0
const JUMP_VELOCITY = -400.0

var health = 100
var max_health = 100
var inventory = []

func _physics_process(delta):
    # Movement logic (50 lines)
    ...

func take_damage(amount):
    # Combat logic (30 lines)
    ...

func add_item(item):
    # Inventory logic (40 lines)
    ...

func update_ui():
    # UI logic (30 lines)
    ...

After (player.gd - 30 lines):

extends CharacterBody2D

@onready var movement: MovementComponent = $MovementComponent
@onready var combat: CombatComponent = $CombatComponent
@onready var inventory: InventoryComponent = $InventoryComponent
@onready var ui: UIComponent = $UIComponent

func _ready():
    combat.health_changed.connect(ui.update_health_bar)
    inventory.item_added.connect(ui.update_inventory)

New Files Created:

movement_component.gd - Handles SPEED, JUMP_VELOCITY, _physics_process
combat_component.gd - Handles health, take_damage, die
inventory_component.gd - Handles inventory array, add_item, remove_item
ui_component.gd - Handles update_health_bar, show_inventory

Split Strategies

By Domain

Split by game concepts (movement, combat, inventory).

By Layer

Split by abstraction (input handling, state management, rendering).

By Responsibility

Split by what changes for different reasons.

What Gets Created

Component scripts with single clear purpose
Preserved @export variables in correct locations
Signal connections for component communication
Updated scene files with new component nodes
Git commits documenting each split

Smart Analysis

Identifies clear boundaries:

Functions that operate on same variables
Logical groupings indicated by comments
Related functionality (all UI, all physics)

Preserves integration:

Main script delegates to components
Signals connect components when needed
Public API remains compatible

Integration

Works with:

godot-extract-to-scenes - Split after extracting scenes
godot-add-signals - Add signals for component communication
godot-refactor (orchestrator) - Runs as part of full refactoring

Safety

Behavior preserved exactly (no functional changes)
Validation tests run after each split
Auto-rollback on test failure
Git history preserves original script

When NOT to Use

Don't split if:

Script under 150 lines and focused
Script has single clear responsibility
Splitting would make code harder to understand
Functions are tightly coupled and can't be separated

Keep simple things simple.

Threshold Configuration

Default: 150 lines (Godot best practice)

Can be adjusted based on:

Team preferences
Script complexity
Domain requirements

Scripts under threshold are skipped unless they have obvious multiple responsibilities.

godot-split-scripts

Split Monolithic Scripts

Core Principle

What This Skill Does