18. [고도 엔진] 비동기 처리의 마법: 코루틴(Coroutine)과 await 키워드

 

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

 

이번에는 '비동기 처리의 마법: 코루틴(Coroutine)과 await 키워드'입니다.

게임에서는 "3초 뒤에 폭탄이 터진다", "캐릭터의 공격 애니메이션이 끝난 후 데미지가 들어간다"처럼 특정 시간이 지나거나 어떤 사건이 끝날 때까지 '기다려야' 하는 상황이 아주 많습니다. 이때 무작정 게임 전체를 멈춰버리면 화면이 그대로 굳어버리겠죠? 게임(메인 스레드)은 계속 부드럽게 돌아가게 두면서, 특정 스크립트의 실행만 잠시 멈췄다가 나중에 다시 시작하게 해주는 키워드가 바로 await입니다.

1. 가장 흔한 사용법: 타이머로 특정 시간 기다리기

코드를 짜다가 "여기서 딱 2초만 기다렸다가 다음 코드를 실행하고 싶다"할 때 await와 내장 타이머를 조합하면 코드가 놀랍도록 간결해집니다.

GDScript

 

func _ready():
    print("전투 시작!")
    
    # 1. 2초 동안 이 함수의 실행을 잠시 멈춥니다. (게임은 멈추지 않습니다!)
    await get_tree().create_timer(2.0).timeout
    
    # 2. 2초 뒤에 타이머가 끝나면 아래 코드가 이어서 실행됩니다.
    print("2초 경과! 몬스터가 스폰됩니다.")

2. 시그널(Signal)과 함께 쓰기: 사건이 끝날 때까지 대기

await 뒤에 특정 노드의 '시그널'을 적어주면, 그 시그널이 방송될(emit) 때까지 얌전히 대기합니다. 애니메이션이나 소리가 끝날 때까지 기다릴 때 가장 많이 사용됩니다.

GDScript

 

@onready var anim_player = $AnimationPlayer

func attack():
    print("공격 모션 시작!")
    anim_player.play("attack_animation")
    
    # 'animation_finished' 시그널이 발생할 때까지 코드를 일시 정지합니다.
    await anim_player.animation_finished
    
    # 애니메이션이 완전히 끝난 후 실행됩니다.
    print("공격 모션 종료! 원래 상태로 돌아갑니다.")

3. 커스텀 함수로 코루틴 만들기

내가 만든 다른 함수가 끝날 때까지 기다릴 수도 있습니다. 여러 단계로 이루어진 컷신이나 복잡한 튜토리얼 단계를 순서대로 만들 때 매우 유용합니다.

GDScript

 

func _ready():
    print("컷신 1단계 시작")
    await play_cutscene() # 이 함수 안의 작업이 전부 끝날 때까지 대기
    print("컷신 모두 완료! 게임을 재개합니다.")

func play_cutscene():
    print("캐릭터 이동 중...")
    await get_tree().create_timer(1.0).timeout
    print("대사 출력 중...")
    await get_tree().create_timer(1.5).timeout

한눈에 보는 코루틴(await) 핵심 요약

문법 / 개념	기능 설명	게임 속 사용 예시
코루틴 (Coroutine)	실행을 잠시 멈췄다가 나중에 중단된 지점부터 다시 재개할 수 있는 함수	NPC와의 긴 대화 이벤트나 연출이 들어간 컷신을 순차적으로 구현할 때
await	(고도 4 기준) 지정한 시그널이 발생할 때까지 코드 실행을 일시 정지하는 키워드	스킬 캐스팅(영창) 시간 대기, 화면 페이드인/아웃 완료 대기
get_tree().create_timer(초).timeout	지정한 시간(초)만큼 일회성 타이머를 만들고 끝날 때 시그널을 방출함	독에 걸려 1초마다 지속 피해를 입는 로직을 구현할 때
await 대상.시그널	특정 대상이 해당 시그널을 방출할 때까지 대기	보스 몬스터의 '사망(died)' 시그널을 기다렸다가 승리 UI를 띄울 때