Autotile no Godot 4: Terrains que Conectam as Bordas Sozinhos

Desenhar cada canto de uma borda de grama à mão é o tipo de trabalho chato que faz a gente largar o projeto. Você pinta o chão, aí precisa do tile de quina superior esquerda, do tile de lado direito, do tile de transição pra água, e quando troca uma célula no meio tudo quebra. O autotile no Godot 4 resolve isso: você diz quais tiles pertencem a um terreno, e a engine escolhe a peça certa pra cada posição automaticamente, conectando as bordas sozinha. Esse tutorial mostra o sistema de Terrains do Godot do começo ao fim, do editor até pintar por código.

A boa notícia é que o sistema é poderoso. A notícia menos boa é que ele foi totalmente reformulado em relação ao Godot 3 e os nomes mudaram, então tutorial antigo confunde mais que ajuda. Vamos pelos termos atuais.

Como o autotile vive no TileSet: Terrain Sets e Terrains

No Godot 4 o autotiling não é um botão mágico no TileMap. Ele mora dentro do recurso TileSet, organizado em duas camadas de configuração:

• Terrain Set: um agrupamento de terrenos que se conectam entre si. Você cria um Terrain Set e escolhe o modo de combinação dele. Esse modo vale pra todos os terrains de dentro.
• Terrain: um terreno individual dentro do set, tipo "grama", "água" ou "parede". É o que você efetivamente pinta no mapa.

O detalhe que confunde todo mundo é o modo do Terrain Set, escolhido na hora de criar:

• Match Corners and Sides: a engine olha o bitmask completo de 3x3 ao redor de cada célula, ou seja, os 4 cantos e os 4 lados. É o que dá o resultado mais bonito, com transições diagonais limpas, mas exige um tileset com muitas variações (o conjunto clássico tem 47 ou 48 tiles).
• Match Corners: olha só os 4 cantos. Pede menos tiles (16 dão conta) e funciona bem em arte estilizada.
• Match Sides: olha só os 4 lados (cima, baixo, esquerda, direita). Bom pra paredes e trilhos onde diagonal não importa.

O que são os "peering bits"

Aqui está o conceito central. Cada tile do seu tileset pode declarar, pra cada lado e canto, se aquela região pertence ao terreno. Esses marcadores são os peering bits (bits de vizinhança). Quando você pinta uma célula com o terrain "grama", a engine pergunta: "quais vizinhos também são grama?" e procura o tile cujos peering bits batem com essa vizinhança. Se o vizinho de cima é grama e os outros não, ela escolhe o tile que tem o peering bit de cima marcado como grama e os de baixo como vazio (a borda inferior da grama).

Ou seja, o peering bit não é o centro do tile, é a costura com o vizinho. Pintar o centro é automático; o que você configura à mão é quais bordas e cantos daquele desenho representam o terreno. Errar isso é a causa número um de borda torta, e vamos voltar nisso no fim.

Passo a passo no editor

Esse tutorial assume Godot 4.3 ou mais novo. Se você ainda não montou um TileSet, vale ler antes como criar um TileSet 2D, porque aqui parto do tileset já com os tiles recortados.

1. Criar o Terrain Set

1. Selecione o nó TileMapLayer na cena e abra o recurso TileSet no inspetor (clicando nele, o painel TileSet aparece embaixo).
2. No painel TileSet, vá na seção Terrain Sets e clique em adicionar (o +).
3. Escolha o Mode. Pra um terreno de grama com transição bonita, use Match Corners and Sides.

2. Definir um Terrain

1. Com o Terrain Set criado, adicione um Terrain dentro dele (de novo, o +, agora na lista de terrains).
2. Dê um nome ("Grama") e uma cor. A cor é só pra você enxergar a máscara enquanto pinta, não aparece no jogo.

3. Pintar os peering bits nos tiles

Essa é a parte que ninguém explica direito. Vá na aba TileSet (não TileMap), selecione a ferramenta Paint e, no dropdown de propriedade, escolha Terrains. Agora:

1. Selecione o terrain "Grama" na lista.
2. Clique no centro de cada tile que é grama pura. Isso marca o tile inteiro como pertencente ao terreno (o "modo" do tile).
3. Para as bordas, pinte os cantos e lados do tile. Cada tile do editor mostra subdivisões: um quadradinho central (o modo) e regiões nas bordas e cantos (os peering bits). Pinte só as regiões que, no desenho daquele tile, mostram grama.

Por exemplo, no tile que é a borda de cima da grama (grama embaixo, vazio em cima), você pinta o lado inferior e os dois cantos de baixo, e deixa o lado de cima e os cantos superiores apagados. A engine vai usar esse tile sempre que uma célula de grama tiver vazio acima dela.

Repita pra cada tile de borda. Sim, dá trabalho na primeira vez. Mas é uma vez por tileset, e depois o mapa inteiro se monta sozinho.

Pintando com o terrain no editor do mapa

Com os peering bits prontos, voltar a pintar o mapa é prazeroso. Selecione o nó TileMapLayer, abra o painel TileMap (a aba ao lado de TileSet) e procure a aba Terrains dentro dele. Lá estão seus terrains listados.

1. Selecione o terrain "Grama".
2. Pinte no mapa normalmente, arrastando o mouse.

A diferença pro modo tile normal é gritante: você não escolhe peça nenhuma, só "passa grama" e a engine resolve cada borda enquanto você arrasta. Apague uma célula no meio de um bloco e os vizinhos se reajustam na hora. É exatamente o comportamento de autotile que você esperava.

Um aviso de versão: no Godot 4.3 cada camada é um node TileMapLayer. Em projetos anteriores ao 4.3, o node se chamava TileMap e guardava as camadas dentro de si, e a aba se comportava de forma parecida mas a API de código era diferente. Os conceitos de Terrains valem nos dois; os nomes de método não.

Se você for empilhar camadas (chão, depois objetos, depois personagem) e quiser que tudo desenhe na ordem certa de profundidade, vale fechar o assunto de camadas depois de dominar o autotile.

Autotiling por código com set_cells_terrain_connect

Pintar à mão é ótimo pra fases feitas por você. Mas e mapa gerado proceduralmente, ou terreno que muda em runtime (uma plantação que cresce, água que invade)? Aí você pinta o terrain por código, e a engine continua resolvendo as bordas pra você.

O método é set_cells_terrain_connect() do TileMapLayer. Ele recebe um array de células, o índice do terrain set e o índice do terrain, pinta todas essas células com aquele terreno e ajusta as bordas levando em conta os vizinhos. O nome diz "connect" justamente porque ele conecta as bordas automaticamente.

Aqui um exemplo curto e tipado. Imagine um script no próprio TileMapLayer que recebe uma lista de células e as preenche de grama:

extends TileMapLayer

const TERRAIN_SET: int = 0
const TERRAIN_GRAMA: int = 0

func pintar_grama(celulas: Array[Vector2i]) -> void:
    set_cells_terrain_connect(celulas, TERRAIN_SET, TERRAIN_GRAMA)

Repare que celulas é tipado como Array[Vector2i], que é exatamente o tipo de coordenada de célula do TileMapLayer. As constantes deixam claro qual terrain set e qual terrain estão em jogo (ambos índice zero se você só tem um de cada).

Um caso mais concreto: gerar um retângulo de grama por código.

extends TileMapLayer

const TERRAIN_SET: int = 0
const TERRAIN_GRAMA: int = 0

func gerar_campo(largura: int, altura: int) -> void:
    var celulas: Array[Vector2i] = []
    for y: int in range(altura):
        for x: int in range(largura):
            celulas.append(Vector2i(x, y))
    set_cells_terrain_connect(celulas, TERRAIN_SET, TERRAIN_GRAMA)

O loop monta o Array[Vector2i] com todas as células do retângulo e uma única chamada pinta o campo inteiro, já com as bordas certas nos quatro cantos. Você não escolheu tile nenhum: passou as coordenadas e o terreno, e o autotile fez o resto.

Vale guardar dois pontos sobre o método:

• Ele resolve as bordas considerando as células que você passou e as que já estavam no mapa. Se há água ao redor, a costura grama/água sai correta desde que os peering bits de água também estejam pintados.
• Se quiser apagar, pinte aquelas células com um terrain "vazio" ou use os métodos de limpeza de célula do TileMapLayer. Passar terrain -1 em algumas versões também limpa o terreno da célula.

Pra entender como esse método se encaixa no fluxo geral do node, o guia de TileMap no Godot 4 cobre o resto da API de células e camadas.

As pegadinhas que vão te morder

O sistema é confiável, mas três coisas viram dor de cabeça com frequência:

Peering bits mal pintados. É a causa de 90% das bordas erradas. Se um tile diz que pertence à grama num canto onde a arte mostra terra, a engine vai escolher esse tile em situações onde ele não combina, e você vê uma quina de grama "vazando" no lugar errado. Quando uma borda sai torta, não mexa no mapa: volte na aba Terrains do TileSet e confira aquele tile específico, comparando o que está pintado com o desenho real, canto por canto.

Ordem de prioridade dos terrains. Quando dois terrains diferentes encostam (grama e água), a engine decide qual desenha a borda com base na ordem deles dentro do Terrain Set e nos peering bits de cada um. Se a transição parece sempre "favorecer" o mesmo lado, ou se a água nunca cria praia na grama, reordene os terrains no painel ou pinte tiles de transição dedicados. Não existe transição mágica entre dois terrains se você não desenhou e marcou os tiles dessa transição.

Modo errado pro tileset que você tem. Escolher Match Corners and Sides com um tileset que só tem 16 variações deixa buracos: a engine procura um tile que não existe e cai num fallback feio. Se sua arte é simples, use Match Corners. Combine o modo do Terrain Set com a quantidade de tiles que você realmente desenhou.

Fechando

O autotile do Godot 4 troca trabalho repetitivo por configuração única. Você investe um tempo pintando os peering bits no TileSet uma vez, e a partir daí tanto o pincel do editor quanto o set_cells_terrain_connect() no código montam bordas perfeitas sem você pensar em quina nenhuma. O segredo está todo na honestidade dos peering bits: marque exatamente o que o desenho mostra, respeite a ordem dos terrains, e o sistema te paga de volta em todo mapa que você fizer.

Se você quer dominar Godot do TileMap ao gameplay completo, sem ficar caçando tutorial solto que mistura versões, vale ver o melhor curso de Godot e seguir um caminho que conecta as peças. CursoGame.Dev existe exatamente pra isso.