Godot 4의 @export와 어노테이션

소개: 키워드에서 어노테이션으로

Godot 4는 여러 GDScript 키워드를 @ 접두사가 붙은 어노테이션으로 대체했습니다. 이는 GDScript 구문을 더 깔끔하고 일관성 있게 만들기 위한 더 큰 노력의 일부였습니다. 가장 중요한 세 가지 변경 사항은 다음과 같습니다:

• export → @export
• onready → @onready
• tool → @tool

어노테이션은 수정하는 선언의 앞 줄(또는 같은 줄)에 배치합니다. Godot 4는 또한 Godot 3에는 없던 @export_range, @export_group, @export_category와 같은 많은 새로운 어노테이션 변형을 도입했습니다. 이 가이드는 그 모두를 다룹니다.

기본 @export

@export 어노테이션은 변수를 Godot 인스펙터에 노출시켜 코드를 편집하지 않고도 값을 설정할 수 있게 합니다. Godot은 변수의 타입에 따라 적절한 에디터 위젯을 자동으로 선택합니다.

@export var speed: float = 300.0
@export var player_name: String = "Player"
@export var health: int = 100
@export var color: Color = Color.WHITE
@export var texture: Texture2D
@export var scene: PackedScene

팁: 익스포트하는 변수에는 항상 타입 어노테이션을 추가하세요. 그래야 인스펙터가 올바른 위젯을 표시합니다(예: Color에는 컬러 피커, Texture2D에는 리소스 슬롯).

@export_range — 숫자 슬라이더

@export_range는 숫자 값을 최솟값과 최댓값으로 제한하고, 인스펙터에 슬라이더를 표시합니다. 스텝 크기와 "or_greater", "or_less" 같은 힌트도 지정할 수 있습니다.

@export_range(0, 100) var health: int = 100
@export_range(0.0, 1.0, 0.01) var volume: float = 0.8
@export_range(0, 1000, 1, "or_greater") var damage: int = 10

"or_greater" 힌트는 슬라이더 범위를 집중적으로 유지하면서 최댓값을 초과하는 값을 입력할 수 있게 합니다. 마찬가지로 "or_less"는 최솟값 미만의 값을 허용합니다.

@export_enum — 드롭다운 메뉴

@export_enum은 인스펙터에 드롭다운을 생성합니다. String과 함께 사용하면 선택한 옵션의 이름이 저장됩니다. int와 함께 사용하면 명시적인 값을 할당할 수 있습니다.

# Stores the string name: "Warrior", "Mage", or "Rogue"
@export_enum("Warrior", "Mage", "Rogue") var character_class: String

# Stores the integer value: 0, 1, or 2
@export_enum("Easy:0", "Normal:1", "Hard:2") var difficulty: int = 1

@export_file와 @export_dir — 파일/디렉터리 경로

@export_file은 인스펙터에 파일 대화상자를 표시합니다. 파일 확장자로 필터링할 수 있습니다. @export_dir은 디렉터리 선택 대화상자를 표시합니다.

@export_file("*.tscn") var next_level: String
@export_dir var save_directory: String

필터 문자열은 glob 패턴을 사용합니다. 여러 필터는 쉼표로 구분할 수 있습니다: "*.png,*.jpg".

@export_multiline와 @export_placeholder

@export_multiline은 여러 줄 문자열을 위한 큰 텍스트 영역을 제공합니다(대사나 설명에 적합). @export_placeholder는 필드가 비어 있을 때 필드 안에 힌트 텍스트를 표시합니다.

@export_multiline var description: String
@export_placeholder("Enter name...") var player_name: String

@export_group와 @export_subgroup — 인스펙터 속성 정리

@export_group은 인스펙터에 접을 수 있는 그룹 헤더를 생성합니다. 그 뒤에 오는 모든 @export 변수는 다음 그룹이나 카테고리 전까지 해당 그룹에 속합니다. @export_subgroup은 현재 그룹 안에 중첩됩니다.

@export_group("Movement")
@export var speed: float = 300.0
@export var jump_force: float = 400.0

@export_group("Combat")
@export var attack_damage: int = 10
@export var defense: int = 5

@export_subgroup("Ranged")
@export var projectile_speed: float = 500.0

그룹과 서브그룹은 순전히 정리를 위한 것입니다 — 코드에서의 변수 접근에는 영향을 주지 않으며, 인스펙터에서 속성이 표시되는 방식에만 영향을 줍니다.

@export_category — 굵은 카테고리 헤더

@export_category는 인스펙터에 굵은 최상위 카테고리 헤더를 생성합니다. 그룹과 달리 카테고리는 접을 수 없으며, 서로 관련 없는 속성 집합 사이의 강한 시각적 구분자 역할을 합니다.

@export_category("Player Stats")
@export var level: int = 1
@export var experience: int = 0

노드 참조와 함께 사용하는 @export

