Dictionary na Godot 4: Organizar Dados por Chave em GDScript

Você já sabe criar variáveis e já mexeu com Array. Só que Array tem um limite claro: os itens são acessados por posição, um número que vai de 0 pra cima. Isso é ótimo pra uma fila de inimigos, mas vira um pesadelo quando você quer guardar os stats de um personagem. Qual índice era a vida? O 0? E a mana, era o 2 ou o 3? É aí que entra o Dictionary. Um dicionário em GDScript guarda dados por chave, um nome que você escolhe, então você acessa stats["vida"] em vez de decorar posições. Nesse post eu mostro como criar, ler, iterar e manter um Dictionary na Godot 4, com casos reais de jogo.

A ideia é a mesma de um dicionário de verdade: você procura pela palavra (a chave) e encontra a definição (o valor). Num Array você pergunta "o que tem na posição 2?". Num Dictionary você pergunta "o que tem na chave vida?". A chave costuma ser um texto, mas pode ser número ou outros tipos. O valor pode ser qualquer coisa: um número, um texto, um Array, ou até outro Dictionary.

O que é um Dictionary e quando usar em vez de Array

Um Dictionary é uma coleção de pares chave/valor. Cada chave é única dentro do dicionário e aponta pra um valor. A grande diferença pro Array é que você não depende de ordem nem de índice numérico: você busca o dado pelo nome que fizer sentido pro seu jogo.

A regra prática pra escolher entre os dois:

• Se você tem uma lista de coisas do mesmo tipo e a ordem importa (inimigos na tela, itens de um menu, waypoints de um caminho), use Array.
• Se você tem dados nomeados que descrevem uma coisa (vida, mana, nome, nível de um personagem), use Dictionary.

Repara que os dois se complementam. É comum ter um Array de Dictionaries: uma lista de inimigos, onde cada inimigo é um Dictionary com nome, vida e dano.

Como criar um Dictionary em GDScript

Em GDScript você declara um Dictionary com chaves {}. Sempre tipe a variável, como você já faz com o resto do código:

# Dictionary vazio, pronto pra receber dados depois
var inventario: Dictionary = {}

# Dictionary já com valores iniciais
var stats: Dictionary = {
    "vida": 100,
    "mana": 50,
    "nome": "Heroi",
    "nivel": 1
}

Aqui vem um ponto que precisa de honestidade: a variável é tipada como Dictionary, mas os valores dentro dela não têm tipo estático garantido. O Dictionary é heterogêneo por natureza. No exemplo acima, "vida" guarda um int, "nome" guarda uma String, e nada impede você de misturar tudo. Isso é poderoso, mas cobra um cuidado na hora de ler, que eu mostro daqui a pouco.

Acessar e alterar valores

Pra ler ou escrever um valor, use a chave entre colchetes, igual a um índice de Array, só que com o nome no lugar do número:

var stats: Dictionary = {"vida": 100, "mana": 50}

# Ler
print(stats["vida"])  # 100

# Alterar
stats["vida"] = 80

# Criar uma chave nova: basta atribuir
stats["escudo"] = 25

Cuidado com o acesso direto por colchetes: se a chave não existir, o Godot dá erro em tempo de execução. print(stats["forca"]) quebra se "forca" nunca foi definida. Por isso existem formas mais seguras de ler, que é o próximo tópico.

Ler com segurança: has() e get() com valor padrão

Antes de acessar uma chave que talvez não exista, cheque com has():

if stats.has("escudo"):
    print("Tem escudo:", stats["escudo"])
else:
    print("Sem escudo")

Mas o jeito mais limpo, e o que resolve o problema do tipo heterogêneo, é get() com valor padrão. Você pede a chave e diz o que quer receber caso ela não exista:

# Se "vida" existir, devolve o valor. Se não, devolve 0.
var vida: int = stats.get("vida", 0)

# Funciona pra qualquer tipo: aqui o padrão é uma String
var nome: String = stats.get("nome", "Sem nome")

Esse padrão é o que deixa seu código robusto. Como os valores do Dictionary não têm tipo garantido, ao ler você declara uma variável tipada e usa get() com um padrão do tipo certo. Assim, se a chave sumir num save antigo ou num dado que veio de fora, o jogo não quebra: ele cai no valor padrão. É a diferença entre um crash e um comportamento previsível.