gdscript-syntax-guide

GDScript 语法权威指南

技能概述

gdscript-syntax-guide 是专门用于提供 Godot 4.5 环境下 GDScript 语法规范、最佳实践和代码风格的权威指南。该技能确保所有生成的代码符合最新标准和最佳实践。

🎯 核心目标

• 语法准确性: 确保代码符合 Godot 4.5 语法标准
• 缩进规范: 严格遵守 GDScript 官方缩进规范（制表符缩进）
• 最佳实践: 提供业界认可的最佳实践示例
• 代码风格: 统一代码风格和命名规范
• 类型安全: 推荐强类型和类型提示使用

📋 缩进规范（核心重点）

✅ 官方推荐标准

基本缩进规则

• 缩进字符: 必须使用制表符 (Tab)，而非空格
• 缩进宽度: 显示为4个字符宽度（编辑器配置）
• 缩进层级: 每个嵌套层级使用一个Tab
• 对齐: 严格使用Tab缩进，避免Tab和空格混用

为什么使用制表符

• Godot官方编辑器默认支持和推荐Tab缩进
• 文件大小更小，解析性能更好
• 避免空格/制表符混用导致的显示问题
• 团队协作时缩进一致性更容易保证

✅ 正确示例

# 函数定义无前导缩进
func my_function(param: int) -> void:
    # 函数体内使用一个Tab缩进
    if condition:
        # 嵌套代码块使用两个Tab缩进
        nested_call()
        another_call()

    # 同级别的代码保持一个Tab缩进
    other_call()

# 静态函数同样遵循缩进规则
static func static_function() -> void:
    # 静态函数体内的代码使用一个Tab缩进
    pass

❌ 错误示例

# 错误：函数定义前有缩进
    func bad_function() -> void:
        pass

# 错误：混用空格和制表符
func bad_example() -> void:
	var variable = 0    # 这里可能使用了空格
        another_var = 1   # 这里可能使用了不同的缩进

# 错误：缩进层级混乱
func bad_function() -> void:
if condition:
do_something()
		nested_call()

🔤 类型系统最佳实践

强类型推荐

# ✅ 推荐：使用类型提示
var player: Player
var health: int = 100
var position: Vector2 = Vector2.ZERO
var items: Array[String] = []

# ✅ 推荐：函数参数类型
func take_damage(amount: int, damage_type: String) -> void:
    pass

# ✅ 推荐：返回类型
func calculate_damage(base: int, multiplier: float) -> int:
    return int(base * multiplier)

类型转换安全

# ✅ 推荐：安全类型转换
var node = get_node("Player")
if node is Player:
    var player = node as Player
    player.health -= 10

# ✅ 推荐：使用类型检查
func process_object(object: Variant) -> void:
    match object.get_type():
        TYPE_INT:
            var value = object as int
            print("整数值: ", value)
        TYPE_STRING:
            var text = object as String
            print("字符串: ", text)
        _:
            push_warning("不支持的类型")

🎨 代码风格指南

命名规范

# ✅ 变量和函数：snake_case
var player_health: int = 100
var current_level: String = "level_1"
func calculate_damage() -> int:
    pass

# ✅ 常量：UPPER_SNAKE_CASE
const MAX_HEALTH: int = 100
const GRAVITY: float = 9.8

# ✅ 类名：PascalCase
class_name PlayerController
extends CharacterBody2D

# ✅ 信号：snake_case
signal health_changed(new_health: int)
signal player_died()