TileMap in Godot 4 — Complete Guide Godot 4のTileMap — 完全ガイド

Introduction

はじめに

Godot 4 completely rewrote the TileMap system. If you used TileMap in Godot 3, almost everything has changed — the TileSet editor, how tiles are defined, auto-tiling, layers, and the GDScript API. This guide covers the new architecture from scratch.

Godot 4ではTileMapシステムが完全に書き直されました。Godot 3でTileMapを使っていた場合、ほぼすべてが変更されています — TileSetエディタ、タイルの定義方法、オートタイリング、レイヤー、GDScript APIなど。このガイドでは新しいアーキテクチャをゼロから解説します。

New TileMap Architecture

新しいTileMapアーキテクチャ

The Godot 4 TileMap system has two main components:

Godot 4のTileMapシステムは2つの主要コンポーネントで構成されています：

• TileMap node — The node you add to your scene. It holds one or more layers and references a TileSet resource. TileMapノード — シーンに追加するノード。1つ以上のレイヤーを持ち、TileSetリソースを参照します。
• TileSet resource — Defines the tiles themselves. Contains sources (atlas, scene collection, etc.), physics layers, navigation layers, custom data layers, and terrain sets. TileSetリソース — タイル自体を定義します。ソース（アトラス、シーンコレクションなど）、物理レイヤー、ナビゲーションレイヤー、カスタムデータレイヤー、テレインセットを含みます。

TileSet Sources

TileSetソース

A TileSet can have multiple sources, each identified by a source_id (integer). Source types include:

TileSetは複数のソースを持つことができ、各ソースはsource_id（整数）で識別されます。ソースの種類：

• TileSetAtlasSource — The most common type. A single texture image containing multiple tiles arranged in a grid. TileSetAtlasSource — 最も一般的なタイプ。グリッド状に配置された複数のタイルを含む1枚のテクスチャ画像です。
• TileSetScenesCollectionSource — Each tile is a packed scene, useful for animated or interactive tiles. TileSetScenesCollectionSource — 各タイルがパックドシーンです。アニメーションやインタラクティブなタイルに便利です。

Setting Up a TileSet

TileSetのセットアップ

Step 1: Create the TileSet Resource

ステップ1：TileSetリソースの作成

1. Add a TileMap node to your scene. シーンにTileMapノードを追加します。
2. In the Inspector, click the Tile Set property and select New TileSet. インスペクターでTile Setプロパティをクリックし、New TileSetを選択します。
3. Set the Tile Size (e.g., 16x16 or 32x32). Tile Sizeを設定します（例：16x16 または 32x32）。

Step 2: Add an Atlas Source

ステップ2：アトラスソースの追加

1. Click the TileSet to open the TileSet editor at the bottom panel. TileSetをクリックして、下部パネルのTileSetエディタを開きます。
2. Click the + button and select Atlas. +ボタンをクリックし、Atlasを選択します。
3. Drag your tileset image into the Texture property. タイルセット画像をTextureプロパティにドラッグします。
4. The editor automatically splits it into tiles based on your tile size. You can adjust the texture region and margins. エディタがタイルサイズに基づいて自動的にタイルに分割します。テクスチャ領域やマージンを調整できます。

Step 3: Configure Tile Properties

ステップ3：タイルプロパティの設定

In the TileSet editor, you can add various layer types that apply to all tiles:

TileSetエディタで、すべてのタイルに適用される各種レイヤータイプを追加できます：

• Physics Layers — Collision shapes for tiles Physics Layers — タイルのコリジョンシェイプ
• Navigation Layers — Walkable polygons for pathfinding Navigation Layers — パスファインディング用の歩行可能ポリゴン
• Custom Data Layers — Arbitrary typed data (bool, int, float, String, etc.) Custom Data Layers — 任意の型付きデータ（bool、int、float、Stringなど）
• Terrain Sets — For auto-tiling (the replacement for Godot 3 autotile) Terrain Sets — オートタイリング用（Godot 3のautotileの後継）

TileMap Layers

TileMapレイヤー

A single TileMap node can contain multiple layers. This is a major improvement over Godot 3, where you needed separate TileMap nodes for background and foreground. Each layer can have its own z-index, y-sort, and modulate settings.

1つのTileMapノードで複数のレイヤーを持てるようになりました。Godot 3では背景と前景に別々のTileMapノードが必要でしたが、これは大きな改善です。各レイヤーは独自のz-index、y-sort、モジュレート設定を持てます。

Common layer setup:

一般的なレイヤー構成：

• Layer 0 — Background (ground, floor) — z-index: -1 Layer 0 — 背景（地面、床） — z-index: -1
• Layer 1 — Terrain (walls, obstacles) — z-index: 0 Layer 1 — 地形（壁、障害物） — z-index: 0
• Layer 2 — Foreground (decoration above player) — z-index: 1 Layer 2 — 前景（プレイヤーの上に表示される装飾） — z-index: 1

GDScript API for Layers

レイヤーのGDScript API

# 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")

Terrain System (Auto-Tiling)

テレインシステム（オートタイリング）

The terrain system replaces Godot 3's autotile. It automatically selects the correct tile variant based on neighboring tiles.

テレインシステムはGodot 3のautotileを置き換えるものです。隣接するタイルに基づいて正しいタイルバリアントを自動選択します。

Setting Up Terrains

テレインのセットアップ

1. In TileSet, add a Terrain Set (Inspector → Terrain Sets → Add Element). TileSetでTerrain Setを追加（インスペクター → Terrain Sets → Add Element）。
2. Choose the terrain mode: Match Corners and Sides (47 tiles), Match Corners (16 tiles), or Match Sides (16 tiles). テレインモードを選択：Match Corners and Sides（47タイル）、Match Corners（16タイル）、Match Sides（16タイル）。
3. Add terrain types within the set (e.g., "Grass", "Dirt", "Water"). セット内にテレインタイプを追加（例：「Grass」「Dirt」「Water」）。
4. In the TileSet editor, switch to Select mode, select a tile, and paint the terrain peering bits on each tile. TileSetエディタでSelectモードに切り替え、タイルを選択し、各タイルにテレインピアリングビットをペイントします。

Painting Terrains

テレインのペイント

Once terrains are configured, switch to the TileMap editor and select the Terrains tab. Choose your terrain type and paint directly on the map. Godot will automatically select the correct tile variant.

テレインの設定が完了したら、TileMapエディタに切り替えてTerrainsタブを選択します。テレインタイプを選んでマップ上に直接ペイントすると、Godotが自動的に正しいタイルバリアントを選択します。

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

Physics on Tiles

タイルの物理演算

To add collision to tiles:

タイルにコリジョンを追加するには：

1. Add a Physics Layer in the TileSet Inspector. TileSetインスペクターでPhysics Layerを追加。
2. Configure which collision layer and mask this physics layer uses. この物理レイヤーが使用するコリジョンレイヤーとマスクを設定。
3. In the TileSet editor, switch to the Physics tab and draw collision polygons on each tile. TileSetエディタでPhysicsタブに切り替え、各タイルにコリジョンポリゴンを描画。

Custom Data on Tiles

タイルのカスタムデータ

Custom data layers let you attach typed metadata to any tile. This is extremely useful for gameplay logic.

カスタムデータレイヤーにより、任意のタイルに型付きメタデータを添付できます。ゲームプレイロジックに非常に便利です。

Setting Up Custom Data

カスタムデータのセットアップ

1. In the TileSet Inspector, add a Custom Data Layer. TileSetインスペクターでCustom Data Layerを追加。
2. Name it (e.g., "is_destructible") and set the type (e.g., bool). 名前を設定（例：「is_destructible」）し、型を設定（例：bool）。
3. In the TileSet editor, switch to the Custom Data tab and set values per tile. TileSetエディタでCustom Dataタブに切り替え、タイルごとに値を設定。

Reading Custom Data in 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))

Common custom data examples:

よく使うカスタムデータの例：

• is_destructible: bool
• damage: int
• movement_cost: float
• tile_type: String (e.g., "water", "lava", "ice")
• spawn_chance: float

Procedural Tile Placement

タイルのプロシージャル配置

Placing tiles programmatically is straightforward with the new API:

新しい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()

World-to-Map Coordinate Conversion

ワールド座標とマップ座標の変換

# 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 from Godot 3

Godot 3からの移行

Common Mistakes

よくある間違い

1. Forgetting to create a TileSet first. The TileMap node won't show the tile editor until you assign a TileSet resource. Create one in the Inspector.

   TileSetの作成を忘れる。 TileSetリソースを割り当てるまでTileMapノードはタイルエディタを表示しません。インスペクターで作成してください。

2. Wrong source_id. If you have only one atlas source, its source_id is 0. Adding a second source gives it source_id = 1. Check the TileSet editor bottom panel — each source tab shows its ID.

   source_idの間違い。 アトラスソースが1つだけの場合、source_idは0です。2つ目のソースを追加するとsource_id = 1になります。TileSetエディタの下部パネルで各ソースタブのIDを確認してください。

3. Confusing atlas_coords with tile IDs. In Godot 4, there are no simple tile IDs. Instead, you reference tiles by their position in the atlas grid as Vector2i(column, row).

   atlas_coordsとタイルIDの混同。 Godot 4にはシンプルなタイルIDはありません。代わりに、アトラスグリッド内の位置をVector2i(列, 行)で参照します。

4. Not specifying the layer parameter. Every cell operation requires a layer index as the first argument. Forgetting it causes argument errors.

   レイヤーパラメータの指定忘れ。 すべてのセル操作は第1引数にレイヤーインデックスが必要です。忘れると引数エラーが発生します。

5. Using set_cellv(). This method no longer exists. Use set_cell() with the new signature.

   set_cellv()を使う。 このメソッドはもう存在しません。新しいシグネチャのset_cell()を使用してください。