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

Introduction: Keywords to Annotations はじめに：キーワードからアノテーションへ

Godot 4 replaced several GDScript keywords with @-prefixed annotations. This was part of a larger effort to make GDScript syntax cleaner and more consistent. The three most important changes are: Godot 4では、GDScriptの複数のキーワードが@プレフィックス付きのアノテーションに置き換えられました。これはGDScriptの構文をより明確で一貫性のあるものにするための大きな変更の一部です。最も重要な3つの変更は：

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

Annotations are placed on the line before (or on the same line as) the declaration they modify. Godot 4 also introduced many new annotation variants like @export_range, @export_group, and @export_category that did not exist in Godot 3. This guide covers all of them. アノテーションは修飾する宣言の前の行（または同じ行）に配置します。Godot 4ではGodot 3には存在しなかった@export_range、@export_group、@export_categoryなど、多くの新しいアノテーションバリアントも導入されました。このガイドではそれらすべてを解説します。

Basic @export 基本的な@export

The @export annotation exposes a variable in the Godot Inspector, letting you configure values without editing code. Godot automatically picks the right editor widget based on the variable's type. @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

Tip: Always add type annotations to exported variables. This ensures the Inspector shows the correct widget (e.g., a color picker for Color, a resource slot for Texture2D). ヒント： エクスポートする変数には必ず型アノテーションを付けましょう。これによりインスペクターが正しいウィジェットを表示します（例：Colorにはカラーピッカー、Texture2Dにはリソーススロット）。

@export_range — Numeric Sliders @export_range — 数値スライダー

@export_range restricts a numeric value to a minimum and maximum, displaying a slider in the Inspector. You can also specify a step size and hints like "or_greater" or "or_less". @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

The "or_greater" hint allows typing values above the maximum while keeping the slider range focused. Similarly, "or_less" allows values below the minimum. "or_greater"ヒントはスライダーの範囲を保ちつつ、最大値以上の値の手入力を許可します。同様に、"or_less"は最小値以下の値を許可します。

@export_enum — Dropdown Menus @export_enum — ドロップダウンメニュー

@export_enum creates a dropdown in the Inspector. When used with String, the selected option name is stored. When used with int, you can assign explicit values. @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 and @export_dir — File/Directory Paths @export_fileと@export_dir — ファイル/ディレクトリパス

@export_file shows a file dialog in the Inspector. You can filter by file extension. @export_dir shows a directory selection dialog. @export_fileはインスペクターにファイルダイアログを表示します。拡張子でフィルタリングも可能です。@export_dirはディレクトリ選択ダイアログを表示します。

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

The filter string uses glob patterns. Multiple filters can be separated with commas: "*.png,*.jpg". フィルタ文字列はグロブパターンを使用します。複数のフィルタはカンマで区切れます："*.png,*.jpg"。

@export_multiline and @export_placeholder @export_multilineと@export_placeholder

@export_multiline provides a large text area for multi-line strings (great for dialogue or descriptions). @export_placeholder shows hint text inside the field when it is empty. @export_multilineは複数行テキスト用の大きなテキストエリアを提供します（台詞や説明文に最適）。@export_placeholderはフィールドが空のときにヒントテキストを表示します。

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

@export_group and @export_subgroup — Organize Inspector Properties @export_groupと@export_subgroup — インスペクタープロパティの整理

@export_group creates a collapsible group header in the Inspector. All @export variables that follow belong to that group until the next group or category. @export_subgroup nests within the current group. @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

Groups and subgroups are purely organizational — they do not affect variable access in code, only how properties appear in the Inspector. グループとサブグループは純粋に整理のためのものです。コードでの変数アクセスには影響せず、インスペクターでのプロパティ表示にのみ影響します。

@export_category — Bold Category Headers @export_category — 太字カテゴリヘッダー

@export_category creates a bold, top-level category header in the Inspector. Unlike groups, categories cannot be collapsed and act as a strong visual separator between unrelated sets of properties. @export_categoryはインスペクターに太字のトップレベルカテゴリヘッダーを作成します。グループとは異なり、カテゴリは折りたたみできず、関連性のないプロパティセット間の強い視覚的な区切りとして機能します。

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

@export with Node References ノード参照の@export

You can export a NodePath to let designers pick a node from the scene tree. In Godot 4.2+, you can directly export a typed node reference — no NodePath needed. 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

Typed node exports are the recommended approach in modern Godot 4. The Inspector shows a node picker filtered to the specified type, and you get full autocompletion in the script editor. 型付きノードエクスポートは最新のGodot 4で推奨されるアプローチです。インスペクターは指定された型でフィルタリングされたノードピッカーを表示し、スクリプトエディタで完全な自動補完が得られます。

@export_flags — Bitmask Checkboxes @export_flags — ビットマスクチェックボックス

@export_flags creates a set of checkboxes where each option corresponds to a bit in an integer. Godot also provides built-in flag exports for physics and render layers. @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 — Deferred Initialization @onready — 遅延初期化

@onready defers variable initialization until the node enters the scene tree (equivalent to assigning in _ready()). This is essential when referencing child nodes with $, because children are not available at parse time. @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

Best practice: Always type your @onready variables. This enables autocompletion and catches type errors at parse time instead of runtime. ベストプラクティス： @onready変数には必ず型を付けましょう。自動補完が有効になり、実行時ではなくパース時に型エラーをキャッチできます。

@tool — Run Scripts in the Editor @tool — エディタ内でスクリプトを実行

@tool makes a script execute inside the Godot editor (not just at runtime). This is powerful for creating custom previews, gizmos, and live-updating properties. Place it at the very top of the script, before extends. @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)

Warning: Be careful with @tool scripts. Code in _process() and _physics_process() will run in the editor. Use Engine.is_editor_hint() to guard game-only logic. 注意： @toolスクリプトは慎重に使いましょう。_process()や_physics_process()のコードはエディタ内でも実行されます。ゲーム専用のロジックはEngine.is_editor_hint()でガードしてください。

Other Annotations その他のアノテーション

@icon

Sets a custom icon for the script's node type in the Scene dock and Create Node dialog. シーンドックや「ノード作成」ダイアログでスクリプトのノードタイプにカスタムアイコンを設定します。

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

@warning_ignore

Suppresses specific GDScript warnings for the next statement. Useful when you intentionally shadow a variable or have an unused parameter. 次のステートメントの特定のGDScript警告を抑制します。意図的に変数をシャドウする場合や未使用パラメータがある場合に便利です。

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

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

@static_unload

Marks a script so Godot can unload it from memory when no instances exist. This can reduce memory usage for scripts that are only used temporarily. The script must not have any static variables or data that needs to persist. インスタンスが存在しないときにスクリプトをメモリからアンロードできるようにマークします。一時的にのみ使用されるスクリプトのメモリ使用量を削減できます。永続化が必要な静的変数やデータがないスクリプトに使用してください。

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

Static Typing Best Practices 静的型付けのベストプラクティス

While not annotations, static type hints are closely related and strongly recommended in Godot 4. They improve autocompletion, enable compile-time error checking, and can improve performance. アノテーションではありませんが、静的型ヒントは密接に関連しており、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

Note: Be careful with := in for loops when iterating over untyped arrays. Use explicit type annotations instead: for item: String in array. 注意： 型なし配列のforループで:=を使う際は注意してください。代わりに明示的な型アノテーションを使いましょう：for item: String in array。

Migration Cheat Sheet: Godot 3 to 4 移行チートシート：Godot 3から4へ

Quick reference for converting Godot 3 export syntax to Godot 4 annotations: Godot 3のエクスポート構文をGodot 4のアノテーションに変換するクイックリファレンス：