Godot Dev Guide Skill

Godot 4.x 游戏开发完整指南，专为 AI 辅助开发设计。

核心原则

1. 文件格式差异（最重要！）

.gd → GDScript 代码（完整语言）
.tscn → 场景序列化（严格格式，非 GDScript）
.tres → 资源序列化（严格格式，非 GDScript）

⚠️ AI 陷阱：混淆 GDScript 与资源格式
gdscript

❌ 错误写法 in .tres/.tscn

script = preload(res://script.gd)
var items = [1, 2, 3]

✅ 正确写法 in .tres/.tscn

[ext_resource type=Script path=res://script.gd id=1] script = ExtResource(1) items = Arrayint

2. 类型系统（始终使用）

gdscript

变量类型

var health: int = 100
var speed: float = 200.0
var items: Array[Item] = []
var stats: Dictionary = {}

函数签名

func calculate_damage(base: int, multiplier: float) -> int: return int(base * multiplier)

3. 架构模式

组合优先于继承
信号用于解耦通信
资源用于数据配置
自动加载用于全局系统

---

快速参考

项目结构

res://
├── project.godot
├── scenes/ # .tscn 场景
│ ├── player/
│ ├── enemies/
│ └── ui/
├── scripts/ # .gd 脚本
├── assets/ # 资源文件
├── autoload/ # 单例脚本
├── resources/ # .tres 资源
└── test/ # 测试

常用节点

2D	3D	用途
CharacterBody2D	CharacterBody3D	玩家/NPC 移动
RigidBody2D

RigidBody3D | 物理模拟 | | Area2D | Area3D | 碰撞检测（无物理） | | Sprite2D | MeshInstance3D | 视觉渲染 |

Export 变量

gdscript
@export var speed: float = 5.0
@export_range(0, 100, 1) var health: int = 100
@exportfile(*.tscn) var nextlevel: String
@export_group(Combat)
@export var damage: int = 10

信号模式

gdscript
signal health_changed(current: int, maximum: int)
signal died

func take_damage(amount: int) -> void:
health -= amount
healthchanged.emit(health, maxhealth)
if health <= 0:
died.emit()

节点引用

gdscript
@onready var sprite: Sprite2D = $Sprite2D
@onready var anim: AnimationPlayer = $AnimationPlayer

---

关键陷阱清单

陷阱	错误写法	正确写法
.tres 使用 preload	preload(res://x.gd)	ExtResource(id)
.tres 使用 var

var x = 5 | x = 5 |
| 未类型化数组 | [1, 2, 3] in .tres | Arrayint |
| 缺少 extresource | 直接使用 id | 先声明 extresource |
| @onready 初始化 | 在声明时访问其他节点 | 等到 _ready() |
| 直接修改资源 | resource.value = x | resource.duplicate() |
| 输入处理 | UI 和游戏混用 input | UI 用 gui_input |

---

参考文件

主题	路径
项目结构	references/01-project-structure.md
GDScript 模式

references/02-gdscript-patterns.md |
| 文件格式 | references/03-file-formats.md |
| 场景与节点 | references/04-scenes-nodes.md |
| UI 与输入 | references/05-ui-input.md |
| 物理系统 | references/06-physics.md |
| 音效与动画 | references/07-audio-animation.md |
| 性能优化 | references/08-performance.md |
| 导出平台 | references/09-export.md |
| 测试指南 | references/10-testing.md |

---

CLI 快速命令

bash

运行游戏

godot --path .

验证脚本

godot --path . --check-only --script path/to/script.gd

无头测试

godot --path . --headless --quit

导出

godot --path . --export-release Preset Name builds/game.exe

---

版本： 1.0.0 | 最后更新： 2026-02-17