gdscript-codegen

GDScript 代码生成 Skill

用途：AI 生成高质量 GDScript 代码的规范和模板
版本：v1.0 · 2026-04-22
适用引擎：Godot 4.5/4.6

---

一、GDScript 4.x 核心规范

1.1 类型系统

Godot 4.x 使用强类型 GDScript，AI 生成代码时必须遵循：

# ✅ 推荐：显式类型标注
var health: int = 100
var speed: float = 10.0
var player_name: String = "Player"
var position: Vector3 = Vector3.ZERO
var enemies: Array[Node3D] = []
var weapon_data: Dictionary = {}

# ✅ 推荐：函数参数和返回值标注
func take_damage(amount: int) -> void:
    health -= amount

func get_health_ratio() -> float:
    return float(health) / float(max_health)

# ❌ 避免：无类型标注（编译器警告）
var health = 100  # 类型推断，但不推荐

1.2 类型推断陷阱

# ❌ 错误：for 循环迭代变量无法推断
for x in [-1.0, 1.0]:
    var pos := center + Vector2(x, 0) * radius  # 报错！

# ✅ 正确：显式标注迭代变量
for x: float in [-1.0, 1.0]:
    var pos := center + Vector2(x, 0) * radius

# ❌ 错误：字典值类型无法推断
var data = {"a": 1, "b": 2}
var value := data["a"]  # 报错！

# ✅ 正确：显式标注或使用 as
var value: int = data["a"]
var value := data["a"] as int

1.3 信号声明

# Godot 4.x 信号语法
signal health_changed(current: int, maximum: int)
signal died
signal damage_taken(amount: int, remaining: int)
signal weapon_changed(weapon_index: int)

1.4 导出变量

# 基础类型
@export var health: int = 100
@export var speed: float = 10.0

# 范围限制
@export_range(0, 100, 1) var health: int = 100
@export_range(0.0, 10.0, 0.1) var speed: float = 5.0

# 枚举
@export_enum("Easy", "Normal", "Hard") var difficulty: int = 1

# 资源
@export var weapon_resource: WeaponResource
@export var projectile_scene: PackedScene

# 分组
@export_group("Combat")
@export var damage: int = 10
@export var fire_rate: float = 0.5

1.5 @onready 和节点引用

# ✅ 推荐：@onready 延迟初始化
@onready var animation_player: AnimationPlayer = $AnimationPlayer
@onready var health_bar: ProgressBar = $UI/HealthBar

# ✅ 推荐：运行时获取（更灵活）
var player: Node3D
func _ready() -> void:
    player = get_tree().get_first_node_in_group("player")

# ❌ 避免：硬编码路径（易断裂）
var health_label = $"../UI/GameHUD/HealthPanel/HealthLabel"