20. [고도 엔진] 에러 처리와 디버깅 팁 (assert, print_debug, 중단점 활용)

 

이 카테고리는 고도 엔진(Godot Engine) 관련 문법을 기록하고 저장하기 위해 만든 공간입니다.

 

이번에는 '에러 처리와 디버깅 팁 (assert, print_debug, 중단점 활용)'입니다.

게임 개발은 흔히 '20%의 코딩과 80%의 디버깅(버그 잡기)'으로 이루어져 있다고 합니다. 코드가 길어지고 씬이 복잡해지면 어디서 문제가 발생했는지 찾기가 모래사장에서 바늘 찾기처럼 어려워집니다. 이때 고도 엔진이 제공하는 강력한 디버깅 도구들을 활용하면, 버그가 숨어있는 정확한 위치와 원인을 순식간에 찾아낼 수 있습니다.

1. print_debug(): 나 여기 있어요! (위치 추적기)

일반적인 print() 함수는 출력창에 글자만 달랑 띄워주기 때문에, 코드가 수천 줄이 넘어가면 이 메시지가 도대체 어디서 나온 건지 찾기 힘듭니다. 반면 print_debug()를 사용하면 메시지와 함께 '어떤 스크립트의 몇 번째 줄에서 실행되었는지'를 상세히 알려줍니다.

GDScript

 

func take_damage(amount: int):
    hp -= amount
    
    # 출력 예시: 데미지 처리됨!
    # At: res://Scripts/Player.gd:15 - take_damage()
    print_debug("데미지 처리됨! 남은 체력: ", hp)

2. assert(): 조건이 안 맞으면 당장 멈춰! (안전띠)

assert()는 괄호 안의 조건이 '거짓(false)'일 경우, 즉시 게임을 일시 정지시키고 에러를 뿜어내는 아주 강력한 함수입니다. "이 변수에는 절대 마이너스 값이 들어가면 안 돼!" 혹은 "이 노드는 무조건 존재해야 해!"처럼, 게임이 치명적으로 망가지기 전에 미리 경고를 울리게 만드는 안전장치입니다. (※ 정식 출시(Export)된 게임에서는 무시되므로 성능에 영향을 주지 않습니다.)

GDScript

 

@onready var weapon = $WeaponNode

func _ready():
    # 1. 무기 노드가 씬에 존재하는지(null이 아닌지) 강력하게 검사합니다.
    # 만약 경로가 틀려서 노드를 못 찾았다면 여기서 게임이 멈추고 메시지를 띄웁니다.
    assert(weapon != null, "치명적 에러: 무기 노드를 찾을 수 없습니다!")
    
func heal(amount: int):
    # 2. 회복량이 0보다 큰지 검사합니다. (마이너스 회복 금지)
    assert(amount > 0, "회복량은 반드시 0보다 커야 합니다!")
    hp += amount

3. 중단점(Breakpoint): 시간 정지와 변수 관찰

코드가 도대체 어떻게 굴러가고 있는지 한 줄 한 줄 뜯어보고 싶을 때가 있습니다. 스크립트 에디터 창의 왼쪽 숫자(줄 번호) 옆 빈 공간을 클릭하면 빨간색 점(중단점)이 생깁니다. 게임이 실행되다가 이 줄에 도달하면 시간이 멈추며, 그때 하단 디버거(Debugger) 창에서 모든 변수에 현재 어떤 숫자가 들어있는지 낱낱이 확인할 수 있습니다. 코드로 직접 멈추고 싶다면 breakpoint 키워드를 쓰면 됩니다.

GDScript

 

func calculate_complex_damage():
    var base_dmg = 50
    var critical_multiplier = 1.5
    var armor_reduction = 10
    
    # 게임이 여기서 멈춥니다! (이 시점의 위 변수 값들을 에디터에서 확인 가능)
    breakpoint 
    
    var final_dmg = (base_dmg * critical_multiplier) - armor_reduction
    return final_dmg

한눈에 보는 디버깅 핵심 요약

함수 / 기능	기능 설명	실전 디버깅 활용 예시
print()	가장 기본적인 출력 함수	단순히 현재 점수나 상태를 콘솔 창에 띄워볼 때
print_debug()	메시지와 함께 호출된 스크립트 위치(줄 번호) 출력	수많은 몬스터 중 도대체 어떤 몬스터가 에러를 냈는지 추적할 때
assert(조건, 메시지)	조건이 거짓일 때 에디터 실행을 멈추고 에러 발생시킴	치명적인 버그(음수 체력, 없는 아이템 사용 등)를 사전에 차단할 때
중단점 (Breakpoint)	에디터 UI에서 빨간 점을 찍어 해당 줄에서 게임을 일시 정지	복잡한 데미지 계산식에서 중간에 값이 어떻게 변하는지 관찰할 때
breakpoint	스크립트에 직접 적어 중단점과 동일하게 작동시키는 키워드	특정 if 조건문에 진입했을 때만 게임을 멈춰서 확인하고 싶을 때