Variaveis e Tipos no GDScript para Iniciantes

Se voce esta comecando a programar jogos, a primeira peca que precisa dominar sao as variaveis no GDScript. Toda mecanica, da barra de vida ao placar, depende de guardar valores em algum lugar e ler esses valores depois. Antes de aprender condicionais, loops ou fisica, vale parar aqui e entender bem o que e uma variavel, como declarar com tipos e por que tipar ajuda tanto quem esta descobrindo como programar jogos. Neste texto eu uso o GDScript, a linguagem da Godot 4, sempre com os tipos declarados, e amarro cada exemplo a uma cena de jogo de verdade.

Nada de teoria solta. Toda variavel que aparece aqui guarda algo concreto: a vida do player, a pontuacao da fase, a velocidade do personagem, o nome de quem esta jogando. Quando voce liga o conceito ao que acontece na tela, ele para de ser abstrato e vira ferramenta.

O que e uma variavel no jogo

Uma variavel e um nome que guarda um valor. Pense nela como uma caixinha com etiqueta: a etiqueta e o nome, e dentro fica o valor que voce quer lembrar. No jogo, a variavel guarda tudo que muda ou que precisa ser consultado depois: a vida do player, quantas moedas ele tem, se a porta esta aberta, onde o inimigo esta.

Em GDScript voce cria uma variavel com a palavra var, da um nome a ela e coloca um valor inicial. O mais importante para iniciantes e pegar o habito de declarar o tipo junto, ou seja, dizer que tipo de valor aquela caixinha aceita.

var vida: int = 100
var pontuacao: int = 0
var nome_jogador: String = "Heroi"
var velocidade: float = 250.0
var vivo: bool = true

Leia com calma. var vida: int = 100 cria uma variavel chamada vida, do tipo int, comecando em 100. Sempre que o player tomar dano, voce muda esse valor. Sempre que a tela precisar mostrar a vida, voce le esse valor. A variavel e a memoria do seu jogo.

Os tipos basicos: int, float, bool, String e Vector2

Cada valor de um jogo tem uma natureza, e o tipo diz qual e. Conhecer os cinco tipos mais comuns ja cobre a maior parte do que voce vai escrever no comeco.

O int guarda numero inteiro, sem casa decimal. Serve para tudo que voce conta em unidades: vida, municao, moedas, pontuacao, numero de vidas.

var municao: int = 30
var moedas: int = 0
var vidas: int = 3

O float guarda numero com casa decimal. Serve para grandezas continuas, onde a fracao importa: velocidade, tempo, dano com multiplicador, gravidade. Repare no ponto decimal, mesmo quando o valor e redondo escrevemos 250.0 para deixar claro que e float.

var velocidade: float = 250.0
var gravidade: float = 980.0
var tempo_recarga: float = 1.5

O bool guarda apenas verdadeiro ou falso, o famoso liga e desliga. Toda pergunta de sim ou nao do jogo vira um bool: o player esta vivo? o pulo esta disponivel? a fase ja foi concluida?

var vivo: bool = true
var pode_pular: bool = true
var fase_concluida: bool = false

O String guarda texto: nome do jogador, linha de dialogo, mensagem na tela.

var nome_jogador: String = "Aventureiro"
var dialogo: String = "Bem-vindo a vila"

Por fim, o Vector2, que guarda dois numeros de uma vez, um x e um y. Ele aparece o tempo todo em jogo 2D porque posicao, velocidade e direcao vivem em duas dimensoes. Um so Vector2 guarda o par inteiro.

var posicao: Vector2 = Vector2(320.0, 180.0)
var direcao: Vector2 = Vector2(1.0, 0.0)

Se a ideia de trabalhar com x e y ainda esta nebulosa, vale um mergulho depois em matematica para jogos e vetores, porque quase todo movimento do seu jogo vai passar por ali. Por enquanto, basta saber que o Vector2 e um par de numeros que a gente trata como um so.

Por que tipar ajuda quem esta aprendendo

Talvez voce esteja pensando: se o GDScript aceita variavel sem tipo, por que dar esse trabalho? A resposta e que o tipo trabalha a seu favor de tres formas, e todas contam muito no comeco.

Primeiro, a Godot passa a pegar seus erros antes de rodar o jogo. Se voce declarou var vida: int e por engano tenta guardar um texto ali, o editor reclama na hora, antes de voce apertar play. Sem o tipo, esse erro so apareceria no meio do jogo, num momento dificil de rastrear. Pegar o erro cedo economiza horas de caca a bug.

Segundo, o codigo fica mais rapido. Quando a Godot sabe de antemao que velocidade e sempre um float, ela executa aquele trecho de forma mais direta. Para um jogo que roda dezenas de vezes por segundo, isso soma.

Terceiro, e talvez o mais util pra quem esta aprendendo, o tipo documenta o codigo. Quando voce le var alcance: float = 120.0, ja sabe na hora que ali vive um numero decimal, sem precisar procurar onde a variavel foi usada. O tipo funciona como um bilhete colado na caixinha dizendo o que ela carrega. Semanas depois, quando voce voltar ao proprio codigo, vai agradecer.

Esse habito de declarar tipos anda de maos dadas com o resto dos fundamentos. Se voce ainda nao viu como variaveis conversam com decisoes e repeticoes, vale a pena firmar a base de logica de programacao para jogos antes de seguir, porque variavel sem logica em volta e so uma caixinha parada.

Constantes com const: o que nunca muda

Nem todo valor do jogo muda. A velocidade maxima do carro, o dano base de uma espada, o numero de fases: sao valores que voce define uma vez e nunca mais mexe durante a partida. Para esses casos existe o const, de constante.

Uma constante se declara igual a uma variavel, com tipo, mas usando const no lugar de var. A diferenca e que, depois de definida, ela nao pode ser alterada. Se voce tentar mudar, a Godot acusa erro.

const VELOCIDADE_MAXIMA: float = 400.0
const DANO_BASE: int = 10
const TOTAL_FASES: int = 8

Por convencao, nomes de constantes vem em MAIUSCULAS, para bater o olho e saber que aquilo e fixo. Usar const no que e fixo tem duas vantagens. Voce se protege de alterar o valor por engano em outro trecho do codigo, e deixa clara a intencao pra quem le: isso aqui e uma regra do jogo, nao um estado que varia. Um erro comum de iniciante e criar tudo como var e depois se perder sobre o que pode ou nao mudar. Reserve const para as regras e var para o estado.

Variaveis de export: ajustar valores no Inspetor

Existe um tipo especial de variavel que merece um paragrafo, porque poupa muito tempo de teste: a variavel exportada, marcada com @export. Ao colocar @export na frente de uma variavel, ela aparece no Inspetor da Godot, o painel lateral do editor. Ai voce ajusta o valor arrastando ou digitando na interface, sem abrir o codigo.

extends CharacterBody2D

@export var velocidade: float = 250.0
@export var vida_maxima: int = 100

Na pratica, isso e ouro pra balancear o jogo. Voce quer testar se o inimigo fica bom com velocidade 180 ou 220? Em vez de editar o script toda vez, seleciona o node na cena e muda o numero no Inspetor, com o jogo quase rodando ao lado. O mesmo node pode ter valores diferentes em cenas diferentes, porque cada instancia guarda o proprio ajuste. Guarde o @export para os numeros que voce vai querer afinar bastante: vida, velocidade, dano, tempo de recarga.

Erros comuns de iniciante com variaveis

Alguns tropecos aparecem sempre no comeco. Conhecer eles de antemao poupa frustacao.

O primeiro e misturar int e float sem perceber. Se voce divide dois int, o resultado pode nao ser o que espera em algumas contas. Quando o valor pede fracao, como velocidade ou tempo, use float desde o inicio, com o .0 no numero.

O segundo e usar uma variavel antes de dar valor a ela, ou fora do lugar onde ela existe. Uma variavel declarada dentro de uma funcao so vive dentro daquela funcao. Se voce precisa que a vida seja lida por varias funcoes do mesmo script, declare ela no topo, fora das funcoes, como fizemos nos primeiros exemplos.

O terceiro e escolher nomes ruins. Uma variavel chamada x2 ou temp nao diz nada. Nomes como vida, velocidade, nome_jogador explicam sozinhos o que guardam. No GDScript o padrao e usar letras minusculas com underline separando palavras, o chamado snake_case.

O quarto e confundir atribuir com comparar quando as variaveis entram numa decisao. Guardar valor usa um sinal de igual (vida = 100), comparar valores usa dois (if vida == 0). Trocar um pelo outro e fonte de metade dos bugs iniciais, e o assunto aparece com forca quando voce chega nas condicionais no GDScript, o proximo passo natural depois das variaveis.

Juntando tudo num trecho de jogo

Veja como esses conceitos vivem juntos num unico script. Um personagem simples com vida, velocidade exportada, uma constante de dano e um estado de vivo ou morto:

extends CharacterBody2D

const DANO_QUEDA: int = 20

@export var velocidade: float = 250.0
@export var vida_maxima: int = 100

var vida: int = 100
var nome_jogador: String = "Heroi"
var vivo: bool = true

func receber_dano(dano: int) -> void:
    vida -= dano
    if vida <= 0:
        vida = 0
        vivo = false

func curar(pontos: int) -> void:
    vida += pontos
    if vida > vida_maxima:
        vida = vida_maxima

Repare no papel de cada peca. DANO_QUEDA e uma regra fixa, entao virou const. velocidade e vida_maxima sao valores que voce quer ajustar no Inspetor, entao ganharam @export. vida, nome_jogador e vivo sao o estado que muda durante a partida, entao sao var comuns declaradas no topo, visiveis por todas as funcoes. Cada funcao tem seus parametros tipados e devolve void porque so executa uma acao, sem entregar valor de volta.

Uma duvida comum de quem comeca na Godot e se deve escrever em GDScript ou C#. As ideias de variavel, tipo e constante existem nas duas, mas a sintaxe muda. Se voce estiver nesse dilema, vale ler a comparacao entre C# e GDScript no Godot antes de investir tempo. Para aprender os fundamentos, porem, GDScript e o caminho mais curto: menos cerimonia e feedback rapido dentro do editor.

Por onde seguir

Variaveis no GDScript sao a base de tudo que vem depois. Guardar o estado com o tipo certo, separar o que muda (var) do que e fixo (const), expor no Inspetor o que voce quer ajustar (@export) e nomear cada caixinha de forma clara: esse conjunto de habitos ja te coloca a frente de muita gente que so copia codigo de tutorial sem entender.

O proximo passo e simples de dizer e trabalhoso de fazer: abra a Godot e crie variaveis de verdade. Faca um personagem com vida, exiba a vida na tela, tire pontos quando ele encostar num espinho, some pontos quando pegar uma moeda. Cada pequeno teste fixa um tipo diferente na sua cabeca. A fluencia com variaveis nao entra pela leitura, entra pela mao, escrevendo, errando e vendo o valor mudar na tela.