GDScript：Godot 专用脚本语言

FreeGuideOnline 最新 2026-06-17

GDScript 快速入门

什么是 GDScript？

GDScript 是 Godot 引擎原生集成的动态类型脚本语言，语法灵感来自 Python，专为游戏开发优化。它与 Godot 的节点系统深度绑定，能直接访问引擎 API，是 Godot 最推荐的学习路径。

第一个脚本：Hello, Godot!

  1. 在场景中新建一个节点（例如 Sprite2D）
  2. 点击“附加脚本”按钮，选择 GDScript，保存文件
  3. 编辑器会自动生成模板，替换为以下代码：
extends Sprite2D

func _ready():
    print("Hello, Godot!")

运行场景，在“输出”面板即可看到打印信息。

变量与数据类型

GDScript 支持动态类型，也可以使用静态类型优化性能。

var health = 100
var player_name: String = "Hero"
var speed: float = 3.5
var is_alive: bool = true

常用内置类型：int, float, String, bool, Vector2, Vector3, Color, Array, Dictionary。

var 是声明变量的唯一方式，没有 const 关键字，但常量大写命名约定可实现不可变效果。

const MAX_SPEED = 500

函数定义

使用 func 关键字定义函数：

func take_damage(amount: int) -> void:
    health -= amount
    if health <= 0:
        die()
  • void 表示无返回值，可省略类型提示
  • 支持默认参数：func attack(weapon, strength = 10):

节点通信与信号

获取节点

# 使用 $ 快捷方式获取子节点
var player = $Player
var anim = $AnimationPlayer

# 使用 get_node() 方法
var player2 = get_node("Player")

信号连接

信号是 Godot 的解耦利器。在脚本中连接信号：

func _ready():
    $Timer.timeout.connect(_on_timer_timeout)

func _on_timer_timeout():
    print("时间到！")

也可以直接在编辑器中通过“节点”面板连接信号。

生命周期回调

最重要的虚函数：

  • _ready()：节点及其子节点都进入场景后调用一次
  • _process(delta)：每帧调用，delta 为距上一帧的秒数
  • _physics_process(delta)：物理更新帧调用，用于刚体运动
func _physics_process(delta):
    var move = speed * delta
    position.x += move

条件与循环

条件语句

if health <= 0:
    die()
elif health < 30:
    show_warning()
else:
    play_idle()

循环

# for 循环
for i in range(5):
    print(i)

# 遍历数组
for enemy in enemies:
    enemy.attack()

# while 循环
while coins > 0:
    drop_coin()
    coins -= 1

数组与字典

var inventory = ["剑", "盾", "药水"]
inventory.append("弓箭")
print(inventory[0])  # 输出 "剑"

var player_stats = {
    "name": "Hero",
    "level": 5,
    "exp": 230
}
player_stats["level"] += 1

使用静态类型提升性能

虽然 GDScript 是动态类型，但为变量指定类型可以：

  • 提供更好的自动补全
  • 让代码更易读
  • 潜在地提升执行速度
var damage: int = 25
var target: Node2D = $Enemy

实用小技巧

  • 调试输出：print() 可以打印任意变量，print_debug() 会显示调用栈
  • 注释：使用 # 单行注释，没有多行注释语法（可用 ## 文档注释）
  • 短路求值：if player and player.is_alive:
  • @onready 注解：延迟初始化节点引用，确保子节点已就绪
@onready var health_bar = $HealthBar

常见错误与排查

  • 场景中看不到节点变化：确认是否在 _process 或 _physics_process 中更新
  • 打印不生效：检查脚本是否附加到了正确的节点，并确保节点在场景中
  • node not found：使用 $ 时节点路径拼写错误或节点尚未存在，可使用 @onready 解决

扩展到整个项目

自定义类

可以创建独立的 GDScript 文件作为类，使用 class_name 注册为全局类型：

# 新建脚本文件 Item.gd
class_name Item
extends Resource

var name: String
var weight: float

之后在其他脚本中直接 var item: Item = Item.new()。

使用组（Groups）

为节点添加组标签，然后批量操作：

get_tree().call_group("enemies", "stun")

总结

GDScript 让你的游戏逻辑与 Godot 无缝衔接，它的简单语法降低了学习曲线，同时强大的节点、信号系统提供了专业级开发能力。开始动手写你的第一个 2D 角色控制器吧，实践是掌握 GDScript 的最佳途径。