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...

ノードとシーンインスタンス

このガイドでは、ノードの取得、ノードの作成、それらを子として追加し、コードからシーンをインスタンス化する方法について説明します。

参考

Check the インスタンスの作成 tutorial to learn about Godot's approach to scene instantiation.

ノードの取得

ノードへの参照を取得するには Node.get_node() メソッドを呼び出します。これが機能するには、子ノードがシーンツリーに存在する必要があります。親ノードの _ready() 関数でそれを取得することで、それが保証されます。

If, for example, you have a scene tree like this, and you want to get a reference to the Sprite2D and Camera2D nodes to access them in your script.

../../_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() 関数はパスをサポートしており、ファイルブラウザを操作する場合と似ています。ノードを区切るにはスラッシュを追加します。

次のシーン例を考えてみましょう。UserInterfacノードにスクリプトがアタッチされています。

../../_images/nodes_and_scene_instances_ui_scene_example.webp

AnimationPlayerノードを取得するには、次のコードを使用します。

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" になります。

シンタックスシュガー

2つの短縮表現を使用して、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() を呼び出す前のリモートシーンツリーは次のようになります。

エンジンがノードを解放すると、リモートシーンツリーにはスプライトが表示されなくなります。

You can alternatively call free() to immediately destroy the node. You should do this with care as any reference to it will instantly become invalid. We recommend using queue_free() unless you know what you're doing.

ノードを解放すると、そのノードのすべての子も解放されます。このおかげでシーンツリーのブランチ全体を削除するには、最上位の親ノードを解放するだけで済みます。

Instantiating scenes

Scenes are templates from which you can create as many reproductions as you'd like. This operation is called instantiation, and doing it from code happens in two steps:

ローカルドライブからシーンをロードします。
ロードされた PackedScene リソースのインスタンスを作成します。

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

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

シーンをプリロードすると、ロード操作は実行時ではなくコンパイラがスクリプトを読み取るときに実行されるため、ユーザーエクスペリエンスが向上します。この機能は GDScript でのみ使用できます。

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

その時点で scene はまだノードではなく、パックされたシーンのリソースです。実際のノードを作成するには、 PackedScene.instantiate() 関数を呼び出す必要があります。これにより現在のノードの子として使用できるノードのツリーが返されます。

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

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

The advantage of this two-step process is you can keep a packed scene loaded and create new instances on the fly. For example, to quickly instantiate several enemies or bullets.