Godot GDScript 代码规范与最佳实践 | 类型注解、信号、@export 使用指南 | SkillsMDGodot GDScript 代码规范与最佳实践 | 类型注解、信号、@export 使用指南
godot-dev by chen19007/my_skills
npx skills add https://github.com/chen19007/my_skills --skill godot-dev🇨🇳中文介绍
Godot 代码实现规范
本 Skill 提供 GDScript 代码实现的规范和最佳实践，确保代码符合 Godot 引擎特性和 TDD 友好原则。
适用场景
- 编写新的功能代码
- 重构现有代码
- 遵循 GDScript 风格规范
- 使用 Godot 特有功能
GDScript 风格规则
类型注解
# 函数参数和返回值（强制）
func move_to(target: Vector2) -> void:
...
func calculate_damage(base: float, multiplier: float) -> float:
return base * multiplier
# 变量类型注解
var health: int = 100
var speed: float = 300.0
var position: Vector2 = Vector2.ZERO
var enemies: Array[Node] = []
属性可见性
# 私有属性（使用下划线前缀）
var _health: int = 100
var _velocity: Vector2 = Vector2.ZERO
var _cooldowns: Dictionary = {}
# 只读属性（使用 getter）
var health: int:
get:
return _health
# 导出变量（编辑器配置）
@export var max_health: int = 100
@export var move_speed: float = 300.0
@export var damage: float = 10.0
常量命名
const MAX_HEALTH := 100
const MOVE_SPEED := 300.0
const GRAVITY := 980.0
const TAG_ENEMY := "enemy"
信号定义
# 状态变化信号
signal health_changed(new_health: int, old_health: int)
signal died()
signal revived()
# 事件信号
signal attack_completed(target: Node)
signal level_up(level: int)
# 使用信号
func take_damage(amount: int) -> void:
var old_health = _health
_health = max(0, _health - amount)
health_changed.emit(_health, old_health)
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
Godot 特性使用
Signal（观察者模式）
# 定义信号
signal health_changed(new_health: int)
# 发送信号
func take_damage(amount: int) -> void:
_health = max(0, _health - amount)
health_changed.emit(_health)
# 连接信号（推荐使用 callable 语法）
func _ready() -> void:
health_changed.connect(_on_health_changed)
func _on_health_changed(new_health: int) -> void:
print("Health: ", new_health)
# 一次性信号
health_changed.connect(_on_health_changed, CONNECT_ONE_SHOT)
@onready（节点引用）
extends Node2D
@onready var sprite: Sprite2D = $Sprite2D
@onready var animation: AnimationPlayer = $AnimationPlayer
@onready var collision: CollisionShape2D = $CollisionShape2D
@export（编辑器配置）
@export var max_health: int = 100
@export var move_speed: float = 300.0
# 资源类型
@export var bullet_scene: PackedScene
# 枚举类型
@export_enum("Fast", "Normal", "Slow") var speed_mode: String = "Normal"
# 分组
@export_group("Damage Settings")
@export var base_damage: float = 10.0
@export var critical_multiplier: float = 2.0
Autoload（单例）
# 获取 autoload
var game_manager = Engine.get_main_loop().get_node("/root/GameManager")
# 安全访问
func _ready() -> void:
if Engine.get_main_loop().has_node("/root/GameManager"):
var gm = Engine.get_main_loop().get_node("/root/GameManager")
gm.register_player(self)
依赖管理
循环依赖问题
# 错误：循环依赖
class_name Player extends Node
func _ready() -> void:
var manager = GameManager.get_instance()
manager.register(self)
# GameManager.gd
class_name GameManager
func register_player(player: Player): # 引用 Player
...
解决方案
# 方案1：使用基类参数
func register_character(character: Node, height_x: float) -> void:
...
# 方案2：延迟绑定
func _ready() -> void:
var manager = _get_game_manager()
if manager:
manager.register(self)
func _get_game_manager() -> Node:
if Engine.get_main_loop().has_node("/root/GameManager"):
return Engine.get_main_loop().get_node("/root/GameManager")
return null
# 方案3：避免 class_name 循环
extends Node2D # 不使用 class_name
碰撞检测
Area2D vs PhysicsBody
extends Area2D
func _ready() -> void:
body_entered.connect(_on_body_entered)
func _on_body_entered(body: Node) -> void:
# 使用 has_method 检查接口
if body.has_method("take_damage"):
body.take_damage(10)
# 检测 PhysicsBody
func check_player_overlap(player: Node) -> bool:
return overlaps_body(player)
# 检测 Area2D
func check_hazard_overlap(hazard: Node) -> bool:
return overlaps_area(hazard)
常见反模式
反模式 1：直接暴露内部变量
# 错误
var health: int = 100
# 正确
var _health: int = 100
func get_health() -> int:
return _health
反模式 2：硬编码 autoload 引用
# 错误
func _ready() -> void:
GameManager.add_player(self) # 可能为 null
# 正确
func _ready() -> void:
if Engine.get_main_loop().has_node("/root/GameManager"):
Engine.get_main_loop().get_node("/root/GameManager").add_player(self)
反模式 3：测试逻辑污染
# 错误
func _process(delta: float) -> void:
move_and_slide()
if is_in_test_mode: # 测试逻辑混入生产代码
_record_test_data()
# 正确
# 测试逻辑完全分离，通过接口控制
反模式 4：缺少类型注解
# 错误
func move_to(target): # 缺少类型
...
# 正确
func move_to(target: Vector2) -> void:
...
反模式 5：不使用 @onready
# 错误
func _ready() -> void:
var sprite = get_node("Sprite2D") # 每次调用都查找
# 正确
@onready var sprite: Sprite2D = $Sprite2D # 缓存引用
避免的模式
对象池（不需要）
GDScript 使用引用计数，不是 GC 语言：
# 不需要对象池
var bullet = BulletScene.instantiate()
add_child(bullet)
# 当没有引用时自动释放
ECS（除非 AAA 游戏）
# 使用节点组合而非 ECS
var player = PlayerScene.instantiate()
add_child(player)
player.attack.connect(_on_attack)
复杂状态机
# 简单情况使用状态变量
var state: String = "idle"
# 复杂情况使用 StateMachine 节点
检查清单
- 所有函数有类型注解
- 变量有类型注解
- 私有属性使用下划线前缀
- 使用 @onready 而非 get_node()
- 信号正确解耦
- autoload 安全访问
- 避免循环依赖
React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性
109,600 周安装
