@export i adnotacje w Godot 4

Wprowadzenie: od słów kluczowych do adnotacji

Godot 4 zastąpił kilka słów kluczowych GDScript adnotacjami z prefiksem @. Było to częścią większego wysiłku, aby uczynić składnię GDScript czystszą i bardziej spójną. Trzy najważniejsze zmiany to:

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

Adnotacje umieszcza się w wierszu przed deklaracją, którą modyfikują (lub w tym samym wierszu). Godot 4 wprowadził również wiele nowych wariantów adnotacji, takich jak @export_range, @export_group i @export_category, których nie było w Godot 3. Ten przewodnik omawia je wszystkie.

Podstawowe @export

Adnotacja @export udostępnia zmienną w inspektorze Godota, pozwalając konfigurować wartości bez edycji kodu. Godot automatycznie dobiera odpowiedni widżet edytora na podstawie typu zmiennej.

@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

Wskazówka: Zawsze dodawaj adnotacje typu do eksportowanych zmiennych. Dzięki temu inspektor wyświetli właściwy widżet (np. próbnik koloru dla Color, slot zasobu dla Texture2D).

@export_range — Suwaki numeryczne

@export_range ogranicza wartość liczbową do minimum i maksimum, wyświetlając w inspektorze suwak. Można również określić rozmiar kroku oraz wskazówki takie jak "or_greater" lub "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

Wskazówka "or_greater" pozwala wpisywać wartości powyżej maksimum, zachowując jednocześnie skupiony zakres suwaka. Analogicznie "or_less" dopuszcza wartości poniżej minimum.

@export_enum — Menu rozwijane

@export_enum tworzy listę rozwijaną w inspektorze. Przy użyciu z typem String zapisywana jest nazwa wybranej opcji. Przy użyciu z typem int można przypisać jawne wartości.

# 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 i @export_dir — Ścieżki plików/katalogów

@export_file wyświetla w inspektorze okno dialogowe wyboru pliku. Można filtrować według rozszerzenia pliku. @export_dir wyświetla okno wyboru katalogu.

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

Łańcuch filtra używa wzorców glob. Wiele filtrów można rozdzielić przecinkami: "*.png,*.jpg".

@export_multiline i @export_placeholder

@export_multiline zapewnia duże pole tekstowe dla łańcuchów wielowierszowych (idealne do dialogów lub opisów). @export_placeholder wyświetla tekst podpowiedzi w polu, gdy jest ono puste.

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

@export_group i @export_subgroup — Organizacja właściwości inspektora

@export_group tworzy zwijany nagłówek grupy w inspektorze. Wszystkie następujące po nim zmienne @export należą do tej grupy aż do kolejnej grupy lub kategorii. @export_subgroup zagnieżdża się w bieżącej grupie.

@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

Grupy i podgrupy służą wyłącznie organizacji — nie wpływają na dostęp do zmiennych w kodzie, a jedynie na to, jak właściwości pojawiają się w inspektorze.

@export_category — Pogrubione nagłówki kategorii

@export_category tworzy pogrubiony nagłówek kategorii najwyższego poziomu w inspektorze. W przeciwieństwie do grup, kategorii nie można zwinąć i działają jako silny wizualny separator między niepowiązanymi zestawami właściwości.

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

@export z referencjami do węzłów

Możesz wyeksportować NodePath, aby projektanci mogli wybrać węzeł z drzewa sceny. W Godot 4.2+ możesz bezpośrednio wyeksportować typowaną referencję do węzła — NodePath nie jest już potrzebny.

# 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

Typowane eksporty węzłów są zalecanym podejściem we współczesnym Godot 4. Inspektor wyświetla próbnik węzłów przefiltrowany do wskazanego typu, a w edytorze skryptów otrzymujesz pełne autouzupełnianie.

@export_flags — Pola wyboru maski bitowej

@export_flags tworzy zestaw pól wyboru, w którym każda opcja odpowiada jednemu bitowi w liczbie całkowitej. Godot udostępnia również wbudowane eksporty flag dla warstw fizyki i renderowania.

# 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 — Opóźniona inicjalizacja

@onready opóźnia inicjalizację zmiennej do momentu, gdy węzeł wejdzie do drzewa sceny (odpowiednik przypisania w _ready()). Jest to niezbędne przy odwoływaniu się do węzłów potomnych za pomocą $, ponieważ węzły potomne nie są dostępne w czasie parsowania.

# 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

Najlepsza praktyka: Zawsze typuj swoje zmienne @onready. Umożliwia to autouzupełnianie i wychwytuje błędy typów w czasie parsowania zamiast w czasie działania.

@tool — Uruchamianie skryptów w edytorze

@tool sprawia, że skrypt wykonuje się wewnątrz edytora Godota (nie tylko w czasie działania). Jest to potężne narzędzie do tworzenia własnych podglądów, gizmów i właściwości aktualizowanych na żywo. Umieść je na samej górze skryptu, przed 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)

Ostrzeżenie: Zachowaj ostrożność ze skryptami @tool. Kod w _process() i _physics_process() będzie działał w edytorze. Użyj Engine.is_editor_hint(), aby zabezpieczyć logikę przeznaczoną tylko do gry.

Pozostałe adnotacje

@icon

Ustawia własną ikonę dla typu węzła skryptu w doku Scena oraz w oknie dialogowym „Utwórz węzeł".

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

@warning_ignore

Wycisza określone ostrzeżenia GDScript dla następnej instrukcji. Przydatne, gdy celowo przesłaniasz zmienną lub masz nieużywany parametr.

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

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

@static_unload

Oznacza skrypt tak, aby Godot mógł usunąć go z pamięci, gdy nie istnieją żadne instancje. Może to zmniejszyć zużycie pamięci przez skrypty używane tylko tymczasowo. Skrypt nie może mieć żadnych zmiennych statycznych ani danych, które muszą być zachowane.

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

Najlepsze praktyki typowania statycznego

Chociaż nie są to adnotacje, statyczne wskazówki typów są ściśle z nimi związane i mocno zalecane w Godot 4. Poprawiają autouzupełnianie, umożliwiają sprawdzanie błędów w czasie kompilacji i mogą poprawić wydajność.

# 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

Uwaga: Zachowaj ostrożność z := w pętlach for podczas iterowania po nietypowanych tablicach. Zamiast tego użyj jawnych adnotacji typu: for item: String in array.

Ściąga migracji: Godot 3 do 4

Szybki przewodnik po konwersji składni eksportu Godot 3 na adnotacje Godot 4: