Folha de Consulta GDScript
Última atualização
Básico e saída
Um script estende um tipo de nó, e o Godot chama as funções dele para você.
| Operação | Sintaxe |
|---|---|
| Vincular o script a um tipo de nó | extends Node |
| Código que roda quando o nó inicia | func _ready() -> void:
print("Hello, World!") |
| Imprimir valores sem separador | print("HP: ", hp) |
| Imprimir valores separados por espaços | prints("a", "b", 3) |
| Comentário | # This is a comment |
| Comentário de documentação | ## Shown in the editor's help |
| String de várias linhas | var text := """Line one
Line two""" |
| Reportar um erro | push_error("Health is negative") |
| Reportar um aviso | push_warning("Old save file") |
Variáveis, constantes e tipos
Os tipos são opcionais. Use-os para ter verificações no editor, autocompletar e código mais rápido.
| Operação | Sintaxe |
|---|---|
| Variável (tipo dinâmico) | var score = 0 |
| Variável com tipo estático | var speed: float = 200.0 |
| Inferir o tipo estático | var lives := 3 |
| Constante | const MAX_HP = 100 |
| Enum | enum State { IDLE, RUN, JUMP } |
| Usar um valor de enum | var state: State = State.IDLE |
| Valores de vetor e de cor | var pos := Vector2(10, 20)
var tint := Color(1, 0, 0) |
| Referência de objeto vazia | var target: Node = null |
| Converter para texto, int ou float | str(42), int("42"), float("3.5") |
| Float para int (descarta as casas decimais) | int(3.9) # 3 |
| Verificar um tipo | value is int, node is Sprite2D |
| Converter para um tipo (cast) | var sprite := node as Sprite2D |
Operadores
A matemática de sempre, mais palavras em inglês para a lógica.
| Operação | Sintaxe |
|---|---|
| Somar, subtrair, multiplicar, dividir | a + b, a - b, a * b, a / b |
| Divisão inteira (int / int) | 7 / 2 # 3 |
| Resto | 7 % 3, fmod(7.5, 2.0) |
| Potência | 2 ** 10 # 1024 |
| Atribuição composta | x += 1, x -= 1, x *= 2, x /= 2 |
| Comparação | ==, !=, <, >, <=, >= |
| Lógica | a and b, a or b, not a |
| Lógica (com símbolos) | a && b, a || b, !a |
| If em linha | var label := "win" if score > 10 else "lose" |
| Está em uma coleção | "sword" in inventory |
| Bit a bit | a & b, a | b, a ^ b, ~a, a << 1, a >> 1 |
Controle de fluxo
Os blocos são definidos pela indentação, como no Python. O Godot indenta com tabs por padrão.
| Operação | Sintaxe |
|---|---|
| If, elif, else | if hp <= 0:
die()
elif hp < 20:
print("Low HP")
else:
print("OK") |
| If em uma linha | if hp <= 0: die() |
| Percorrer um intervalo | for i in range(5):
print(i) # 0 to 4 |
| Intervalo com início, fim e passo | for i in range(10, 0, -2):
print(i) # 10, 8, 6, 4, 2 |
| Repetir n vezes | for i in 3:
print(i) # 0, 1, 2 |
| Percorrer um array | for item in items:
print(item) |
| Variável de loop com tipo (Godot 4.2+) | for n: String in names:
print(n.to_upper()) |
| Loop while | while hp > 0:
hp -= 10 |
| Sair do loop ou pular uma iteração | break, continue |
| Marcador de bloco vazio | pass |
Correspondência de padrões (match)
match executa o primeiro ramo cujo padrão se encaixa. Não existe fallthrough.
| Operação | Sintaxe |
|---|---|
| Comparar valores | match state:
State.IDLE:
print("idle")
State.RUN:
print("run") |
| Vários valores em um ramo | match key:
"w", "up":
move_up() |
| Ramo padrão (curinga) | match n:
0:
print("zero")
_:
print("other") |
| Atribuir o valor a um nome | match cmd:
"quit":
get_tree().quit()
var other:
print("Unknown: ", other) |
| Padrão de array | match pos:
[0, 0]:
print("origin")
[var x, 0]:
print("on the x axis at ", x) |
| Array com qualquer final | match args:
["move", ..]:
print("move command") |
| Padrão de dicionário | match item:
{"type": "coin", "value": var v}:
gold += v |
| Condição com when (Godot 4.4+) | match score:
var s when s >= 90:
print("A")
var s when s >= 75:
print("B")
_:
print("C") |
Funções e lambdas
Funções também são valores: guarde, passe adiante e vincule argumentos a elas.
| Operação | Sintaxe |
|---|---|
| Parâmetros e retorno com tipo | func add(a: int, b: int) -> int:
return a + b |
| Sem valor de retorno | func reset() -> void:
score = 0 |
| Argumento padrão | func greet(who := "player") -> void:
print("Hi, ", who) |
| Função estática | static func double(x: int) -> int:
return x * 2 |
| Lambda de uma linha | var square := func(x): return x * x |
| Chamar um Callable | square.call(4) # 16 |
| Função como valor | var on_done := reset
on_done.call() |
| Vincular argumentos | var add_ten := add.bind(10)
print(add_ten.call(5)) # 15 |
| Lambda de várias linhas | var greet_all := func(names: Array) -> void:
for n in names:
print("Hi, ", n) |
| Esperar um timer | await get_tree().create_timer(1.0).timeout |
| Esperar uma corrotina | var data = await fetch_data() |
Strings
Os métodos de string retornam uma nova string e nunca alteram a original.
| Operação | Sintaxe |
|---|---|
| Formatar com % | "%s has %d HP" % [name, hp] |
| Duas casas decimais | "%.2f" % 3.14159 # "3.14" |
| Formatar com marcadores nomeados | "{a} vs {b}".format({"a": 1, "b": 2}) |
| Concatenar com + | "Score: " + str(score) |
| Tamanho | text.length() |
| Maiúsculas ou minúsculas | text.to_upper(), text.to_lower() |
| Dividir em partes | "a,b,c".split(",") # ["a", "b", "c"] |
| Juntar partes | ", ".join(["a", "b", "c"]) |
| Remover espaços em branco | " hi ".strip_edges() # "hi" |
| Substituir texto | text.replace("cat", "dog") |
| Encontrar uma posição | text.find("lo") # -1 if missing |
| Começa ou termina com | text.begins_with("Hi"), text.ends_with("!") |
| Substring | text.substr(0, 5) |
| Contém | "ell" in "Hello" # true |
Arrays
Arrays crescem e diminuem. Um array tipado só aceita o seu tipo de elemento.
| Operação | Sintaxe |
|---|---|
| Literal de array (tipos misturados) | var items = [1, "two", 3.0] |
| Array tipado | var scores: Array[int] = [10, 20, 30] |
| Ler por índice (negativos contam a partir do fim) | scores[0], scores[-1] |
| Adicionar ao final | scores.append(40), scores.push_back(40) |
| Inserir em um índice | scores.insert(0, 5) |
| Remover e retornar o último | var last = scores.pop_back() |
| Remover por valor ou por índice | scores.erase(20), scores.remove_at(0) |
| Contém, índice de | scores.has(30), scores.find(30) |
| Tamanho, verificar se está vazio | scores.size(), scores.is_empty() |
| Ordenar | scores.sort() |
| Ordenar com a sua própria regra | enemies.sort_custom(func(a, b): return a.hp < b.hp) |
| Map | scores.map(func(x): return x * 2) |
| Filter | scores.filter(func(x): return x > 15) |
| Reduce | scores.reduce(func(acc, x): return acc + x, 0) |
| Fatia (fim não incluído) | scores.slice(1, 3) |
Dicionários
Pares de chave e valor. As chaves podem ser de qualquer tipo; strings são as mais comuns.
| Operação | Sintaxe |
|---|---|
| Literal de dicionário | var stats = {"hp": 100, "mp": 30} |
| Dicionário tipado (Godot 4.4+) | var prices: Dictionary[String, int] = {"sword": 50} |
| Ler ou gravar uma chave | stats["hp"], stats["xp"] = 50 |
| Ler com um valor padrão | stats.get("luck", 0) |
| Tem uma chave | stats.has("hp"), "hp" in stats |
| Remover uma chave | stats.erase("mp") |
| Chaves e valores | stats.keys(), stats.values() |
| Número de entradas | stats.size() |
| Mesclar outro dicionário (true sobrescreve) | stats.merge({"luck": 5}), stats.merge(bonus, true) |
| Percorrer as chaves | for key in stats:
print(key, " = ", stats[key]) |
Classes e anotações
Todo script é uma classe. As anotações começam com @.
| Operação | Sintaxe |
|---|---|
| Dar um nome global à classe | class_name Player
extends CharacterBody2D |
| Construtor | func _init(start_hp := 100) -> void:
hp = start_hp |
| Criar uma instância | var p := Player.new() |
| Classe interna | class Item:
var name := ""
var price := 0 |
| Chamar a versão do pai deste método | func _ready() -> void:
super()
print("child ready") |
| Chamar outro método do pai | super.take_damage(10) |
| Variável estática (Godot 4.1+) | static var count := 0 |
| Mostrar no Inspetor | @export var speed := 300.0 |
| Mostrar com um intervalo de slider | @export_range(0, 100) var volume := 50 |
| Pegar um nó filho quando estiver pronto | @onready var sprite: Sprite2D = $Sprite2D |
| Setter e getter | var hp := 100:
set(value):
hp = clampi(value, 0, 100)
get:
return hp |
| Rodar o script no editor | @tool |
Sinais
Sinais são de primeira classe: declare-os e depois emita, conecte e aguarde diretamente.
| Operação | Sintaxe |
|---|---|
| Declarar um sinal | signal died |
| Sinal com argumentos tipados | signal health_changed(old_hp: int, new_hp: int) |
| Emitir | died.emit() |
| Emitir com argumentos | health_changed.emit(100, 80) |
| Conectar a um método | player.died.connect(_on_player_died) |
| Conectar uma lambda | button.pressed.connect(func(): print("Clicked")) |
| Passar argumentos extras | button.pressed.connect(_on_pressed.bind("start")) |
| Disparar só uma vez | timer.timeout.connect(_on_timeout, CONNECT_ONE_SHOT) |
| Desconectar | player.died.disconnect(_on_player_died) |
| Verificar uma conexão | player.died.is_connected(_on_player_died) |
| Esperar um sinal | await player.died |
Nós e ciclo de vida
Os callbacks que o Godot chama no seu nó e as chamadas que você faz na árvore de cena.
| Operação | Sintaxe |
|---|---|
| Objeto criado (antes da árvore) | func _init() -> void:
print("created") |
| O nó e seus filhos estão prontos | func _ready() -> void:
print("ready") |
| A cada frame | func _process(delta: float) -> void:
position.x += 100.0 * delta |
| A cada tick de física | func _physics_process(delta: float) -> void:
velocity.y += 980.0 * delta
move_and_slide() |
| Input que a interface não usou | func _unhandled_input(event: InputEvent) -> void:
if event.is_action_pressed("jump"):
jump() |
| Pegar um nó pelo caminho | get_node("Sprite2D"), $Sprite2D |
| Caminho com espaços, nome único | $"UI/Health Bar", %HealthBar |
| Verificar uma ação de input | Input.is_action_pressed("move_right") |
| Criar uma instância de uma cena | var enemy := preload("res://enemy.tscn").instantiate()
add_child(enemy) |
| Excluir um nó com segurança | queue_free() |
| Pai e filhos | get_parent(), get_children() |
| Trocar de cena | get_tree().change_scene_to_file("res://main.tscn") |
A sintaxe de GDScript que você usa enquanto cria um jogo no Godot, em uma única página. Esta folha de consulta GDScript é uma referência rápida para o Godot 4: variáveis e tipos estáticos, operadores, controle de fluxo e match, funções e lambdas, strings, arrays e dicionários, classes, sinais e os callbacks de nó que o Godot executa a cada frame.
Tudo aqui é sintaxe do Godot 4, então você vai ver @export, @onready, died.emit() e await em vez das formas do Godot 3. Copie o que precisar para o seu script ou teste os trechos da linguagem ao vivo no playground de GDScript: coloque-os dentro de _ready() e rode no navegador, sem instalar o Godot.
Perguntas frequentes sobre a folha de consulta GDScript
Esta folha de consulta GDScript é gratuita?
Sim. Esta folha de consulta GDScript é totalmente gratuita, sem necessidade de cadastro. Salve nos favoritos e volte sempre que precisar da sintaxe exata de um sinal, de um padrão de match ou de um método de array.
Esta folha de consulta é para Godot 4 ou Godot 3?
Godot 4. As duas versões mudam em pontos que quebram código copiado: o Godot 4 usa as anotações
@export e @onready em vez das palavras-chave export e onready, died.emit() e died.connect(callable) em vez de emit_signal("died") e do connect baseado em strings, await em vez de yield, e super() em vez de .method(). As linhas marcadas com 4.1+, 4.2+ ou 4.4+ exigem pelo menos essa versão do Godot.Qual é a diferença entre = e := em GDScript?
var x = 5 cria uma variável dinâmica que depois pode guardar qualquer tipo. var x := 5 infere o tipo a partir do valor (aqui int) e o fixa, então atribuir uma string depois gera erro. var x: int = 5 declara o tipo explicitamente. Tipos estáticos trazem erros no editor, autocompletar melhor e código mais rápido.Como funcionam os sinais em GDScript?
Declare um sinal com
signal died, envie com died.emit() e reaja a ele a partir de outro nó com player.died.connect(_on_player_died). Você pode conectar uma lambda em vez de um método, vincular argumentos extras com .bind() ou pausar uma função até o sinal disparar com await player.died.GDScript é parecido com Python?
Na aparência, sim: os blocos são definidos pela indentação e ele usa
for ... in, if/elif/else e palavras em inglês como and, or e not. Mas GDScript é uma linguagem própria, feita para o Godot. Tem tipos estáticos opcionais, sinais, anotações como @export e acesso direto aos nós com $.Posso praticar GDScript online?
Sim. Abra o playground de GDScript para rodar os trechos desta folha de consulta no navegador: o playground vincula o seu script a um nó, então o código dentro de
_ready() roda uma vez. Quando quiser algo mais estruturado, o curso interativo gratuito de GDScript da Coddy leva você passo a passo das variáveis e funções até as classes e os sinais.Recursos relacionados
Mais folhas de consulta
