gdscript-codegen

SKILL.md 节选

# GDScript 代码生成 Skill

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

---

## 一、GDScript 4.x 核心规范

### 1.1 类型系统

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

```gdscript
# ✅ 推荐：显式类型标注
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 类型推断陷阱

```gdscript
# ❌ 错误：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 信号声明

```gdscript
# 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 导出变量

```gdscript
# 基础类型
@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 和节点引用

```gdscript
# ✅ 推荐：@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"
```

---

## 二、常用代码模板

### 2.1 组件脚本模板

```gdscript
# health_component.gd
extends Node
class_name HealthComponent

## 生命值组件 - 可挂载到任何需要 HP 的实体

signal health_changed(current: int, maximum: int)
signal died
signal damage_taken(amount: int, remaining: int)

@export var max_health: int = 100
@export var invincible: bool = false
@export var invincible_time: float = 0.0

var current_health: int
var is_dead: bool = false
var _invincible_timer: float = 0.0

func _ready() -> void:
    current_health = max_health

func take_damage(amount: int) -> void:
    if is_dead or invincible:
        return
    if _invincible_timer > 0:
        return
    
    current_health = max(0, current_health - amount)
    damage_taken.emit(amount, current_health)
    health_changed.emit(current_health, max_health)
    
    if current_health <= 0:
        is_dead = true
        died.emit()

func heal(amount: int) -> void:
    if is_dead:
        return
    current_health = min(max_health, current_health + amount)
    health_changed.emit(current_health, max_health)
```

### 2.2 Manager 脚本模板

```gdscript
# arena_manager.gd
extends Node
class_name ArenaManager

## 竞技场管理器 - 处理限时刷分模式的核心逻辑

signal arena_started
signal arena_ended(final_score: int, rating: String)
signal score_changed(score: int, combo: int)
signal time_changed(remaining: float)

@export var match_duration: float = 60.0
@export var combo_window: float = 3.0

var _score: int = 0
var _combo: int = 0
var _time_remaining: float = 0.0

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 1 个文件，合计 9.9 KiB