Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

노드와 씬 인스턴스

이 가이드에서는 노드를 가져오고, 노드를 만들고, 하위 항목으로 추가하고, 코드에서 장면을 인스턴스화하는 방법을 설명합니다.

씬 인스턴싱에 대한 Godot의 접근 방식에 대해 알아보려면 인스턴스 만들기 튜토리얼을 확인하세요.

노드 만들기

노드.get_node() 메서드를 호출하여 노드에 대한 참조를 얻을 수 있습니다. 이것이 작동하려면 자식 노드가 씬 트리에 있어야 합니다. 상위 노드의 _ready() 기능으로 가져오면 이를 보장합니다.

예를 들어, 이와 같은 씬 트리가 있고 Sprite2D 및 Camera2D 노드에 대한 참조를 가져와 스크립트에서 액세스하려는 경우.

../../_images/nodes_and_scene_instances_player_scene_example.webp

인터페이스를 활성화하기 위해, 다음 코드를 실행합니다:

var sprite2d
var camera2d

func _ready():
    sprite2d = get_node("Sprite2D")
    camera2d = get_node("Camera2D")

private Sprite2D _sprite2D;
private Camera2D _camera2D;

public override void _Ready()
{
    base._Ready();

    _sprite2D = GetNode<Sprite2D>("Sprite2D");
    _camera2D = GetNode<Camera2D>("Camera2D");
}

유형이 아닌 이름을 사용하여 노드를 얻습니다. 위의 "Sprite2D"와 "Camera2D"는 씬의 노드 이름입니다.

씬 독에서 Sprite2D 노드의 이름을 Skin으로 바꾸면 스크립트에서 노드를 가져오는 줄을 ``get_node("Skin")``로 변경해야 합니다.

노드 경로 복사

노드에 대한 참조를 얻을 때 직접적인 하위 항목을 얻는 데만 국한되지 않습니다. get_node() 기능은 파일 브라우저로 작업할 때와 마찬가지로 경로를 지원합니다. 노드를 구분하려면 슬래시를 추가하세요.

UserInterface 노드에 스크립트가 연결된 다음 씬 예제를 살펴보겠습니다.

../../_images/nodes_and_scene_instances_ui_scene_example.webp

인터페이스를 활성화하기 위해, 다음 코드를 실행합니다:

var animation_player

func _ready():
    animation_player = get_node("ShieldBar/AnimationPlayer")

private AnimationPlayer _animationPlayer;

public override void _Ready()
{
    base._Ready();

    _animationPlayer = GetNode<AnimationPlayer>("ShieldBar/AnimationPlayer");
}

참고

파일 경로와 마찬가지로 ".."를 사용하여 상위 노드를 얻을 수 있습니다. 가장 좋은 방법은 캡슐화를 깨뜨리지 않더라도 그렇게 하지 않는 것입니다. 슬래시로 경로를 시작하여 절대 경로로 만들 수도 있습니다. 이 경우 최상위 노드는 응용 프로그램의 사전 정의된 루트 뷰포트인 "/root"가 됩니다.

구문 설탕

GDScript에서 코드를 단축하기 위해 두 가지 단축어를 사용할 수 있습니다. 첫째, 멤버 변수 앞에 @onready 주석을 넣으면 _ready() 콜백 직전에 초기화됩니다.

@onready var sprite2d = get_node("Sprite2D")

``get_node()``에 대한 짧은 표기법도 있습니다: 달러 기호 "$". 얻으려는 노드의 이름이나 경로 앞에 배치합니다.

@onready var sprite2d = $Sprite2D
@onready var animation_player = $ShieldBar/AnimationPlayer

노드 만들기

다른 클래스 기반 데이터 유형과 마찬가지로, 코드로 노드를 만들려면 .new() 메서드를 호출해야 합니다. 예를 들어:

새로 생성된 노드의 참조를 변수에 저장하고 ``add_child()``를 호출하여 스크립트를 연결한 노드의 하위 항목으로 추가할 수 있습니다.

var sprite2d

func _ready():
    sprite2d = Sprite2D.new() # Create a new Sprite2D.
    add_child(sprite2d) # Add it as a child of this node.

private Sprite2D _sprite2D;

public override void _Ready()
{
    base._Ready();

    _sprite2D = new Sprite2D(); // Create a new Sprite2D.
    AddChild(_sprite2D); // Add it as a child of this node.
}

노드를 삭제하고 메모리에서 해제하려면 해당 queue_free() 메서드를 호출하면 됩니다. 이렇게 하면 처리가 완료된 후 현재 프레임 끝에서 삭제를 위해 노드가 대기열에 추가됩니다. 이 시점에서 엔진은 씬에서 노드를 제거하고 메모리에서 개체를 해제합니다.

sprite2d.queue_free()

_sprite2D.QueueFree();

``sprite2d.queue_free()``를 호출하기 전의 원격 씬 트리는 다음과 같습니다.

엔진이 노드를 해제한 후 원격 씬 트리는 더 이상 스프라이트를 표시하지 않습니다.

또는 ``free()``를 호출하여 노드를 즉시 삭제할 수도 있습니다. 이에 대한 참조는 즉시 ``null``가 되므로 주의해서 수행해야 합니다. 수행 중인 작업을 잘 모르는 경우에는 ``queue_free()``를 사용하는 것이 좋습니다.

노드를 해제하면 해당 자식 노드도 모두 해제됩니다. 덕분에 씬 트리의 전체 분기를 삭제하려면 최상위 상위 노드만 해제하면 됩니다.

씬 인스턴스화하기

장면은 원하는 만큼 복제물을 만들 수 있는 템플릿입니다. 이 작업을 인스턴스화라고 하며 코드에서 수행하는 작업은 두 단계로 이루어집니다.

코드에서 리소스 불러오기
씬의 인스턴스를 얻으려면 PackedScene.instance() 메서드를 사용해야 합니다.

var scene = load("res://my_scene.tscn")

var scene = GD.Load<PackedScene>("res://MyScene.tscn");

컴파일러가 런타임 시가 아니라 스크립트를 읽을 때 로드 작업이 발생하므로 씬을 미리 로드하면 사용자 경험이 향상될 수 있습니다. 이 기능은 GDScript에서만 사용할 수 있습니다.

var scene = preload("res://my_scene.tscn")

그러나 씬은 아직 노드가 아닙니다. 씬은 PackedScene이라는 특수 리소스에 패키징되어 있습니다. 실제 노드를 만들려면 PackedScene.instance() 함수를 호출해야 합니다. 그러면 PackedScene은 작동중인 씬에 추가할 수 있는 노드 트리를 반환합니다:

var instance = scene.instantiate()
add_child(instance)

var instance = scene.Instantiate();
AddChild(instance);

이 두 단계 처리는 PackedScene이 불러온 상태로 유지되고 언제나 사용될 준비가 되어 있다는 장점이 있습니다. 이렇게 해서 인스턴스를 원하는 만큼 만들 수 있습니다. 이는 특히 활성 씬에서 많은 적, 총알, 그 외 다른 개체를 신속하게 인스턴스화하는 데 유용합니다.