AGENT SKILL

godot-add-signals

当 Godot 代码中存在通过 get_node()、get_parent() 或直接引用产生的紧耦合依赖时使用。 检测耦合模式并将其转换为基于 Signal 的通信方式。组件变得独立、可测试且可复用。 在改进架构的同时精确保留原有行为。

使用场景测试与质量
License 许可
MIT
最近更新
2026-11-12
Stars
★ 3
Forks
1

01 前言 Front Matter

name
godot-add-signals
type
tool
author
Asreonn
license
MIT
outputs
Signal 定义、Signal 连接、解耦组件、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", "signals", "decoupling", "get-node", "get-parent", "architecture", "gdscript", "loose-coupling" ]
execution
全自动执行,保留原有行为
platforms
[ "macos", "linux", "windows" ]
difficulty
intermediate
repository
https://github.com/asreonn/godot-superpowers
description
当 Godot 代码中存在通过 get_node()、get_parent() 或直接引用产生的紧耦合依赖时使用。 检测耦合模式并将其转换为基于 Signal 的通信方式。组件变得独立、可测试且可复用。 在改进架构的同时精确保留原有行为。
displayName
用 Signal 替换耦合
integration
godot-refactor 编排器的一部分,可与 godot-split-scripts 配合使用
permissions
{ "git": true, "filesystem": { "read": [ ".gd", ".tscn" ], "write": [ ".gd", ".tscn" ] } }
requirements
Git 仓库, Godot 4.x

03 SKILL.md 正文

用 Signal 替换耦合

核心原则

组件之间通过 Signal 通信,而非直接引用。 耦合会使代码变得脆弱且难以测试。

本技能的功能

查找如下模式:

# player.gd
func take_damage(amount):
    health -= amount
    get_node("../UI/HealthBar").update(health)  # TIGHT COUPLING
    get_parent().get_node("ScoreManager").reduce_score()  # FRAGILE PATH

转换为:

# player.gd
signal health_changed(new_health)

func take_damage(amount):
    health -= amount
    health_changed.emit(health)  # SIGNAL - NO COUPLING
# main.gd (or scene setup)
func _ready():
    player.health_changed.connect(ui.health_bar.update)
    player.health_changed.connect(score_manager.on_player_damaged)

检测模式

识别以下模式:

  • get_node("../path") - 向上路径导航
  • get_parent().something - 父节点依赖
  • find_child("name") - 运行时搜索
  • has_method() - 紧接口耦合
  • 直接的 owner 引用导致的循环依赖

使用场景

重构遗留代码

旧代码中存在通过 get_node 链产生的意大利面条式依赖。

构建可测试系统

希望在没有完整场景树的情况下独立测试组件。

创建可复用组件

组件应该能在不同上下文中使用而无需修改。

遇到脆弱代码

场景结构的变更会破坏无关功能。

流程

  1. 扫描 - 查找所有 get_node()、get_parent()、find_child() 的使用
  2. 分析 - 识别 Node 之间的信息流
  3. 定义 Signal - 为通信创建 Signal 定义
  4. 替换 - 将直接调用转换为 Signal 发射
  5. 连接 - 在合适的编排点连接 Signal
  6. 验证 - 确保行为完全保留
  7. 提交 - 每次解耦操作对应一次 git 提交

转换示例

转换前(紧耦合):

# enemy.gd
extends CharacterBody2D

func die():
    var player = get_node("../Player")  # FRAGILE PATH
    player.add_score(100)

    var audio = get_parent().get_node("AudioManager")  # TIGHT COUPLING
    audio.play_sound("enemy_death")

    queue_free()

转换后(基于 Signal):

# enemy.gd
extends CharacterBody2D

signal died(score_value: int)
signal death_sound_requested(sound_name: String)

func die():
    died.emit(100)
    death_sound_requested.emit("enemy_death")
    queue_free()
# main.gd (orchestrator)
func _ready():
    for enemy in enemies:
        enemy.died.connect(player.add_score)
        enemy.death_sound_requested.connect(audio_manager.play_sound)

Signal 模式

一对多

一个发射器,多个监听器(生命值变化 → 更新 UI + 保存游戏 + 成就检查)。

事件广播

宣布某事发生,而不关心谁在监听。

请求-响应

请求服务而不知道提供者是谁(request_ammo → 由谁处理弹药就由谁响应)。

状态变更通知

状态变更时发出通知(entered_water、jumped、landed)。

创建的内容

  • 带类型参数的 Signal 定义
  • 在适当位置的 Signal 发射
  • 在编排脚本中的 Signal 连接
  • Signal 用途和参数的文档说明
  • 记录每次解耦的 git 提交

智能分析

识别耦合类型:

  • 结构耦合 - 依赖于场景树结构
  • 接口耦合 - 调用其他 Node 的特定方法
  • 数据耦合 - 访问其他 Node 的数据

选择适当的解决方案:

  • Signal 用于事件和通知
  • 依赖注入用于服务
  • 场景组合用于可复用组件

集成

可与以下技能配合使用:

  • godot-split-scripts - 先拆分,再解耦
  • godot-extract-to-scenes - 提取场景,再添加 Signal
  • godot-refactor(编排器) - 作为完整重构的一部分运行

安全性

  • 精确保留原有行为
  • Signal 连接自动测试
  • 验证失败时回滚
  • 原始耦合保留在 git 历史中

不应使用的情况

以下情况不需要添加 Signal:

  • 父子关系是有意的设计
  • 组件确实需要特定的父类型
  • 耦合在同一职责边界内
  • 添加 Signal 会使代码更复杂而非更简洁

合理耦合的示例:

  • UI 按钮调用父对话框的关闭方法
  • 子 Node 访问父节点的导出属性
  • 组件访问 owner 的公共 API

Signal 命名规范

事件(过去时):

  • health_changed
  • item_collected
  • enemy_died

请求(祈使语气):

  • damage_requested
  • play_sound
  • spawn_particle

状态变更:

  • entered_state
  • exited_state
  • state_changed

优势

  • 可测试性 - 无需完整场景树即可测试组件
  • 可复用性 - 组件可在不同上下文中工作
  • 灵活性 - 添加/移除监听器无需修改发射器
  • 可维护性 - 修改不会破坏远处的代码
  • 清晰性 - Signal 连接展示系统架构

常见转换

转换前(耦合) 转换后(基于 Signal)
get_node("../Player").damage() damage_dealt.emit() → player 监听
get_parent().update_ui() ui_update_requested.emit() → UI 监听
owner.score += 10 score_changed.emit(10) → owner 监听
find_child("Camera").shake() screen_shake_requested.emit() → camera 监听

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