| name | godot-organize-scripts |
| version | 3.0.0 |
| displayName | 整理脚本文件 |
| description | 当 Godot 项目的脚本分散且没有清晰组织时使用。检测脚本并按类别 （角色、敌人、组件、管理器、工具类）整理。创建清晰的结构以展示 架构层级和关系。保留所有引用和 class_name 声明。
|
| 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 | 整理后的脚本目录、移动的文件并保留引用、git 提交 |
| requirements | Git 仓库、Godot 4.x |
| execution | 全自动，保留引用 |
| integration | godot-organize-project 编排器的一部分，与 godot-split-scripts 协同工作 |
整理脚本文件
核心原则
脚本按架构层级和职责整理。 代码结构揭示设计。
本技能的功能
查找类似这样的脚本目录：
scripts/
├── player.gd
├── enemy.gd
├── health_component.gd
├── game_manager.gd
├── utility.gd
├── inventory.gd
├── ui_manager.gd
└── ...（50 多个脚本）
转换为：
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
检测模式
识别：
- 按架构角色分类的脚本
- 基类 vs 实现类
- 可复用组件 vs 特定实体
- 系统/管理器脚本
- 工具/辅助脚本
何时使用
代码库增长
脚本不断增多，组织已经丢失。
理解架构
希望文件夹结构反映设计。
团队新人入职
新开发者需要快速导航代码。
大规模重构之前
清晰的组织使重构更安全。
流程
- 扫描 - 清点所有 .gd 文件并分析内容
- 分类 - 根据角色和命名确定类别
- 分组 - 查找相关脚本（继承、依赖）
- 规划 - 创建目标目录结构
- 移动 - 重新定位脚本，保留引用
- 更新 - 修复 preload()、extends、场景中的路径
- 验证 - 确保所有脚本正确加载
- 提交 - 每个类别移动后进行 git 提交
组织结构
角色
玩家和 NPC 的脚本。
characters/
├── player.gd
├── npc.gd
├── character_base.gd
└── character_state_machine.gd
敌人
敌人实体和 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/
├── health_component.gd
├── movement_component.gd
├── combat_component.gd
├── inventory_component.gd
└── hitbox_component.gd
管理器
单例模式的管理器脚本。
managers/
├── game_manager.gd
├── audio_manager.gd
├── scene_manager.gd
├── save_manager.gd
└── input_manager.gd
系统
游戏系统（背包、任务、对话）。
systems/
├── inventory_system.gd
├── quest_system.gd
├── dialog_system.gd
└── crafting_system.gd
UI
UI 相关脚本。
ui/
├── main_menu.gd
├── pause_menu.gd
├── hud.gd
├── inventory_ui.gd
└── widgets/
├── health_bar.gd
└── button_hover.gd
工具类
辅助和工具脚本。
utility/
├── constants.gd
├── math_helper.gd
├── vector_utils.gd
└── debug_draw.gd
Resource（脚本定义）
自定义 Resource 类定义。
resources/
├── item_data.gd
├── enemy_stats.gd
├── ability_definition.gd
└── level_config.gd
分类逻辑
角色脚本
- 名称包含 "player"、"npc"、"character"
- 继承 CharacterBody2D 或自定义角色基类
- 处理玩家/NPC 特定逻辑
敌人脚本
- 名称包含 "enemy"、"monster"、怪物类型
- 继承敌人基类或包含 AI 逻辑
- 处理敌对实体行为
组件脚本
- 名称以 "_component" 结尾
- 设计用于跨实体复用
- 单一职责（生命值、移动等）
管理器脚本
- 名称以 "_manager" 结尾
- 通常为自动加载的单例
- 管理全局状态或服务
系统脚本
- 名称以 "_system" 结尾
- 处理游戏机制（背包、任务）
- 领域特定逻辑
工具脚本
- 名称类似 "helper"、"utils"、"constants"
- 无状态的辅助函数
- 数学或字符串工具
创建的内容
- 按类别整理的脚本目录
- 专门分组的子目录
- 移动的脚本并保留引用
- 更新的 class_name 引用
- 更新 project.godot 中的自动加载路径
- 每个类别的 git 提交
智能分析
检测关系：
- 继承（基类和实现类）
- 依赖（preload 其他脚本的脚本）
- 命名模式（约定揭示用途）
保持内聚性：
- 相关脚本保持在一起
- 基类 + 派生类在同一类别
- 组件族分组
引用更新
脚本预加载
# 之前
const EnemyScene = preload("res://enemy.gd")
# 之后
const EnemyScene = preload("res://scripts/enemies/enemy.gd")
类继承
# 之前
extends "res://character_base.gd"
# 之后
extends "res://scripts/characters/character_base.gd"
场景脚本附加
[ext_resource path="res://player.gd" type="Script"]
[ext_resource path="res://scripts/characters/player.gd" type="Script"]
集成
协同工作：
- godot-split-scripts - 先拆分，再整理
- godot-organize-files - 基础文件整理
- godot-organize-project（编排器）- 完整项目整理
安全性
- 保留所有脚本引用
- class_name 声明正常工作
- 自动加载路径自动更新
- 验证失败时回滚
- 原始结构保存在 git 历史中
何时不使用
不要在以下情况重新整理：
- 脚本已经组织良好
- 架构要求自定义结构
- 冲刺中期（时机不佳）
- 外部工具依赖当前路径
收益
- 可发现性 - 按职责找到脚本
- 架构可见性 - 结构反映设计
- 新人入职 - 新开发者轻松导航
- 重构 - 清晰的变更边界
- 测试 - 更容易按层测试
命名约定
可选：在整理时重命名
PlayerController.gd → player_controller.gd（snake_case）EnemyAI.gd → enemy_ai.gd
Godot 惯例偏好使用 snake_case 作为文件名。
架构层级
典型层级结构：
- 实体 - characters/、enemies/
- 组件 - components/
- 系统 - systems/、managers/
- UI - ui/
- 工具类 - utility/
组织方式反映依赖方向（工具类不依赖任何东西，实体依赖所有东西）。
常见转换
| 之前 | 之后 |
|---|
scripts/ 中的 player.gd | scripts/characters/player.gd |
scripts/ 中的 enemy_ai.gd | scripts/enemies/ai/enemy_ai.gd |
混杂的 health_component.gd | scripts/components/health_component.gd |
根目录中的 game_manager.gd | scripts/managers/game_manager.gd |
分散的 utils.gd | scripts/utility/math_helper.gd |
配置
可针对以下内容自定义：
- 不同的架构模式（MVC、类 ECS 等）
- 团队特定的类别
- 领域特定的分组
- 整理深度（扁平 vs 深层级）
默认值遵循 Godot 基于组件的架构模式。
