@export dan Anotasi di Godot 4

Pengantar: Dari Keyword ke Anotasi

Godot 4 mengganti beberapa keyword GDScript dengan anotasi berawalan @. Ini adalah bagian dari upaya yang lebih besar untuk membuat sintaks GDScript lebih bersih dan konsisten. Tiga perubahan terpenting adalah:

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

Anotasi ditempatkan pada baris sebelum (atau pada baris yang sama dengan) deklarasi yang dimodifikasinya. Godot 4 juga memperkenalkan banyak varian anotasi baru seperti @export_range, @export_group, dan @export_category yang tidak ada di Godot 3. Panduan ini membahas semuanya.

@export Dasar

Anotasi @export menampilkan sebuah variabel di Godot Inspector, sehingga kamu dapat mengonfigurasi nilai tanpa mengedit kode. Godot secara otomatis memilih widget editor yang tepat berdasarkan tipe variabel.

@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

Tips: Selalu tambahkan anotasi tipe pada variabel yang diekspor. Ini memastikan Inspector menampilkan widget yang benar (mis. pemilih warna untuk Color, slot resource untuk Texture2D).

@export_range — Slider Numerik

@export_range membatasi nilai numerik ke rentang minimum dan maksimum, serta menampilkan slider di Inspector. Kamu juga dapat menentukan ukuran langkah (step) dan petunjuk seperti "or_greater" atau "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

Petunjuk "or_greater" memungkinkan pengetikan nilai di atas maksimum sambil tetap menjaga fokus rentang slider. Demikian pula, "or_less" memungkinkan nilai di bawah minimum.

@export_enum — Menu Dropdown

@export_enum membuat dropdown di Inspector. Saat digunakan dengan String, nama opsi yang dipilih akan disimpan. Saat digunakan dengan int, kamu dapat menetapkan nilai eksplisit.

# 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 dan @export_dir — Path File/Direktori

@export_file menampilkan dialog file di Inspector. Kamu dapat memfilter berdasarkan ekstensi file. @export_dir menampilkan dialog pemilihan direktori.

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

String filter menggunakan pola glob. Beberapa filter dapat dipisahkan dengan koma: "*.png,*.jpg".

@export_multiline dan @export_placeholder

@export_multiline menyediakan area teks besar untuk string multi-baris (bagus untuk dialog atau deskripsi). @export_placeholder menampilkan teks petunjuk di dalam kolom saat kosong.

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

@export_group dan @export_subgroup — Mengatur Properti Inspector

@export_group membuat header grup yang dapat diciutkan di Inspector. Semua variabel @export yang mengikutinya termasuk dalam grup tersebut hingga grup atau kategori berikutnya. @export_subgroup bersarang di dalam grup saat ini.

@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

Grup dan subgrup murni bersifat organisasional — keduanya tidak memengaruhi akses variabel dalam kode, hanya bagaimana properti muncul di Inspector.

@export_category — Header Kategori Tebal

@export_category membuat header kategori tebal tingkat teratas di Inspector. Berbeda dengan grup, kategori tidak dapat diciutkan dan berfungsi sebagai pemisah visual yang kuat antara kumpulan properti yang tidak berkaitan.

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

@export dengan Referensi Node

Kamu dapat mengekspor sebuah NodePath agar desainer dapat memilih node dari scene tree. Di Godot 4.2+, kamu dapat langsung mengekspor referensi node bertipe — tanpa perlu 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

Ekspor node bertipe adalah pendekatan yang direkomendasikan di Godot 4 modern. Inspector menampilkan pemilih node yang difilter ke tipe yang ditentukan, dan kamu mendapatkan autocompletion penuh di editor skrip.

@export_flags — Kotak Centang Bitmask

@export_flags membuat serangkaian kotak centang di mana setiap opsi berkaitan dengan satu bit dalam bilangan bulat. Godot juga menyediakan ekspor flag bawaan untuk layer fisika dan render.

# 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 — Inisialisasi Tertunda

@onready menunda inisialisasi variabel hingga node memasuki scene tree (setara dengan penetapan di _ready()). Ini penting saat mereferensikan child node dengan $, karena child belum tersedia pada waktu parse.

# 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

Praktik Terbaik: Selalu ketik variabel @onready-mu. Ini mengaktifkan autocompletion dan menangkap kesalahan tipe pada waktu parse alih-alih pada waktu runtime.

@tool — Menjalankan Skrip di Editor

@tool membuat sebuah skrip dieksekusi di dalam editor Godot (bukan hanya saat runtime). Ini sangat berguna untuk membuat pratinjau kustom, gizmo, dan properti yang diperbarui secara langsung. Tempatkan di paling atas skrip, sebelum 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)

Peringatan: Hati-hati dengan skrip @tool. Kode di _process() dan _physics_process() akan berjalan di editor. Gunakan Engine.is_editor_hint() untuk melindungi logika khusus game.

Anotasi Lainnya

@icon

Menetapkan ikon kustom untuk tipe node skrip di Scene dock dan dialog Create Node.

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

@warning_ignore

Menekan peringatan GDScript tertentu untuk pernyataan berikutnya. Berguna saat kamu sengaja membayangi (shadow) sebuah variabel atau memiliki parameter yang tidak digunakan.

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

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

@static_unload

Menandai sebuah skrip agar Godot dapat membongkarnya (unload) dari memori saat tidak ada instance. Ini dapat mengurangi penggunaan memori untuk skrip yang hanya digunakan sementara. Skrip tersebut tidak boleh memiliki variabel statis atau data yang perlu dipertahankan.

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

Praktik Terbaik Pengetikan Statis

Meskipun bukan anotasi, petunjuk tipe statis sangat berkaitan dan sangat direkomendasikan di Godot 4. Petunjuk tipe ini meningkatkan autocompletion, memungkinkan pengecekan kesalahan pada waktu kompilasi, dan dapat meningkatkan performa.

# 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

Catatan: Hati-hati dengan := di dalam perulangan for saat mengiterasi array tanpa tipe. Gunakan anotasi tipe eksplisit sebagai gantinya: for item: String in array.

Lembar Contekan Migrasi: Godot 3 ke 4

Referensi cepat untuk mengonversi sintaks ekspor Godot 3 menjadi anotasi Godot 4: