godot

生成适用于生产环境且类型安全的 GDScript 2.0，面向 Godot 4.3+。所有生成的代码都必须遵循官方风格指南、严格静态类型和现代架构模式。

目的

此技能将所有 Godot 相关代码生成限制为：

• 仅限 Godot 4.3+ — 主动阻止 Godot 3 语法和已弃用的 API
• 严格静态类型 — 为每个变量、参数和返回值声明类型
• 官方 GDScript 风格指南 — 命名、格式、17 步代码排序
• 松耦合 — “向下调用，向上发送信号”，优先组合而非继承
• 数据驱动设计 — 使用 Resource 存储数据、Node 负责呈现、Manager 处理逻辑

适用时机

在任务涉及以下内容时启用：

• 编写或修改 GDScript 文件
• 设计 Godot 场景架构或节点树
• 实现游戏机制（移动、战斗、物品栏、AI）
• 构建 UI、存档／读档系统、程序化生成
• 将 Godot 3 代码迁移到 Godot 4

语法约束

以下要求不可妥协。违反会导致编译错误：

禁止（Godot 3／已弃用）	必须使用（Godot 4.3+）
yield	await
emit_signal("name")	signal_name.emit()
connect("signal", target, "method")	signal.connect(callable)
TileMap 节点	TileMapLayer 节点
File／Directory 类	FileAccess／DirAccess
deg2rad／rad2deg	deg_to_rad／rad_to_deg
stepify／rand_range／instance()	snapped／randf_range／instantiate()
export var／onready var	@export var／@onready var
KinematicBody2D	CharacterBody2D
move_and_slide(velocity)	velocity = ...; move_and_slide()

迁移代码时，加载 references/godot4-syntax.md 查看完整的弃用映射。

类型安全

每个声明都必须使用静态类型：

var speed := 400.0                                          # Inferred
var player_name: String = ""                                # Explicit
var enemies: Array[Enemy] = []                              # Typed array
func calculate_damage(base: float, mult: float) -> float:  # Params + return
func take_damage(amount: int) -> void:                      # Void explicit

命名和格式

加载 references/gdscript-style-guide.md 查看命名规范和格式规则。

始终适用的关键规则：

元素	规范	示例
文件	snake_case.gd	weapon_system.gd
类／节点	PascalCase	class_name NetworkManager
函数	snake_case()	func calculate_velocity():
信号	snake_case（过去时）	signal enemy_defeated
常量／枚举成员	CONSTANT_CASE	const MAX_SPEED := 600.0

格式：每行一条语句，使用英文布尔运算符（and／or／not），不加不必要的括号，多行条件使用双重缩进。

脚本结构（17 步排序）

每个脚本都必须严格遵循以下顺序：

 1. @tool, @icon          2. class_name           3. extends
 4. ## Docstring           5. signals              6. enums
 7. constants              8. static var           9. @export var
10. var (public → _private) 11. @onready var       12. _static_init()
13. static func            14. Virtual callbacks (_init → _ready → _process → _physics_process)
15. Public methods          16. Private methods     17. Inner classes

架构模式

加载 references/architecture-patterns.md，查看信号总线、状态机、实体模式和组合示例。

始终适用的决策树：

状态管理：

Needs _process() or node lifecycle? → Autoload
Just data/utilities/config?          → Static class (class_name + static var/func)

通信：

Parent → Child:     direct method calls
Child → Parent:     signals (emit up)
Sibling → Sibling:  signal bus or parent mediates
Cross-scene:        Autoload event bus

常见系统

加载 references/common-systems.md，查看 TileMapLayer、FileAccess、Resource、输入、摄像机、对象池和 UI 模式。

始终适用的关键约束：

• 使用 TileMapLayer，而非已弃用的 TileMap — 每个图层使用一个节点
• 使用 FileAccess/DirAccess，而非 File/Directory — 存档使用 user://，导出时 res:// 为只读
• 在导出的构建版本中使用 ResourceLoader 加载资源
• 使用 Resource（.tres）存储可移植数据 — 将数据与呈现分离

常见任务模式

玩家控制器（2D 平台游戏）

生成完整的 CharacterBody2D 脚本：导出的移动变量、包含 move_and_slide() 的 _physics_process、土狼时间、跳跃缓冲、基于枚举的状态跟踪，以及输入映射引用。

状态机

使用专用的 StateMachine 节点管理 State 子节点。每个状态都继承基类 State。通过信号进行状态转换。绝不使用基于字符串的状态比较。

存档／读档

所有存档都使用 user://。使用 FileAccess.open() 并检查错误。使用 JSON 或 ResourceSaver。绝不使用 File 类。

TileMap / 关卡设计

每个逻辑层使用一个 TileMapLayer。使用 get_cell_source_id() / set_cell()。通过代码进行程序化生成。

输出规则

1. 代码块 + 最多 2 句话的架构理由
2. 不要添加对话式填充内容
3. 注释解释原因，而不是内容
4. 始终指定文件路径
5. 适用时描述节点树：

Player (CharacterBody2D)
├── CollisionShape2D
├── Sprite2D
├── AnimationPlayer
└── Hurtbox (Area2D)
    └── CollisionShape2D

错误恢复

提供了 Godot 3 代码 → 指出已弃用的元素，提供现代等效写法，用 1 句话说明迁移方式，并生成修正后的代码。

请求在架构上不合理 → 使用恰当的模式生成代码，用 1 句话指出问题；仅在问题会导致实际扩展性问题时才建议替代方案。

切勿

• 切勿输出 Godot 3 语法（yield、emit_signal()、基于字符串的 connect()、TileMap、File、Directory）
• 能使用静态类型时，切勿使用动态类型
• 切勿使用驼峰命名法、匈牙利命名法或符号布尔运算符（&&、||、!）
• 切勿使用 get_parent() 或 get_node("../Sibling") 进行跨节点通信
• 切勿为纯工具/数据建议使用 Autoload；应使用静态类
• 切勿在同一行中同时编写条件和执行语句
• 切勿使用反斜杠进行换行续写；应使用括号
• 在多行条件中，切勿将 and/or 放在行尾
• 对于不返回任何内容的函数，切勿省略 -> void
• 切勿编写解释代码做了什么的注释；只解释原因
• 未先阅读用户现有项目上下文时，切勿生成代码