AGENT SKILL

godot-split-scripts

用于 Godot 脚本超过 150 行或承担多个职责时。 检测做了太多事情的脚本(玩家移动 + 战斗 + 背包 + UI)。 自动按照单一职责原则拆分为专注的脚本, 精确保留原有行为,并为每次拆分创建 git 提交。

License 许可
MIT
最近更新
2026-11-12
Stars
★ 3
Forks
1

01 前言 Front Matter

name
godot-split-scripts
type
tool
author
Asreonn
license
MIT
outputs
拆分后的单一职责脚本、保留的原有行为、每次拆分的 git 提交
version
3.0.0
audience
[ "developers" ]
behavior
{ "validation": true, "git_commits": true, "auto_rollback": true }
category
game-development
homepage
https://github.com/asreonn/godot-superpowers#readme
keywords
[ "godot", "script-splitting", "refactoring", "single-responsibility", "component-pattern", "gdscript", "code-organization", "monolithic-scripts" ]
execution
全自动,包含行为验证
platforms
[ "macos", "linux", "windows" ]
difficulty
intermediate
repository
https://github.com/asreonn/godot-superpowers
description
用于 Godot 脚本超过 150 行或承担多个职责时。 检测做了太多事情的脚本(玩家移动 + 战斗 + 背包 + UI)。 自动按照单一职责原则拆分为专注的脚本, 精确保留原有行为,并为每次拆分创建 git 提交。
displayName
拆分臃肿脚本
integration
属于 godot-refactor 编排器的一部分,可与 godot-add-signals 配合使用
permissions
{ "git": true, "filesystem": { "read": [ ".gd", ".tscn" ], "write": [ ".gd", ".tscn" ] } }
requirements
Git 仓库、Godot 4.x

03 SKILL.md 正文

拆分臃肿脚本

核心原则

一个脚本,一个职责。 超过 150 行的脚本通常承担了太多事情。

本技能的功能

找到类似这样的脚本:

# player.gd - 500 行
class_name Player
extends CharacterBody2D

# 移动(第 1-100 行)
func _physics_process(delta): ...
func handle_input(): ...
func move(): ...

# 战斗(第 101-200 行)
func take_damage(amount): ...
func attack(): ...
func die(): ...

# 背包(第 201-350 行)
func add_item(item): ...
func remove_item(item): ...
func use_item(item): ...

# UI(第 351-500 行)
func update_health_bar(): ...
func show_inventory(): ...

转换为:

# player.gd - 50 行(协调器)
class_name Player
extends CharacterBody2D

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

# 委托给各组件

检测模式

识别以下特征的脚本:

  • 超过 150 行
  • 有多个逻辑分区(如注释 "# 移动"、"# 战斗")
  • 处理不相关的职责(物理 + UI + 数据管理)
  • 有大量用于不同系统的导出变量
  • 混合了不同的抽象层级

使用场景

你正在添加新功能

向已经很大的脚本中添加新功能只会让情况更糟。

你正在调试复杂代码

大型脚本难以理解和测试。

你正在为团队协作做准备

更小的脚本减少合并冲突,改善代码审查体验。

你正在添加测试

单一职责的脚本更容易进行隔离测试。

流程

  1. 扫描 - 找到超过 150 行的脚本
  2. 分析 - 识别逻辑分组和职责
  3. 拆分 - 将每个职责提取到独立脚本
  4. 保留 - 确保行为完全不变
  5. 验证 - 运行测试确认没有回归
  6. 提交 - 每次拆分操作创建 git 提交

示例转换

之前(player.gd - 300 行):

extends CharacterBody2D

const SPEED = 300.0
const JUMP_VELOCITY = -400.0

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

func _physics_process(delta):
    # 移动逻辑(50 行)
    ...

func take_damage(amount):
    # 战斗逻辑(30 行)
    ...

func add_item(item):
    # 背包逻辑(40 行)
    ...

func update_ui():
    # UI 逻辑(30 行)
    ...

之后(player.gd - 30 行):

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)

创建的新文件:

  • movement_component.gd - 处理 SPEED、JUMP_VELOCITY、_physics_process
  • combat_component.gd - 处理 health、take_damage、die
  • inventory_component.gd - 处理 inventory 数组、add_item、remove_item
  • ui_component.gd - 处理 update_health_bar、show_inventory

拆分策略

按领域拆分

按游戏概念拆分(移动、战斗、背包)。

按层级拆分

按抽象层级拆分(输入处理、状态管理、渲染)。

按职责拆分

按变更原因不同来拆分。

创建的内容

  • 具有单一明确目的的组件脚本
  • 保留在正确位置的 @export 变量
  • 用于组件间通信的 Signal 连接
  • 更新后的场景文件,包含新的组件 Node
  • 记录每次拆分的 git 提交

智能分析

识别清晰的边界:

  • 操作相同变量的函数
  • 注释指示的逻辑分组
  • 相关功能(所有 UI、所有物理)

保留集成:

  • 主脚本委托给各组件
  • 需要时通过 Signal 连接组件
  • 公共 API 保持兼容

集成

可搭配使用:

  • godot-extract-to-scenes - 提取场景后再拆分
  • godot-add-signals - 为组件间通信添加 Signal
  • godot-refactor(编排器)- 作为完整重构的一部分运行

安全性

  • 精确保留原有行为(无功能变更)
  • 每次拆分后运行验证测试
  • 测试失败时自动回滚
  • git 历史保留原始脚本

何时不使用

以下情况不要拆分:

  • 脚本低于 150 行且职责单一
  • 脚本有单一明确的职责
  • 拆分后会使代码更难理解
  • 函数紧密耦合且无法分离

保持简单的事情简单。

阈值配置

默认值:150 行(Godot 最佳实践)

可根据以下因素调整:

  • 团队偏好
  • 脚本复杂度
  • 领域需求

低于阈值的脚本会被跳过,除非它们明显承担了多个职责。

04 同仓库更多 Skills

welflau
welflau/ai-dev-system

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

测试与质量前端开发
★ 3
welflau
welflau/ai-dev-system

internal-comms

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

邮件与沟通
★ 3
welflau
welflau/ai-dev-system

web-artifacts-builder

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

前端开发
★ 3
welflau
welflau/ai-dev-system

frontend-design

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

设计师前端开发视觉设计
★ 3
welflau
welflau/ai-dev-system

algorithmic-art

Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.

视觉设计
★ 3
welflau
welflau/ai-dev-system

theme-factory

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

视觉设计
★ 3