@export e anotações no Godot 4

Introdução: de palavras-chave a anotações

O Godot 4 substituiu várias palavras-chave do GDScript por anotações prefixadas com @. Isso fez parte de um esforço maior para tornar a sintaxe do GDScript mais limpa e consistente. As três mudanças mais importantes são:

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

As anotações são colocadas na linha anterior (ou na mesma linha) da declaração que modificam. O Godot 4 também introduziu muitas novas variantes de anotação, como @export_range, @export_group e @export_category, que não existiam no Godot 3. Este guia cobre todas elas.

@export básico

A anotação @export expõe uma variável no Inspetor do Godot, permitindo configurar valores sem editar código. O Godot escolhe automaticamente o widget de editor correto com base no tipo da variável.

@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

Dica: Sempre adicione anotações de tipo às variáveis exportadas. Isso garante que o Inspetor mostre o widget correto (por exemplo, um seletor de cores para Color, um slot de recurso para Texture2D).

@export_range — Sliders numéricos

@export_range restringe um valor numérico a um mínimo e um máximo, exibindo um slider no Inspetor. Você também pode especificar um tamanho de passo e hints como "or_greater" ou "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

O hint "or_greater" permite digitar valores acima do máximo, mantendo o intervalo do slider focado. De forma semelhante, "or_less" permite valores abaixo do mínimo.

@export_enum — Menus suspensos

@export_enum cria um menu suspenso no Inspetor. Quando usado com String, o nome da opção selecionada é armazenado. Quando usado com int, você pode atribuir valores explícitos.

# 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 e @export_dir — Caminhos de arquivo/diretório

@export_file mostra um diálogo de arquivo no Inspetor. Você pode filtrar por extensão de arquivo. @export_dir mostra um diálogo de seleção de diretório.

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

A string de filtro usa padrões glob. Vários filtros podem ser separados por vírgulas: "*.png,*.jpg".

@export_multiline e @export_placeholder

@export_multiline fornece uma área de texto grande para strings de múltiplas linhas (ótimo para diálogos ou descrições). @export_placeholder mostra um texto de dica dentro do campo quando ele está vazio.

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

@export_group e @export_subgroup — Organize as propriedades do Inspetor

@export_group cria um cabeçalho de grupo recolhível no Inspetor. Todas as variáveis @export que vêm em seguida pertencem a esse grupo até o próximo grupo ou categoria. @export_subgroup aninha dentro do grupo atual.

@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

Grupos e subgrupos são puramente organizacionais — eles não afetam o acesso às variáveis no código, apenas como as propriedades aparecem no Inspetor.

@export_category — Cabeçalhos de categoria em negrito

@export_category cria um cabeçalho de categoria de nível superior, em negrito, no Inspetor. Diferentemente dos grupos, as categorias não podem ser recolhidas e atuam como um forte separador visual entre conjuntos de propriedades não relacionados.

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

@export com referências de nós

Você pode exportar um NodePath para permitir que designers escolham um nó na árvore de cena. No Godot 4.2+, você pode exportar diretamente uma referência de nó tipada — sem precisar de 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

Exportações de nós tipados são a abordagem recomendada no Godot 4 moderno. O Inspetor mostra um seletor de nós filtrado pelo tipo especificado, e você obtém autocompletar completo no editor de scripts.

@export_flags — Checkboxes de bitmask

@export_flags cria um conjunto de checkboxes em que cada opção corresponde a um bit de um inteiro. O Godot também fornece exportações de flags integradas para camadas de física e de renderização.

# 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 — Inicialização adiada

@onready adia a inicialização da variável até que o nó entre na árvore de cena (equivalente a atribuir em _ready()). Isso é essencial ao referenciar nós filhos com $, porque os filhos não estão disponíveis em tempo de parsing.

# 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

Boa prática: Sempre tipe suas variáveis @onready. Isso habilita o autocompletar e detecta erros de tipo em tempo de parsing, em vez de em tempo de execução.

@tool — Execute scripts no editor

@tool faz um script ser executado dentro do editor do Godot (não apenas em tempo de execução). Isso é poderoso para criar prévias personalizadas, gizmos e propriedades atualizadas em tempo real. Coloque-o no topo do script, antes de 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)

Aviso: Tenha cuidado com scripts @tool. O código em _process() e _physics_process() será executado no editor. Use Engine.is_editor_hint() para proteger a lógica que só deve rodar no jogo.

Outras anotações

@icon

Define um ícone personalizado para o tipo de nó do script no dock de Cena e no diálogo Criar Nó.

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

@warning_ignore

Suprime avisos específicos do GDScript para a próxima instrução. Útil quando você intencionalmente faz shadowing de uma variável ou tem um parâmetro não utilizado.

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

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

@static_unload

Marca um script para que o Godot possa descarregá-lo da memória quando não houver instâncias. Isso pode reduzir o uso de memória para scripts usados apenas temporariamente. O script não pode ter variáveis estáticas ou dados que precisem persistir.

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

Boas práticas de tipagem estática

Embora não sejam anotações, os hints de tipo estático são intimamente relacionados e fortemente recomendados no Godot 4. Eles melhoram o autocompletar, habilitam a verificação de erros em tempo de compilação e podem melhorar o desempenho.

# 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

Observação: Tenha cuidado com := em loops for ao iterar sobre arrays não tipados. Use anotações de tipo explícitas em vez disso: for item: String in array.

Guia rápido de migração: Godot 3 para 4

Referência rápida para converter a sintaxe de export do Godot 3 para as anotações do Godot 4: