Godot 4'te @export ve Anotasyonlar

Giriş: Anahtar Kelimelerden Anotasyonlara

Godot 4, çeşitli GDScript anahtar kelimelerini @ önekli anotasyonlarla değiştirdi. Bu, GDScript sözdizimini daha temiz ve tutarlı hâle getirmeye yönelik daha büyük bir çabanın parçasıydı. En önemli üç değişiklik şunlardır:

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

Anotasyonlar, değiştirdikleri bildirimin önündeki satıra (veya aynı satıra) yerleştirilir. Godot 4 ayrıca Godot 3'te bulunmayan @export_range, @export_group ve @export_category gibi birçok yeni anotasyon varyantı da tanıttı. Bu rehber bunların tümünü kapsar.

Temel @export

@export anotasyonu bir değişkeni Godot Inspector'da görünür kılarak kodu düzenlemeden değerleri yapılandırmanıza olanak tanır. Godot, değişkenin tipine göre doğru editör bileşenini otomatik olarak seçer.

@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

İpucu: Dışa aktarılan değişkenlere her zaman tip anotasyonları ekleyin. Bu, Inspector'ın doğru bileşeni göstermesini sağlar (örneğin Color için bir renk seçici, Texture2D için bir kaynak yuvası).

@export_range — Sayısal Kaydırıcılar

@export_range sayısal bir değeri bir minimum ve maksimuma sınırlar ve Inspector'da bir kaydırıcı gösterir. Ayrıca bir adım boyutu ve "or_greater" ya da "or_less" gibi ipuçları da belirtebilirsiniz.

@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" ipucu, kaydırıcı aralığını odaklı tutarken maksimumun üzerindeki değerlerin yazılmasına izin verir. Benzer şekilde "or_less" minimumun altındaki değerlere izin verir.

@export_enum — Açılır Menüler

@export_enum Inspector'da bir açılır menü oluşturur. String ile kullanıldığında, seçilen seçeneğin adı depolanır. int ile kullanıldığında ise açık değerler atayabilirsiniz.

# 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 ve @export_dir — Dosya/Dizin Yolları

@export_file Inspector'da bir dosya iletişim kutusu gösterir. Dosya uzantısına göre filtreleyebilirsiniz. @export_dir bir dizin seçim iletişim kutusu gösterir.

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

Filtre dizesi glob kalıplarını kullanır. Birden çok filtre virgülle ayrılabilir: "*.png,*.jpg".

@export_multiline ve @export_placeholder

@export_multiline çok satırlı dizeler için büyük bir metin alanı sağlar (diyaloglar veya açıklamalar için idealdir). @export_placeholder alan boşken içinde bir ipucu metni gösterir.

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

@export_group ve @export_subgroup — Inspector Özelliklerini Düzenleme

@export_group Inspector'da katlanabilir bir grup başlığı oluşturur. Bunu izleyen tüm @export değişkenleri, bir sonraki gruba veya kategoriye kadar o gruba aittir. @export_subgroup geçerli grubun içine iç içe yerleşir.

@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

Gruplar ve alt gruplar tamamen düzenleme amaçlıdır — koddaki değişken erişimini etkilemez, yalnızca özelliklerin Inspector'da nasıl göründüğünü etkiler.

@export_category — Kalın Kategori Başlıkları

@export_category Inspector'da kalın, üst düzey bir kategori başlığı oluşturur. Gruplardan farklı olarak kategoriler katlanamaz ve birbiriyle ilgisiz özellik kümeleri arasında güçlü bir görsel ayraç işlevi görür.

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

Node Referanslarıyla @export

Tasarımcıların sahne ağacından bir düğüm seçebilmesi için bir NodePath dışa aktarabilirsiniz. Godot 4.2+ sürümünde, tipli bir düğüm referansını doğrudan dışa aktarabilirsiniz — NodePath gerekmez.

# 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

Tipli düğüm dışa aktarımları, modern Godot 4'te önerilen yaklaşımdır. Inspector, belirtilen tipe göre filtrelenmiş bir düğüm seçici gösterir ve betik editöründe tam otomatik tamamlama elde edersiniz.

@export_flags — Bit Maskesi Onay Kutuları

@export_flags her seçeneğin bir tam sayıdaki bir bite karşılık geldiği bir dizi onay kutusu oluşturur. Godot ayrıca fizik ve render katmanları için yerleşik bayrak dışa aktarımları da sağlar.

# 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 — Ertelenmiş Başlatma

@onready değişken başlatmayı, düğüm sahne ağacına girene kadar erteler (_ready() içinde atama yapmaya eşdeğerdir). Çocuk düğümler ayrıştırma (parse) zamanında henüz kullanılamadığından, $ ile çocuk düğümlere başvururken bu şarttır.

# 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

En iyi uygulama: @onready değişkenlerinizi her zaman tipleyin. Bu, otomatik tamamlamayı etkinleştirir ve tip hatalarını çalışma zamanı yerine ayrıştırma zamanında yakalar.

@tool — Betikleri Editörde Çalıştırma

@tool bir betiğin Godot editörü içinde çalışmasını sağlar (yalnızca çalışma zamanında değil). Bu, özel önizlemeler, gizmo'lar ve canlı güncellenen özellikler oluşturmak için güçlüdür. Betiğin en üstüne, extends ifadesinden önce yerleştirin.

@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)

Uyarı: @tool betiklerine dikkat edin. _process() ve _physics_process() içindeki kod editörde çalışır. Yalnızca oyuna özgü mantığı korumak için Engine.is_editor_hint() kullanın.

Diğer Anotasyonlar

@icon

Betiğin düğüm tipi için Sahne panelinde ve Düğüm Oluştur iletişim kutusunda özel bir simge ayarlar.

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

@warning_ignore

Bir sonraki ifade için belirli GDScript uyarılarını bastırır. Bilerek bir değişkeni gölgelediğinizde veya kullanılmayan bir parametreniz olduğunda kullanışlıdır.

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

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

@static_unload

Hiçbir örnek yokken Godot'un betiği bellekten kaldırabilmesi için betiği işaretler. Bu, yalnızca geçici olarak kullanılan betikler için bellek kullanımını azaltabilir. Betikte, kalıcı olması gereken herhangi bir statik değişken veya veri bulunmamalıdır.

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

Statik Tipleme En İyi Uygulamaları

Anotasyon olmasalar da, statik tip ipuçları bunlarla yakından ilişkilidir ve Godot 4'te şiddetle önerilir. Otomatik tamamlamayı iyileştirir, derleme zamanı hata denetimine olanak tanır ve performansı artırabilir.

# 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

Not: Tipsiz diziler üzerinde yineleme yaparken for döngülerinde := kullanırken dikkatli olun. Bunun yerine açık tip anotasyonları kullanın: for item: String in array.

Geçiş Kopya Kâğıdı: Godot 3'ten 4'e

Godot 3 dışa aktarma sözdizimini Godot 4 anotasyonlarına dönüştürmek için hızlı başvuru: