TileMap dans Godot 4 — Guide complet

Introduction

Godot 4 a entièrement réécrit le système TileMap. Si tu as utilisé TileMap dans Godot 3, presque tout a changé — l'éditeur de TileSet, la façon dont les tuiles sont définies, l'auto-tiling, les calques et l'API GDScript. Ce guide explique la nouvelle architecture à partir de zéro.

La nouvelle architecture TileMap

Le système TileMap de Godot 4 se compose de deux éléments principaux :

• Nœud TileMap — le nœud que tu ajoutes à ta scène. Il contient un ou plusieurs calques et référence une ressource TileSet.
• Ressource TileSet — définit les tuiles elles-mêmes. Elle contient des sources (atlas, collection de scènes, etc.), des calques de physique, des calques de navigation, des calques de données personnalisées et des ensembles de terrain.

Sources de TileSet

Un TileSet peut avoir plusieurs sources, chacune identifiée par une source_id (entier). Les types de sources incluent :

• TileSetAtlasSource — le type le plus courant. Une seule image de texture contenant plusieurs tuiles disposées en grille.
• TileSetScenesCollectionSource — chaque tuile est une scène empaquetée, utile pour les tuiles animées ou interactives.

Configurer un TileSet

Étape 1 : créer la ressource TileSet

1. Ajoute un nœud TileMap à ta scène.
2. Dans l'inspecteur, clique sur la propriété Tile Set et choisis New TileSet.
3. Définis la Tile Size (par exemple 16x16 ou 32x32).

Étape 2 : ajouter une source d'atlas

1. Clique sur le TileSet pour ouvrir l'éditeur de TileSet dans le panneau du bas.
2. Clique sur le bouton + et choisis Atlas.
3. Glisse ton image de tileset dans la propriété Texture.
4. L'éditeur la découpe automatiquement en tuiles selon ta taille de tuile. Tu peux ajuster la région de texture et les marges.

Étape 3 : configurer les propriétés des tuiles

Dans l'éditeur de TileSet, tu peux ajouter différents types de calques qui s'appliquent à toutes les tuiles :

• Physics Layers — formes de collision pour les tuiles
• Navigation Layers — polygones traversables pour la recherche de chemin
• Custom Data Layers — données typées arbitraires (bool, int, float, String, etc.)
• Terrain Sets — pour l'auto-tiling (le remplaçant de l'autotile de Godot 3)

Calques de TileMap

Un seul nœud TileMap peut contenir plusieurs calques. C'est une grande amélioration par rapport à Godot 3, où tu avais besoin de nœuds TileMap séparés pour l'arrière-plan et le premier plan. Chaque calque peut avoir ses propres réglages de z-index, y-sort et modulate.

Configuration de calques courante :

• Layer 0 — arrière-plan (sol, plancher) — z-index : -1
• Layer 1 — terrain (murs, obstacles) — z-index : 0
• Layer 2 — premier plan (décoration au-dessus du joueur) — z-index : 1

API GDScript pour les calques

# Set a cell on layer 0
tilemap.set_cell(0, Vector2i(5, 3), source_id, atlas_coords)

# Get cell info
var source = tilemap.get_cell_source_id(0, Vector2i(5, 3))
var coords = tilemap.get_cell_atlas_coords(0, Vector2i(5, 3))

# Erase a cell
tilemap.erase_cell(0, Vector2i(5, 3))

# Check if a cell is occupied
if tilemap.get_cell_source_id(0, Vector2i(5, 3)) != -1:
    print("Cell has a tile")

Système de terrain (auto-tiling)

Le système de terrain remplace l'autotile de Godot 3. Il sélectionne automatiquement la bonne variante de tuile en fonction des tuiles voisines.

Configurer les terrains

1. Dans le TileSet, ajoute un Terrain Set (Inspecteur → Terrain Sets → Add Element).
2. Choisis le mode de terrain : Match Corners and Sides (47 tuiles), Match Corners (16 tuiles) ou Match Sides (16 tuiles).
3. Ajoute des types de terrain à l'intérieur de l'ensemble (par exemple « Grass », « Dirt », « Water »).
4. Dans l'éditeur de TileSet, passe en mode Select, choisis une tuile et peins les bits de peering de terrain sur chaque tuile.

Peindre des terrains

Une fois les terrains configurés, passe à l'éditeur de TileMap et sélectionne l'onglet Terrains. Choisis ton type de terrain et peins directement sur la carte. Godot sélectionne automatiquement la bonne variante de tuile.

# Set terrain programmatically
tilemap.set_cells_terrain_connect(0, [Vector2i(5, 3)], 0, 0)
# Parameters: layer, cells array, terrain_set, terrain index

Physique sur les tuiles

Pour ajouter de la collision aux tuiles :

1. Dans l'inspecteur du TileSet, ajoute un Physics Layer.
2. Configure quels calque et masque de collision cette couche de physique utilise.
3. Dans l'éditeur de TileSet, passe à l'onglet Physics et dessine des polygones de collision sur chaque tuile.

Données personnalisées sur les tuiles

Les calques de données personnalisées te permettent d'attacher des métadonnées typées à chaque tuile. C'est extrêmement utile pour la logique de gameplay.

Configurer des données personnalisées

1. Dans l'inspecteur du TileSet, ajoute un Custom Data Layer.
2. Nomme-le (par exemple « is_destructible ») et définis son type (par exemple bool).
3. Dans l'éditeur de TileSet, passe à l'onglet Custom Data et définis des valeurs par tuile.

Lire les données personnalisées dans le code

var tile_data = tilemap.get_cell_tile_data(0, Vector2i(5, 3))
if tile_data:
    var is_destructible = tile_data.get_custom_data("is_destructible")
    var damage = tile_data.get_custom_data("damage")
    if is_destructible:
        destroy_tile(Vector2i(5, 3))

Exemples courants de données personnalisées :

• is_destructible: bool
• damage: int
• movement_cost: float
• tile_type: String (par exemple "water", "lava", "ice")
• spawn_chance: float

Placement procédural de tuiles

Placer des tuiles par programmation est simple avec la nouvelle API :

# Fill a rectangular area
for x in range(20):
    for y in range(10):
        tilemap.set_cell(0, Vector2i(x, y), 0, Vector2i(0, 0))

# Random tile placement
for x in range(50):
    for y in range(50):
        if randf() > 0.7:
            tilemap.set_cell(0, Vector2i(x, y), 0, Vector2i(1, 0))
        else:
            tilemap.set_cell(0, Vector2i(x, y), 0, Vector2i(0, 0))

# Get all used cells on a layer
var used_cells: Array[Vector2i] = tilemap.get_used_cells(0)
print("Layer 0 has ", used_cells.size(), " tiles")

# Clear all tiles on a layer
tilemap.clear_layer(0)

# Clear everything
tilemap.clear()

Conversion des coordonnées monde vers carte

# Convert world position to map coordinates
var map_pos: Vector2i = tilemap.local_to_map(world_position)

# Convert map coordinates to world position (center of tile)
var world_pos: Vector2 = tilemap.map_to_local(Vector2i(5, 3))

# Example: check what tile the player is standing on
var player_tile = tilemap.local_to_map(tilemap.to_local(player.global_position))
var tile_data = tilemap.get_cell_tile_data(0, player_tile)
if tile_data:
    var tile_type = tile_data.get_custom_data("tile_type")
    print("Player is on: ", tile_type)

Migration depuis Godot 3

Erreurs courantes

1. Oublier de créer d'abord un TileSet. Le nœud TileMap n'affiche l'éditeur de tuiles que lorsque tu lui assignes une ressource TileSet. Crées-en une dans l'inspecteur.

2. Mauvaise source_id. Si tu n'as qu'une seule source d'atlas, sa source_id vaut 0. Ajouter une deuxième source lui donne source_id = 1. Vérifie le panneau du bas de l'éditeur de TileSet — chaque onglet de source affiche son ID.

3. Confondre atlas_coords avec des ID de tuile. Dans Godot 4, il n'y a pas d'ID de tuile simples. À la place, tu référencies les tuiles par leur position dans la grille d'atlas sous forme de Vector2i(column, row).

4. Ne pas indiquer le paramètre de calque. Chaque opération sur une cellule nécessite un indice de calque comme premier argument. L'oublier provoque des erreurs d'arguments.

5. Utiliser set_cellv(). Cette méthode n'existe plus. Utilise set_cell() avec la nouvelle signature.