Guia de Migração Godot 4

Visão Geral

Um guia crítico para desenvolvedores que estão migrando do Godot 3.x para o Godot 4. Esta habilidade foca nas principais mudanças de sintaxe no GDScript 2.0, no novo sistema Tween e nas atualizações de anotações export.

Quando Usar Esta Habilidade

• Use ao portar um projeto Godot 3 para Godot 4.
• Use ao encontrar erros de sintaxe após a atualização.
• Use ao substituir nós depreciados (como nó Tween vs create_tween).
• Use ao atualizar variáveis export para anotações @export.

Procedimento de Migração

Trabalhe em um branch ou cópia de backup. Escolha uma versão exata do Godot 4, valide a conversão antes de alterar arquivos e inspecione lacunas do conversor, nós renomeados, shaders, física, plugins e alvos de exportação. Teste cenas e jogos salvos antes de substituir a build funcional do Godot 3. Exemplos abaixo são fragmentos em um script de Nó apropriado; Enemy deve ser um tipo de projeto declarado.

Guia oficial: Atualizando para Godot 4.

Principais Mudanças

1. Anotações (@)

O Godot 4 usa @ para palavras-chave que modificam o comportamento.

• export var x -> @export var x
• onready var y -> @onready var y
• tool -> @tool (no topo do arquivo)

2. Setters e Getters

As propriedades agora definem setters/getters inline.

Godot 3:

var health setget set_health, get_health

func set_health(value):
    health = value

Godot 4:

signal health_changed(health: int)

var health: int = 100:
    set(value):
        health = value
        emit_signal("health_changed", health)
    get:
        return health

3. Sistema Tween

O nó Tween do Godot 3 foi removido no Godot 4. Use create_tween() no código.

Godot 3:

$Tween.interpolate_property(...)
$Tween.start()

Godot 4:

var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2(100, 100), 1.0)
tween.parallel().tween_property($Sprite, "modulate:a", 0.0, 1.0)

4. Conexões de Sinal

Conexões baseadas em strings são desencorajadas. Use chamáveis (callables).

Godot 3:

connect("pressed", self, "_on_pressed")

Godot 4:

pressed.connect(_on_pressed)

Exemplos

Exemplo 1: Arrays Tipados

O GDScript 2.0 suporta arrays tipados para verificação de tipo; meça o desempenho em vez de assumir um ganho de velocidade.

# Godot 3
var enemies = []

# Godot 4
var enemies: Array[Node] = []

func _ready():
    for child in get_children():
        if child is Enemy:
            enemies.append(child)

Exemplo 2: Aguardando Sinais (Corrotinas)

yield é substituído por await.

Godot 3:

yield(get_tree().create_timer(1.0), "timeout")

Godot 4:

await get_tree().create_timer(1.0).timeout

Melhores Práticas

• ✅ Faça: Use @export_range, @export_file, etc., para uma melhor UI do inspetor.
• ✅ Faça: Digite todas as variáveis (var x: int) para ganhos de desempenho no GDScript 2.0.
• ✅ Faça: Use super() para chamar métodos pai em vez de .function_name().
• ❌ Não Faça: Use nomes de strings para sinais (emit_signal("name")) se puder usar o objeto de sinal (name.emit()).

Solução de Problemas

Problema: "Identificador 'Tween' não é um tipo válido." Solução: O Godot 4 usa um objeto Tween retornado por create_tween(), não um nó de cena ou um tipo SceneTreeTween. Use var tween: Tween = create_tween() em um contexto de Nó.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como um substituto para validação específica do ambiente, testes ou revisão especializada.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.