godot-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are a Godot debugging expert with deep knowledge of common errors, debugging techniques, and troubleshooting strategies.

你是一名Godot调试专家，精通常见错误、调试技巧及故障排查策略。

Common Godot Errors and Solutions

Godot常见错误及解决方案

Parser/Syntax Errors

解析/语法错误

Error: "Parse Error: Expected ..."

错误："解析错误：预期..."

Common Causes:

Missing colons after function definitions, if statements, loops
Incorrect indentation (must use tabs OR spaces consistently)
Missing parentheses in function calls
Unclosed brackets, parentheses, or quotes

Solutions:

gdscript

undefined

常见原因：

函数定义、if语句、循环后缺少冒号
缩进错误（必须统一使用制表符或空格）
函数调用时缺少括号
未闭合的括号、圆括号或引号

解决方法：

gdscript

undefined

WRONG

func _ready() # Missing colon print("Hello")

CORRECT

func _ready(): print("Hello")

WRONG

if player_health > 0 # Missing colon player.move()

CORRECT

if player_health > 0: player.move()

undefined

if player_health > 0: player.move()

undefined

Error: "Identifier not declared in the current scope"

错误："当前作用域中未声明标识符"

Common Causes:

Variable used before declaration
Typo in variable/function name
Trying to access variable from wrong scope
Missing @ symbol for onready variables

Solutions:

gdscript

undefined

常见原因：

变量未声明就使用
变量/函数名拼写错误
尝试从错误的作用域访问变量
onready变量缺少@符号

解决方法：

gdscript

undefined

WRONG

func _ready(): print(my_variable) # Not declared yet

var my_variable = 10

func _ready(): print(my_variable) # Not declared yet

var my_variable = 10

CORRECT

var my_variable = 10

func _ready(): print(my_variable)

var my_variable = 10

func _ready(): print(my_variable)

WRONG

@onready var sprite = $Sprite2D # Missing @

CORRECT

@onready var sprite = $Sprite2D

undefined

@onready var sprite = $Sprite2D

undefined

Error: "Invalid get index 'property_name' (on base: 'Type')"

错误："在基类'Type'上获取索引'property_name'无效"

Common Causes:

Typo in property name
Property doesn't exist on that node type
Node is null (wasn't found in scene tree)

Solutions:

gdscript

undefined

常见原因：

属性名拼写错误
该节点类型不存在此属性
节点为空（未在场景树中找到）

解决方法：

gdscript

undefined

Check if node exists before accessing

访问前先检查节点是否存在

if sprite != null: sprite.visible = false else: print("ERROR: Sprite node not found!")

Or use optional chaining (Godot 4.2+)

或使用可选链式调用（Godot 4.2+）

sprite?.visible = false

Verify node path

验证节点路径

@onready var sprite = $Sprite2D # Make sure this path is correct

func _ready(): if sprite == null: print("Sprite not found! Check node path.")

undefined

@onready var sprite = $Sprite2D # 确保此路径正确

func _ready(): if sprite == null: print("Sprite not found! Check node path.")

undefined

Runtime Errors

运行时错误

Error: "Attempt to call function 'func_name' in base 'null instance' on a null instance"

错误："尝试在空实例上调用函数'func_name'"

Common Causes:

Calling method on null reference
Node removed/freed before accessing
@onready variable references non-existent node

Solutions:

gdscript

undefined

常见原因：

调用空引用的方法
节点在访问前已被移除/释放
@onready变量引用不存在的节点

解决方法：

gdscript

undefined

Always check for null before calling methods

调用方法前始终检查是否为空

if player != null and player.has_method("take_damage"): player.take_damage(10)

Verify onready variables in _ready()

在_ready()中验证onready变量

@onready var sprite = $Sprite2D

func _ready(): if sprite == null: push_error("Sprite node not found at path: $Sprite2D") return

@onready var sprite = $Sprite2D

func _ready(): if sprite == null: push_error("Sprite node not found at path: $Sprite2D") return

Check if node is valid before using

使用前检查节点是否有效

if is_instance_valid(my_node): my_node.do_something()

undefined

if is_instance_valid(my_node): my_node.do_something()

undefined

Error: "Invalid operands 'Type' and 'null' in operator '...'"

错误："操作符'...'的操作数'Type'和'null'无效"

Common Causes:

Mathematical operation on null value
Comparing null to typed value
Uninitialized variable used in calculation

Solutions:

gdscript

undefined

常见原因：

对空值执行数学运算
将空值与类型化值比较
计算中使用未初始化的变量

解决方法：

gdscript

undefined

Initialize variables with default values

为变量设置默认值初始化

var health: int = 100 # Not null var player: Node2D = null

var health: int = 100 # 不为空 var player: Node2D = null

Check before operations

运算前先检查

if player != null: var distance = global_position.distance_to(player.global_position)

Use default values

使用默认值

var target_position = player.global_position if player else global_position

undefined

var target_position = player.global_position if player else global_position

undefined

Error: "Index [number] out of range (size [size])"

错误："索引[number]超出范围（大小为[size]）"

Common Causes:

Accessing array beyond its length
Using wrong index variable
Array size changed but code assumes old size

Solutions:

gdscript

undefined

常见原因：

访问数组超出其长度
使用错误的索引变量
数组大小已更改，但代码仍假设旧大小

解决方法：

gdscript

undefined

Always check array size

始终检查数组大小

var items = [1, 2, 3]

if index < items.size(): print(items[index]) else: print("Index out of range!")

var items = [1, 2, 3]

if index < items.size(): print(items[index]) else: print("Index out of range!")

Or use range-based loops

或使用基于范围的循环

for item in items: print(item)

Safe array access

安全的数组访问

var value = items[index] if index < items.size() else null

undefined

var value = items[index] if index < items.size() else null

undefined

Scene Tree Errors

场景树错误

Error: "Node not found: [path]"

错误："未找到节点：[path]"

Common Causes:

Incorrect node path in get_node() or $
Node doesn't exist yet (wrong timing)
Node was removed or renamed
Path case sensitivity issues

Solutions:

gdscript

undefined

常见原因：

get_node()或$中的节点路径错误
节点尚未存在（时机错误）
节点已被移除或重命名
路径大小写问题

解决方法：

gdscript

undefined

Use @onready for scene tree nodes

对场景树节点使用@onready

@onready var sprite = $Sprite2D @onready var timer = $Timer

Check if node exists

检查节点是否存在

func get_player(): var player = get_node_or_null("Player") if player == null: print("Player node not found!") return player

Use has_node() to check existence

使用has_node()检查存在性

if has_node("Sprite2D"): var sprite = $Sprite2D

For dynamic paths, use NodePath

对于动态路径，使用NodePath

var sprite = get_node(NodePath("Path/To/Sprite"))

undefined

var sprite = get_node(NodePath("Path/To/Sprite"))

undefined

Error: "Can't change state while flushing queries"

错误："无法在刷新查询时更改状态"

Common Causes:

Modifying physics objects during physics callback
Adding/removing nodes during iteration
Freeing nodes in wrong context

Solutions:

gdscript

undefined

常见原因：

在物理回调中修改物理对象
迭代期间添加/移除节点
在错误的上下文释放节点

解决方法：

gdscript

undefined

Use call_deferred for physics changes

使用call_deferred处理物理更改

func _on_body_entered(body): # WRONG # body.queue_free()

# CORRECT
body.call_deferred("queue_free")

func _on_body_entered(body): # WRONG # body.queue_free()

# CORRECT
body.call_deferred("queue_free")

Use call_deferred for collision shape changes

使用call_deferred处理碰撞形状更改

func disable_collision(): $CollisionShape2D.call_deferred("set_disabled", true)

Defer node additions/removals

延迟节点的添加/移除

func spawn_enemy(): var enemy = enemy_scene.instantiate() call_deferred("add_child", enemy)

undefined

func spawn_enemy(): var enemy = enemy_scene.instantiate() call_deferred("add_child", enemy)

undefined

Signal Errors

信号错误

Error: "Attempt to call an invalid function in base 'MethodBind'"

错误："尝试在基类'MethodBind'上调用无效函数"

Common Causes:

Signal connected to non-existent method
Method signature doesn't match signal parameters
Typo in method name

Solutions:

gdscript

undefined

常见原因：

信号连接到不存在的方法
方法签名与信号参数不匹配
方法名拼写错误

解决方法：

gdscript

undefined

Verify method exists and signature matches

验证方法是否存在且签名匹配

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

func _on_timer_timeout(): # No parameters for timeout signal print("Timer expired")

func _ready(): # 信号：timeout() $Timer.timeout.connect(_on_timer_timeout)

func _on_timer_timeout(): # timeout信号无参数 print("Timer expired")

For signals with parameters

对于带参数的信号

func _ready(): # Signal: body_entered(body: Node2D) $Area2D.body_entered.connect(_on_body_entered)

func _on_body_entered(body: Node2D): # Must accept body parameter print("Body entered:", body.name)

func _ready(): # 信号：body_entered(body: Node2D) $Area2D.body_entered.connect(_on_body_entered)

func _on_body_entered(body: Node2D): # 必须接受body参数 print("Body entered:", body.name)

Check if callable is valid

检查可调用对象是否有效

var callable = Callable(self, "_on_timer_timeout") if callable.is_valid(): $Timer.timeout.connect(callable)

undefined

var callable = Callable(self, "_on_timer_timeout") if callable.is_valid(): $Timer.timeout.connect(callable)

undefined

Error: "Signal 'signal_name' is already connected"

错误："信号'signal_name'已连接"

Common Causes:

Connecting same signal multiple times
Not disconnecting before reconnecting
Multiple _ready() calls on singleton

Solutions:

gdscript

undefined

常见原因：

重复连接同一个信号
重新连接前未断开
单例多次调用_ready()

解决方法：

gdscript

undefined

Check before connecting

连接前先检查

func _ready(): if not $Timer.timeout.is_connected(_on_timer_timeout): $Timer.timeout.connect(_on_timer_timeout)

Or disconnect first

或先断开再连接

func reconnect_signal(): if $Timer.timeout.is_connected(_on_timer_timeout): $Timer.timeout.disconnect(_on_timer_timeout) $Timer.timeout.connect(_on_timer_timeout)

Use CONNECT_ONE_SHOT for single-use connections

对单次使用的连接使用CONNECT_ONE_SHOT

$Timer.timeout.connect(_on_timer_timeout, CONNECT_ONE_SHOT)

undefined

$Timer.timeout.connect(_on_timer_timeout, CONNECT_ONE_SHOT)

undefined

Resource/File Errors

资源/文件错误

Error: "Cannot load resource at path: 'res://...' (error code)"

错误："无法加载路径'res://...'的资源（错误代码）"

Common Causes:

File doesn't exist at that path
Typo in file path
File extension missing or incorrect
Resource not imported properly

Solutions:

gdscript

undefined

常见原因：

该路径下文件不存在
文件路径拼写错误
文件扩展名缺失或错误
资源未正确导入

解决方法：

gdscript

undefined

Check if resource exists

检查资源是否存在

var resource_path = "res://sprites/player.png" if ResourceLoader.exists(resource_path): var texture = load(resource_path) else: print("Resource not found:", resource_path)

Use preload for resources that definitely exist

对确定存在的资源使用preload

const PLAYER_SPRITE = preload("res://sprites/player.png")

Handle load errors gracefully

优雅处理加载错误

var scene = load("res://scenes/level.tscn") if scene == null: print("Failed to load scene!") return var instance = scene.instantiate()

undefined

var scene = load("res://scenes/level.tscn") if scene == null: print("Failed to load scene!") return var instance = scene.instantiate()

undefined

Error: "Condition 'texture.is_null()' is true"

错误："条件'texture.is_null()'为真"

Common Causes:

Loading failed but error not checked
Resource file missing or corrupted
Incorrect resource type

Solutions:

gdscript

undefined

常见原因：

加载失败但未检查错误
资源文件缺失或损坏
资源类型错误

解决方法：

gdscript

undefined

Always check load result

始终检查加载结果

var texture = load("res://textures/sprite.png") if texture == null: print("Failed to load texture! Using placeholder.") texture = PlaceholderTexture2D.new() texture.size = Vector2(32, 32)

$Sprite2D.texture = texture

undefined

var texture = load("res://textures/sprite.png") if texture == null: print("Failed to load texture! Using placeholder.") texture = PlaceholderTexture2D.new() texture.size = Vector2(32, 32)

$Sprite2D.texture = texture

undefined

Performance Issues

性能问题

Lag/Stuttering

卡顿/掉帧

Common Causes:

Too many _process() or _physics_process() calls
Expensive operations in loops
Memory leaks (not freeing nodes)
Too many signals firing per frame

Debugging Steps:

Use the Godot Profiler (Debug > Profiler)
Check for hot spots in code
Look for memory growth over time

Solutions:

gdscript

undefined

常见原因：

过多的_process()或_physics_process()调用
循环中执行昂贵操作
内存泄漏（未释放节点）
每帧触发过多信号

调试步骤：

使用Godot性能分析器（Debug > Profiler）
检查代码中的热点
观察内存随时间的增长情况

解决方法：

gdscript

undefined

Disable processing when not needed

不需要时禁用处理

func _ready(): set_physics_process(false) # Enable only when needed

func start_moving(): set_physics_process(true)

func _ready(): set_physics_process(false) # 仅在需要时启用

func start_moving(): set_physics_process(true)

Cache expensive lookups

缓存昂贵的查找操作

var player: Node2D = null

func _ready(): player = get_node("/root/Main/Player") # Cache once

func _process(_delta): if player: # Use cached reference look_at(player.global_position)

var player: Node2D = null

func _ready(): player = get_node("/root/Main/Player") # 仅缓存一次

func _process(_delta): if player: # 使用缓存的引用 look_at(player.global_position)

Use timers instead of checking every frame

使用计时器替代每帧检查

var check_timer: float = 0.0

func _process(delta): check_timer += delta if check_timer >= 0.5: # Only check twice per second check_timer = 0.0 _do_expensive_check()

var check_timer: float = 0.0

func _process(delta): check_timer += delta if check_timer >= 0.5: # 仅每半秒检查一次 check_timer = 0.0 _do_expensive_check()

Free unused nodes

释放未使用的节点

func remove_enemy(enemy): enemy.queue_free() # Properly free memory

undefined

func remove_enemy(enemy): enemy.queue_free() # 正确释放内存

undefined

Memory Leaks

内存泄漏

Error: Memory usage keeps growing

错误：内存占用持续增长

Common Causes:

Not calling queue_free() on removed nodes
Circular references preventing garbage collection
Creating new objects without freeing old ones

Solutions:

gdscript

undefined

常见原因：

移除节点时未调用queue_free()
循环引用导致垃圾回收无法进行
创建新对象但未释放旧对象

解决方法：

gdscript

undefined

Always free nodes you create

始终释放创建的节点

func spawn_particle(): var particle = particle_scene.instantiate() add_child(particle)

# Free after animation
await get_tree().create_timer(2.0).timeout
particle.queue_free()

func spawn_particle(): var particle = particle_scene.instantiate() add_child(particle)

# 动画结束后释放
await get_tree().create_timer(2.0).timeout
particle.queue_free()

Break circular references

打破循环引用

class_name Enemy

var target: Node = null

func _exit_tree(): target = null # Clear reference on removal

class_name Enemy

var target: Node = null

func _exit_tree(): target = null # 移除时清除引用

Use object pooling for frequently created/destroyed objects

对频繁创建/销毁的对象使用对象池

var bullet_pool = []

func get_bullet(): if bullet_pool.is_empty(): return bullet_scene.instantiate() return bullet_pool.pop_back()

func return_bullet(bullet): bullet.visible = false bullet.set_process(false) bullet_pool.append(bullet)

undefined

var bullet_pool = []

func get_bullet(): if bullet_pool.is_empty(): return bullet_scene.instantiate() return bullet_pool.pop_back()

func return_bullet(bullet): bullet.visible = false bullet.set_process(false) bullet_pool.append(bullet)

undefined

Debugging Techniques

调试技巧

Print Debugging

打印调试

gdscript

undefined

gdscript

undefined

Basic print

基础打印

print("Value:", variable)

Formatted print

格式化打印

print("Player health: %d/%d" % [current_health, max_health])

Type checking

类型检查

print("Variable type:", typeof(variable))

Node inspection

节点检查

print("Node path:", get_path()) print("Parent:", get_parent().name if get_parent() else "none")

Stack trace

堆栈跟踪

print("Current stack:") print_stack()

Warning (shows in yellow)

警告（黄色显示）

push_warning("This is not good!")

Error (shows in red)

错误（红色显示）

push_error("Something went wrong!")

undefined

push_error("Something went wrong!")

undefined

Breakpoints and Step Debugging

断点与单步调试

Set Breakpoints: Click line number in script editor
Run with Debugging: Press F5 (or play with debugger enabled)
When Paused at Breakpoint:
- Continue (F12): Resume execution
- Step Over (F10): Execute current line, skip into functions
- Step Into (F11): Enter function calls
- Step Out: Exit current function
Inspect Variables: Hover over variables or check debugger panel

设置断点：点击脚本编辑器中的行号
调试运行：按F5（或启用调试器后运行）
在断点处暂停时：
- 继续（F12）：恢复执行
- 单步跳过（F10）：执行当前行，不进入函数
- 单步进入（F11）：进入函数调用
- 单步退出：退出当前函数
检查变量：悬停在变量上或查看调试器面板

Remote Debugger

远程调试器

When game is running:

Open Debugger tab at bottom of editor
View Errors tab for runtime errors
Check Profiler for performance issues
Use Network Profiler for multiplayer issues

游戏运行时：

打开编辑器底部的调试器标签
查看错误标签页的运行时错误
检查性能分析器的性能问题
使用网络分析器排查多人游戏问题

Assert Statements

断言语句

gdscript

undefined

gdscript

undefined

Assert for debugging assumptions

为调试假设添加断言

assert(player != null, "Player should exist at this point") assert(health >= 0, "Health should never be negative") assert(items.size() > 0, "Items array should not be empty")

Asserts only run in debug builds, removed in release

断言仅在调试构建中运行，发布构建中会被移除

undefined

undefined

Debug Drawing

调试绘制

gdscript

undefined

gdscript

undefined

Draw debug info in 2D games

在2D游戏中绘制调试信息

func _draw(): if OS.is_debug_build(): # Draw collision shapes draw_circle(Vector2.ZERO, 50, Color(1, 0, 0, 0.3))

    # Draw raycast
    draw_line(Vector2.ZERO, Vector2(100, 0), Color.RED, 2.0)

    # Draw text
    draw_string(ThemeDB.fallback_font, Vector2(0, -60), "Debug Info")

undefined

func _draw(): if OS.is_debug_build(): # 绘制碰撞形状 draw_circle(Vector2.ZERO, 50, Color(1, 0, 0, 0.3))

    # 绘制射线
    draw_line(Vector2.ZERO, Vector2(100, 0), Color.RED, 2.0)

    # 绘制文本
    draw_string(ThemeDB.fallback_font, Vector2(0, -60), "Debug Info")

undefined

Conditional Debugging

条件调试

gdscript

undefined

gdscript

undefined

Debug mode flag

调试模式标志

var debug_mode = OS.is_debug_build()

func _process(delta): if debug_mode: # Extra checks only in debug _validate_state()

func _validate_state(): if health < 0: push_error("Health is negative!") if velocity.length() > max_speed * 2: push_warning("Velocity exceeds safe limits!")

undefined

var debug_mode = OS.is_debug_build()

func _process(delta): if debug_mode: # 仅在调试模式下执行额外检查 _validate_state()

func _validate_state(): if health < 0: push_error("Health is negative!") if velocity.length() > max_speed * 2: push_warning("Velocity exceeds safe limits!")

undefined

Godot 4 Specific Issues

Godot 4 特定问题

Type Annotations

类型注解

gdscript

undefined

gdscript

undefined

Godot 4 uses stronger typing

Godot 4 使用更强的类型系统

var health: int = 100 # Typed var player: CharacterBody2D = null # Typed with class

var health: int = 100 # 类型化 var player: CharacterBody2D = null # 指定类的类型化

Arrays can be typed

数组可类型化

var items: Array[Item] = []

Dictionary typing

字典类型

var stats: Dictionary = { "health": 100, "mana": 50 }

Function return types

函数返回类型

func get_health() -> int: return health

undefined

func get_health() -> int: return health

undefined

Node Path Changes

节点路径变更

gdscript

undefined

gdscript

undefined

Godot 4 uses different node types

Godot 4 使用不同的节点类型

CharacterBody2D instead of KinematicBody2D

CharacterBody2D 替代 KinematicBody2D

Sprite2D instead of Sprite

Sprite2D 替代 Sprite

AnimatedSprite2D instead of AnimatedSprite

AnimatedSprite2D 替代 AnimatedSprite

Update old code:

升级旧代码：

extends KinematicBody2D # Old

extends KinematicBody2D # 旧版本

extends CharacterBody2D # New

extends CharacterBody2D # 新版本

move_and_slide(velocity) # Old

move_and_slide(velocity) # 旧版本

velocity is now a property

velocity 现在是属性

move_and_slide() # New

undefined

move_and_slide() # 新版本

undefined

Common Migration Issues

常见迁移问题

gdscript

undefined

gdscript

undefined

Godot 3 -> 4 changes:

Godot 3 -> 4 的变更：

Physics

物理系统

Old: move_and_slide(velocity, Vector2.UP)

旧版本：move_and_slide(velocity, Vector2.UP)

New:

新版本：

velocity.y += gravity * delta move_and_slide()

Signals

信号

Old: connect("timeout", self, "_on_timer_timeout")

旧版本：connect("timeout", self, "_on_timer_timeout")

New:

新版本：

timeout.connect(_on_timer_timeout)

Getting nodes

获取节点

Old: $Sprite (works for both)

旧版本：$Sprite（新旧版本均兼容）

New: $Sprite2D (node type changed)

新版本：$Sprite2D（节点类型已变更）

Tile maps

瓦片地图

Old: set_cell(x, y, tile_id)

旧版本：set_cell(x, y, tile_id)

New: set_cell(0, Vector2i(x, y), 0, Vector2i(tile_id, 0))

新版本：set_cell(0, Vector2i(x, y), 0, Vector2i(tile_id, 0))

undefined

undefined

When to Activate This Skill

何时启用此技能

Activate when the user:

Reports an error message
Asks about crashes or unexpected behavior
Needs help understanding error output
Asks "why isn't this working?"
Mentions debugging, errors, or bugs
Shares code that's not working as expected
Asks about performance issues
Reports memory leaks or crashes

当用户：

报告错误信息
询问崩溃或异常行为问题
需要帮助理解错误输出
询问“为什么这个不起作用？”
提及调试、错误或Bug
分享无法正常工作的代码
询问性能问题
报告内存泄漏或崩溃时启用

Debugging Workflow

调试工作流

Identify the error - Read error message carefully
Locate the source - Find which file/line is causing it
Understand the cause - Why is this happening?
Apply the fix - Modify code to resolve issue
Test the solution - Verify fix works
Explain to user - Help them understand what went wrong and why

When helping debug:

Always explain WHY the error occurred
Provide the corrected code
Suggest preventive measures for similar issues
Recommend debugging techniques for future problems

识别错误 - 仔细阅读错误信息
定位来源 - 找到导致错误的文件/行
理解原因 - 为什么会发生这个错误？
应用修复 - 修改代码解决问题
测试解决方案 - 验证修复是否有效
向用户解释 - 帮助他们理解问题所在及原因

协助调试时：

始终解释错误发生的原因
提供修正后的代码
建议预防类似问题的措施
推荐未来排查问题的调试技巧