基本編 on Godot 4 レシピ

ツリー順序を理解しよう

Mon, 01 Jan 0001 00:00:00 +0000

ℹ️ 留意事項

この記事は Godot 3から Godot 4 へ内容の書き換え中です。 Godot4では存在しない変数、関数が含まれている場合があります。もしその場合はリポジトリのIssuesまでご報告ください。

課題

Godotがシーンツリー内のノードをどのように処理するかを理解しておく必要があります。

解決策

「ツリー順序」はGodotの公式ドキュメントやチュートリアルで頻出する概念ですが、初心者にはその意味が直感的に理解しにくいものです。基本的に、ノードがツリー内で処理される順番は 上から下へ で、ルートノードを起点として、各ブランチごとに順番に下層へと降りていくのが原則です。

シーンツリーの順序管理は、Godot初心者にとって非常に混乱しやすい要素です。この例では、各処理がどのような順番で実行されるかを具体的に解説します。

以下にサンプルノード設定例をご紹介します。

各ノードには以下のスクリプトがアタッチされています。

extends Node

func _init():
 # Note: a Node doesn't have a "name" yet here.
 print("TestRoot init")

func _enter_tree():
 print(name + " enter tree")

func _ready():
 print(name + " ready")

# This ensures we only print *once* in process().
var test = true
func _process(delta):
 if test:
 print(name + " process")
 test = false

結果について議論する前に、まず各コールバック関数が何を表しているのかを整理します。

_init() はオブジェクトが最初に作成された際に呼び出されます。この時点でオブジェクトのインスタンスがコンピュータのメモリ上に確保されます。
_enter_tree() はノードが初めてツリーに追加される際に呼び出されます（インスタンス化時や add_child() を使用した場合など）。

ノードパスを理解しよう

Mon, 01 Jan 0001 00:00:00 +0000

ℹ️ 留意事項

課題

「無効なノード参照」、これはGodotヘルプチャンネルで最も頻繁に報告される問題の一つです。ほとんどの場合、以下のようなエラーメッセージとして表示されます。

Invalid get index ‘position’ (on base: ’null instance’).

解決策

問題の核心は「nullインスタンス」部分にあり、これがGodot初心者にとって最も混乱を招く要因となっています。

この問題を回避するには、「ノードパス」の仕組みを理解することが重要です。

ノードパスの理解

シーンツリーはノードで構成されており、これらは親子関係によって接続されています。ノードパスとは、このツリー構造を辿りながらあるノードから別のノードへ移動する際に通る経路のことです。

例として、シンプルな「プレイヤー」シーンを考えてみます。

このシーンのスクリプトは Player ノードに実装されています。もしスクリプトが AnimatedSprite ノードに対して play() メソッドを呼び出す必要がある場合、そのノードへの参照が必要となります。

get_node("AnimatedSprite").play()

get_node() 関数の引数は、対象ノードへのパスを表す文字列です。ここではスクリプト実行中のノードの子要素を指定します。指定したパスが無効な場合、厄介な null instance エラーが発生するほか（さらに「ノードが見つかりませんでした」というメッセージも表示されます）。

ノード参照を get_node() で取得する状況は非常に頻繁にあるため、GDScript にはそのためのショートカットが用意されています。

$AnimatedSprite.play()

情報

get_node() 関数は、対象ノードへの参照を返します。

ではここで、より複雑なシーンツリーを見てみてください。

もし Main スクリプトが ScoreLabel にアクセスする必要がある場合、以下のパスを使用してアクセスできます。

get_node("HUD/ScoreLabel").text = "0"
# or using the shortcut:
$HUD/ScoreLabel.text = "0"

ヒント

ドル記号($)を使用した場合、Godotエディタがパスを自動補完します。またシーンタブでノードを右クリックし、「ノードのパスをコピー」を選択する方法もあります。

ノード間のやりとり（良い方法）

Mon, 01 Jan 0001 00:00:00 +0000

情報

本記事の元ネタとなったGodot Discordの@TheDurielによる原型図に心から感謝します。この資料は保存しておき、必要に応じて参照できる状態にしておくことをオススメします。

課題

プロジェクトが複雑化してきました。複数のシーン、インスタンス、そして膨大な数のノードが存在しています。以下のようなコードが沢山ありませんか。

get_node("../../SomeNode/SomeOtherNode")
get_parent().get_parent().get_node("SomeNode")
get_tree().get_root().get_node("SomeNode/SomeOtherNode")

このようにノード参照すると、すぐに問題が発生することに気づくでしょう。シーンツリーの何かを変更すると、これらの参照がすべて無効になる可能性があるからです。

もっと良い方法があります。ノード間やシーン間のやり取りをシンプルにしていきましょう。

解決策

基本的に、ノードはその子ノードを管理するべきです。逆の関係(子ノードが親ノードを管理する)は避ける必要があります。get_parent()やget_node("..")を使用している場合、すでに問題が発生し始めています。このようなノードパスは脆弱であり、簡単に壊れてしまう性質があります。この構成には主に3つの重大な問題点があります。

シーンを単独でテストすることはできません。そのシーン単体、あるいは厳密に同一のノード構成を持たないテストシーンで実行した場合、get_node() メソッドがクラッシュを引き起こします。
変更は簡単にはできません。ツリーの構造を変更する場合、パスが無効になる可能性があります。
ノードの_ready()が呼ばれる順番は、子ノード優先、親ノード後回しとなります。つまり、ノードの _ready() メソッド内で親プロパティにアクセスしようとすると失敗するケースがあります。これは親ノードがまだ準備中(_ready()が呼ばれていない)状態であるためです。

ヒント

ノードがツリー構造にどのように追加され、準備完了状態になるかについては、ツリー順序を理解するを参照してください。

一般的に、ノードやシーンはゲーム内の任意の場所でインスタンス化可能であるべきであり、その親オブジェクトがどのようなものになるかについて一切仮定すべきではありません。

このチュートリアルでは後ほど詳細な例を紹介しますが、現時点でのノード間通信における「基本原則」は以下の通りです。

「下には呼び出しで」「上にはシグナルで」

ノードが子要素を呼び出している場合（つまりツリー構造を「下方向に」移動している場合）には、get_node() メソッドを使用するのが適切です。

ノードが「ツリー構造の上位」とやり取りする場合、シグナルを使用する方が適切でしょう。

シーン設定を設計する際にこのルールを念頭に置いておけば、メンテナンス性に優れ、整理されたプロジェクト構築への道筋が自然と見えてきます。また、問題を引き起こす煩雑なノードパスの使用も避けられるでしょう。

それでは、これらの戦略を具体例とともに見ていきます。

1. `get_node()` を使用する方法

get_node() は、指定されたパスを使用してシーンツリーを辿り、指定した名前のノードを検索します。

ヒント

ノードパスについてより詳しく知りたい場合は、ノードパスの理解を参照してください。

`get_node()` の使用例

以下の一般的な設定例について考えてみます。

Player ノード内のスクリプトでは、プレイヤーの移動状況に応じて、AnimatedSprite2Dにどのアニメーションを再生すべきか通知する必要があります。このようなケースでは get_node() が適しています。

extends CharacterBody2D

func _process(delta):
 if speed > 0:
 get_node("AnimatedSprite2D").play("run")
 else:
 get_node("AnimatedSprite2D").play("idle")

ヒント

GDScriptでは、get_node()の省略形として$を使用できます。代わりに$AnimatedSprite2Dと記述してください。

理解しよう！'delta'

Mon, 01 Jan 0001 00:00:00 +0000

ℹ️ 留意事項

課題

このdeltaパラメーター（delta time）は、ゲーム開発において誤解されがちな概念です。本チュートリアルでは、どのように使用されるのか、フレームレートに依存しない移動の重要性、そしてGodotにおける実践的な使用例について解説します。

解決策

問題を具体的に説明するため、画面上を移動するSpriteノードを考えてみます。画面幅が 600 ピクセルで、スプライトがこのスクリーン全体を横切るのに 5 秒かかる場合、必要な移動速度は以下の計算で求められます。

600 pixels / 5 seconds = 120 pixels/second

_process()関数を使用して各フレームでスプライトを移動させます。ゲームが 60 フレーム/秒で動作している場合、フレームごとの移動量は次のように計算できます：

120 pixels/second * 1/60 second/frame = 2 pixels/frame

ヒント

上記のすべての計算において、単位が統一されていることに注目してください。常に計算式で使用する単位に注意を払います。これにより、ミスを防ぐことができます。

以下に必要なコードを示します。

extends Node2D

# Desired movement in pixels/frame
var movement = Vector2(2, 0)

func _process(delta):
 $Sprite.position += movement

このコードを実行すると、スプライトが画面を横切るのに5秒かかることがわかります。

このコードだと、コンピュータが他のタスクでリソースを消費している場合に問題が発生します。これは「ラグ」と呼ばれます。コード自体の問題や他の実行中アプリケーションに起因する可能性があります。この状況では、フレームの長さが増加します。極端な例として、フレームレートが半減した場合を考えてみます。各フレームの処理時間が60分の1秒から30分の1秒になります。2 ピクセル/フレームで移動しているスプライトの場合、画面端に到達するまでにこれまでの2倍の時間がかかることになります。

たとえ微小なフレームレートの変動があったとしても、動きの速さが一定に保たれなければなりません。これが銃弾など高速で移動する物体であれば、速度が落ちるのを避けたいです。この移動動作を フレームレートに依存しない ようにする必要があります。

データを保存・読み込む

Mon, 01 Jan 0001 00:00:00 +0000

課題

ゲームセッション間でローカルデータを保存と読み込みたいです。

解決策

Godotのファイル入出力（IO）システムは FileAccess オブジェクトを基盤として構築されています。ファイルをオープンするには open() メソッドを呼び出します。

var file = FileAccess.open("user://myfile.name", File.READ)

警告

ユーザーデータは user:// パスにのみ保存します。エディタから直接実行している場合には res:// も使用できますが、プロジェクトをエクスポートすると、res:// パスは読み取り専用になります。

ファイルパスに続く2番目の引数は「モードフラグ」であり、以下のいずれかを指定できます。

FileAccess.READ - 読み取り専用でファイルを開く
FileAccess.WRITE - 書き込み専用でファイルを開く（存在しない場合は新規作成、存在する場合も先頭から再書き込み）
FileAccess.READ_WRITE - 読み書き両用モードでファイルを開く（既存ファイルは切り捨てない）
FileAccess.WRITE_READ - 読み書き両用モードでファイルを開く（存在しない場合は新規作成、存在する場合も先頭から再書き込み）

データの保存方法

データの保存には、その専用データ型（store_float()、store_string()など）を使用する方法と、汎用的なstore_var()メソッドを使用する方法があります。後者はGodotの組み込みのシリアライゼーション機能を利用してデータをエンコードするため、オブジェクトなどの複雑なデータ構造も扱えます（詳細は後述します）。

まずは簡単な例から始めてください。プレイヤーのハイスコアを保存する場合を考えます。必要に応じて呼び出せる関数を作成できます。

var save_path = "user://score.save"

func save_score():
 var file = FileAccess.open(save_path, FileAccess.WRITE)
 file.store_var(highscore)

スコアを保存していますが、ゲーム開始時にこのデータを読み込み可能な状態にしておく必要があります。

func load_score():
 if FileAccess.file_exists(save_path):
 print("file found")
 var file = FileAccess.open(save_path, FileAccess.READ)
 highscore = file.get_var()
 else:
 print("file not found")
 highscore = 0

ファイルを読み込もうとする前に、まずその存在を確認してください。存在しない場合もあるためです。存在しない場合は、デフォルト値を使用できます。

必要に応じて任意の数の値に対して何度でも store_var() および get_var() を使用できます。

Godot 3.x からの移行

Mon, 01 Jan 0001 00:00:00 +0000

これは、4.0への移行時に注意すべき主要な変更点と「落とし穴」をまとめた随時更新リストです。

新しい名称

Godot 4での最も大きな変化の一つは、ノード名、関数名、プロパティ名などの大量のリネームです。これらの多くは仕様の一貫性や可読性を向上させるために行われています。特に注意すべき主要な変更点をご紹介します。

2D/3Dノードの命名規則 - Godot 3.x では2Dノードに「2D」サフィックスが付いていた一方、3Dノードには何も付加されていませんでした。この不整合が解消され、現在ではすべてのノードが「2D」または「3D」を明示するようになりました。具体例：RigidBody2D と RigidBody3D。
3Dカテゴリにおいて、Spatialノードは名称をNode3Dに統一されています
最も人気のあるノードの1つである KinematicBody が、CharacterBody2D/CharacterBody3D に名称変更されました。このノードに関するAPIの変更点については、以下をご覧ください。
PackedScene の instance() 関数は instantiate() に改名されました
positionおよびglobal_positionプロパティは、3D空間において従来のtranslationとglobal_translationに取って代わり、2Dとの一貫性が保たれます。

シグナルと呼び出し可能オブジェクト

4.0ではシグナルの扱いが大幅に簡素化されています。signalはネイティブ型として扱われるようになったため、文字列を使用する機会が減り、オートコンプリートやエラーチェック機能が利用可能になりました。これは関数にも適用され、従来のような文字列参照ではなく、直接関数を指定できるようになりました。

以下に、シグナルの定義、接続、および送出の具体例を示します。

extends Node

signal my_signal

func _ready():
 my_signal.connect(signal_handler)

func _input(event):
 if event.is_action_pressed("ui_select"):
 my_signal.emit()

func signal_handler():
 print("signal received")

Tweens（中間アニメーション）

Godot 3.5 で SceneTreeTween を使い始めた場合、Godot 4.0 の Tween の使用方法は馴染み深いものでしょう。

Tweenはもはやノードとしてありません。代わりに、必要な時に都度1回限りのTweenアニメーションオブジェクトを作成する方式に変更されました。一度慣れてしまえば、従来の方法よりもはるかに強力で使いやすいものとなっています。

AnimatedSprite[2D|3D]

3.x系バージョンに慣れているユーザーにとって最も大きな変化は、playingプロパティが廃止された点です。現在はAnimationPlayerとの整合性が大幅に改善されており、アニメーションを自動再生するにはSpriteFramesパネルでオートプレイ機能を有効にするだけで済みます。コード側ではplay()メソッドとstop()メソッドを使用して、再生制御する形式に変更されました。

キャラクターボディ [2D/3D]

このノードにおける最大の変更点は move_and_slide() 関数の使用方法です。パラメーターは一切不要となり、すべてが組み込みプロパティとして実装されました。ネイティブの velocity（速度）プロパティも含まれているため、独自に定義する必要はありません。

これらのノードの詳細な使用例については、プラットフォームキャラクターおよび／または基本FPSキャラクタを参照してください。

タイルマップ

4.0版では TileMap ノードが全面的にリニューアルされました。TileSetの作成方法からタイルの描画・操作方法まで、ほぼすべてが完全に刷新されています。

「TileMap の使い方」ガイドが間もなく公開されます。

乱数生成

以下はGDScriptの組み込み乱数生成関数に対する変更点です。

もう randomize() を呼び出す必要はありません。自動で処理されます。再現性のある「乱数」が必要な場合は、seed() で事前に設定した値を指定します。

円運動

Mon, 01 Jan 0001 00:00:00 +0000

ℹ️ 留意事項

課題

オブジェクトを別のオブジェクトの周りで「周回」（円軌道を描くように移動）させたい。

解決策

これは初心者がよく抱く疑問で、三角関数をあれこれ試した後によく出てきます。答えは実はとてもシンプルです。

軌道周回させるスプライトをメインスプライトの子ノードに配置します（ここでは「ピボット」と呼びます）。オフセット値を適用し、Pivotで回転させます。

extends Node2D

@export var rotation_speed = PI


func _process(delta):
 $Sprite/Pivot.rotation += rotation_speed * delta

この手法は3D空間でも同じように機能します。

extends Node3D

@export var rotation_speed = PI


func _process(delta):
 $MeshInstance/Pivot.rotate_y(rotation_speed * delta)

カスタムリソースを使用

Mon, 01 Jan 0001 00:00:00 +0000

ℹ️ 留意事項

課題

ゲーム内でデータを処理する方法や、柔軟なデータオブジェクトを作成する方法を探しています。

解決策

GodotのResourceクラスは、データを格納・操作するための強力なツールです。Godotで扱う最も一般的なオブジェクトの多くはResourceタイプを拡張しています。アニメーション、衝突形状、画像など。リソースは単なるデータ保持だけでなく、そのデータを操作することもできます（Unityの ScriptableObject に似ています。）。

Godot に標準で用意されているすべての リソースタイプに加え、独自のカスタムリソースを作成してゲーム固有のデータを管理することもできます。これはデータの抽象化とカプセル化を実現する利点があり、ゲーム内の他のあらゆるオブジェクトから利用できる汎用的なコンポーネントを作成できます。

例：プレイヤーの移動

この例では、プラットフォーマーゲームにおけるプレイヤーのHP管理を取り上げます。多くのゲームプレイシステムはプレイヤーのHP・状態と連動しています。

プレイヤーが障害物に衝突するとダメージを受ける場合があります
敵キャラクターがプレイヤーに触れたり攻撃したりすることでダメージを与えられます
オブジェクトを拾う、または特定の場所に立つことでプレイヤーが回復できます
ゲーム画面にはHPゲージを表示し、発生する変化を適切に表示する必要があります

さらに、他の相互作用も存在する可能性があります。プレイヤーがHPを減らすとゲームのサウンドトラックが変化する、あるいは敵の行動パターンがプレイヤーのステータスに応じて変化する、といった具合です。

メモ

これは意図的に簡略化した例です。実際の運用では、ここで使用している機能よりも多くの機能が必要になる場合や、ゲームのアーキテクチャに合わせてこの例を修正する必要があるでしょう。

まず最初に、新しいカスタムリソースPlayerHealthを定義する必要があります。このリソースはHPに関連するプロパティを管理する必要があります。さらに、HPの変化（回復やダメージを受けるなど）を処理するための機能とシグナルを提供します。

Script タブで、 ファイル >新規スクリプト を選択します。Resourceを継承するように設定し、ファイル名を PlayerHealth.gd とします。

これを部分ごとに分解して考えてください。

上部には extends 行とリソースに割り当てる class_name があります。このページ名はエディター内の様々な場所で表示されます。

extends Resource
class_name PlayerHealth

次に、ゲームオブジェクトがプレイヤーのHP変化を監視するために購読できるシグナルがあります。また、HPがゼロに達するなどの追加イベント用のシグナルも実装できます。

signal health_changed

使用するプロパティです。

@export var max_value: int

var current_value = 0

この関数を使用すると、HPを最大値に初期化できます。ゲームの再起動時や新しいレベルを開始する際に実行するとよいでしょう。

func reset():
 current_value = max_value

この関数はプレイヤーにダメージが与えられた際に毎回呼び出されるべきです。

func take_damage(amount):
 current_value = max(0, current_value - amount)
 emit_signal("health_changed", current_value)

この関数はプレイヤーの回復が必要な時に随時呼び出されるべきです。

基本編 on Godot 4 レシピ

ツリー順序を理解しよう

課題

解決策

ノードパスを理解しよう

課題

解決策

ノードパスの理解

ノード間のやりとり（良い方法）

課題

解決策

1. get_node() を使用する方法

get_node() の使用例

理解しよう！'delta'

課題

解決策

データを保存・読み込む

課題

解決策

データの保存方法

Godot 3.x からの移行

新しい名称

シグナルと呼び出し可能オブジェクト

Tweens（中間アニメーション）

AnimatedSprite[2D|3D]

キャラクターボディ [2D/3D]

タイルマップ

乱数生成

円運動

課題

解決策

カスタムリソースを使用

課題

解決策

例：プレイヤーの移動

1. `get_node()` を使用する方法

`get_node()` の使用例