NodePath를 익스포트하면 디자이너가 씬 트리에서 노드를 선택할 수 있습니다. Godot 4.2+에서는 타입이 지정된 노드 참조를 직접 익스포트할 수 있어 NodePath가 필요 없습니다.

# Classic NodePath export
@export var target_path: NodePath

# Godot 4.2+: typed node export (direct reference, no NodePath needed)
@export var sprite: Sprite2D
@export var collision: CollisionShape2D

타입이 지정된 노드 익스포트는 최신 Godot 4에서 권장되는 방식입니다. 인스펙터는 지정된 타입으로 필터링된 노드 피커를 표시하고, 스크립트 에디터에서 완전한 자동 완성을 사용할 수 있습니다.

@export_flags — 비트마스크 체크박스

@export_flags는 각 옵션이 정수의 비트에 대응하는 체크박스 집합을 생성합니다. Godot은 물리 레이어와 렌더 레이어를 위한 내장 플래그 익스포트도 제공합니다.

# Custom flags: Fire=1, Water=2, Earth=4, Wind=8
@export_flags("Fire", "Water", "Earth", "Wind") var elements: int

# Built-in physics layer flags
@export_flags_2d_physics var collision_layers: int
@export_flags_2d_render var render_layers: int
@export_flags_3d_physics var collision_layers_3d: int

@onready — 지연 초기화

@onready는 노드가 씬 트리에 들어올 때까지 변수 초기화를 지연시킵니다(_ready()에서 할당하는 것과 동일). 자식 노드는 파싱 시점에는 아직 사용할 수 없기 때문에, $로 자식 노드를 참조할 때 필수입니다.

# Godot 3 (old syntax):
# onready var sprite = $Sprite2D

# Godot 4:
@onready var sprite: Sprite2D = $Sprite2D
@onready var anim: AnimationPlayer = $AnimationPlayer
@onready var label: Label = $UI/ScoreLabel

모범 사례: @onready 변수에는 항상 타입을 지정하세요. 그러면 자동 완성이 활성화되고, 런타임이 아닌 파싱 시점에 타입 오류를 잡아낼 수 있습니다.

@tool — 에디터에서 스크립트 실행

@tool은 스크립트를 Godot 에디터 내에서 실행되게 합니다(런타임뿐만 아니라). 이는 커스텀 미리보기, 기즈모, 실시간으로 갱신되는 속성을 만드는 데 강력합니다. 스크립트의 맨 위, extends 앞에 배치하세요.

@tool
extends Node2D

@export var radius: float = 100.0:
    set(value):
        radius = value
        queue_redraw()  # Redraw in editor when value changes

func _draw() -> void:
    draw_circle(Vector2.ZERO, radius, Color.WHITE)

주의: @tool 스크립트는 신중하게 사용하세요. _process()와 _physics_process()의 코드는 에디터 안에서도 실행됩니다. 게임 전용 로직은 Engine.is_editor_hint()로 보호하세요.

기타 어노테이션

@icon

씬 독과 「노드 만들기」 대화상자에서 스크립트의 노드 타입에 대한 커스텀 아이콘을 설정합니다.

@icon("res://icons/enemy.svg")
extends CharacterBody2D

@warning_ignore

다음 문장에 대한 특정 GDScript 경고를 억제합니다. 의도적으로 변수를 섀도잉하거나 사용하지 않는 매개변수가 있을 때 유용합니다.

@warning_ignore("unused_parameter")
func _on_body_entered(body: Node2D) -> void:
    queue_free()

@warning_ignore("shadowed_variable")
var size: int = 10

@static_unload

인스턴스가 존재하지 않을 때 Godot이 스크립트를 메모리에서 언로드할 수 있도록 표시합니다. 이는 일시적으로만 사용되는 스크립트의 메모리 사용량을 줄일 수 있습니다. 스크립트에는 유지되어야 하는 정적 변수나 데이터가 없어야 합니다.

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

정적 타이핑 모범 사례

어노테이션은 아니지만, 정적 타입 힌트는 밀접하게 관련되어 있으며 Godot 4에서 강력히 권장됩니다. 자동 완성을 개선하고, 컴파일 타임 오류 검사를 가능하게 하며, 성능을 향상시킬 수 있습니다.

# Variable type annotations
var speed: float = 300.0
var player: CharacterBody2D = null
var items: Array[String] = []
var scores: Dictionary = {}

# Function return types and parameter types
func get_damage() -> int:
    return attack - defense

func apply_force(direction: Vector2, strength: float) -> void:
    velocity += direction * strength

# Type inference with :=
var pos := Vector2(100, 200)  # Inferred as Vector2

참고: 타입이 없는 배열을 순회할 때 for 루프에서 :=를 사용하는 것에 주의하세요. 대신 명시적인 타입 어노테이션을 사용하세요: for item: String in array.

마이그레이션 치트 시트: Godot 3에서 4로

Godot 3의 익스포트 구문을 Godot 4 어노테이션으로 변환하기 위한 빠른 참조: