14. [고도 엔진] 편리한 노드 할당자 @onready 키워드

 

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

 

이번에는 고도 엔진 개발자들의 타이핑을 줄여주는 필수 키워드, '편리한 노드 할당자 @onready '입니다.

이전 글에서 다른 노드를 가져올 때 $ 기호를 쓴다고 배웠습니다. 하지만 이 $ 기호를 함수 밖(스크립트 최상단)에서 그냥 사용하면 고도 엔진은 "아직 노드가 준비되지 않았다"라며 에러를 뿜어냅니다. 이를 우아하게 해결해 주는 마법의 키워드가 바로 @onready입니다.

1. @onready가 필요한 이유 (에러가 발생하는 상황)

고도 엔진에서 변수는 노드가 게임 화면(씬 트리)에 들어오기도 전에 메모리에 먼저 만들어집니다. 이때 $ 기호로 자식 노드를 찾으려고 하면, 자식 노드들이 아직 생성되지 않은 상태라 에러(Null)가 발생합니다.

GDScript

 

extends Node2D

# [X] 에러 발생! 스크립트가 로드되는 시점에는 $Player 노드가 아직 존재하지 않습니다.
var player = $Player 

func _ready():
    player.jump()

이 문제를 해결하려면 예전에는 변수를 먼저 선언하고, _ready() 함수 안에서 노드를 할당하는 귀찮은 2단계 과정을 거쳐야 했습니다.

2. @onready의 마법: 코드를 한 줄로 줄이기

변수 앞에 @onready를 붙여주면, 고도 엔진에게 "이 변수는 메모리에 뜰 때가 아니라, 이 노드와 자식 노드들이 씬에 완전히 준비(_ready)되었을 때 값을 채워 넣어줘!"라고 부탁하는 것입니다. 덕분에 귀찮은 2단계 코드를 깔끔하게 한 줄로 줄일 수 있습니다.

GDScript

 

extends Node2D

# [O] 정상 작동! 노드가 준비되는 타이밍에 맞춰 $Player를 안전하게 가져옵니다.
@onready var player = $Player
@onready var sprite = $Sprite2D

func _ready():
    # 이제 ready 함수 안에서 바로 사용할 수 있습니다.
    player.jump()
    sprite.play("idle")

3. [실전 팁] @onready와 타입 힌팅(Type Hinting)

실전 개발에서는 @onready를 사용할 때 해당 노드가 어떤 종류(타입)인지 명시해 주는 것이 좋습니다. 이렇게 하면 점(.)을 찍었을 때 자동 완성 기능이 완벽하게 작동하여 오타를 줄이고 개발 속도를 엄청나게 높여줍니다.

GDScript

 

# 1. 정석적인 타입 명시 방법 (자동 완성이 지원됩니다)
@onready var dynamic_label: Label = $Label

# 2. 고도 엔진이 타입을 자동으로 추론하게 하는 방법 (:= 사용)
@onready var audio_player := $AudioStreamPlayer2D

func _ready():
    dynamic_label.text = "안녕하세요!" # .text 가 자동 완성됨
    audio_player.play()             # .play() 가 자동 완성됨

한눈에 보는 @onready 핵심 요약

비교 항목	일반 변수 선언 (var)	온레디 변수 선언 (@onready var)
값 할당 타이밍	스크립트 객체가 메모리에 생성될 때 (_init 시점)	노드와 자식이 씬 트리에 준비 완료될 때 (_ready 직전)
$ (노드 접근) 가능 여부	불가능 (에러 발생 및 게임 크래시)	가능 (안전하게 노드를 찾아와 저장함)
주요 사용 목적	숫자, 문자열, 리스트 등 일반적인 데이터 초기화	주로 다른 자식 노드나 UI 요소를 변수에 담아둘 때
실전 코드 예시	var max_hp = 100	@onready var hp_bar = $ProgressBar