Godot 4の@exportとアノテーション完全ガイド

はじめに：キーワードからアノテーションへ

Godot 4では、GDScriptの複数のキーワードが@プレフィックス付きのアノテーションに置き換えられました。これはGDScriptの構文をより明確で一貫性のあるものにするための大きな変更の一部です。最も重要な3つの変更は：

• 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

フィルタ文字列はグロブパターンを使用します。複数のフィルタはカンマで区切れます："*.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

インスタンスが存在しないときにスクリプトをメモリからアンロードできるようにマークします。一時的にのみ使用されるスクリプトのメモリ使用量を削減できます。永続化が必要な静的変数やデータがないスクリプトに使用してください。

@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のアノテーションに変換するクイックリファレンス：