godot-tilemap

Godot TileMap（4.7 TileMapLayer）

TileMapLayer と TileSet を使ってタイルベースのレベルを作成し、タイルごとの衝突とカスタムデータを追加して、地形を使ったオートタイルを設定し、実行時にセルを操作します。対象は Godot 4.7 です。このバージョンでは、非推奨となった TileMap ノードの代わりに TileMapLayer を使用します。

使用する場面

• タイルグリッドから 2D レベルを設計する場合、TileSet（衝突、ナビゲーション、カスタムデータ、地形）を設定する場合、またはコードからタイルを読み書きする場合に使用します。
• TileMap ノード（1 つのノードに複数のレイヤー）を、複数の TileMapLayer ノード（各ノードに 1 つのレイヤー）へ移行する場合に使用します。

使用しない場面： タイル上でプレイヤーを移動させる場合 → godot-2d-movement、一般的な物理ボディやレイキャストの場合 → godot-physics、プロシージャルなマップの 生成 アルゴリズムの場合 → procedural-gen、レベル 設計 の実践の場合 → level-design。

基本的なワークフロー

1. TileMapLayer ノードを追加します（背景、壁、前景など、視覚的または論理的なレイヤーごとに 1 つ）。各ノードにはタイルのレイヤーが 1 つだけ含まれます。
2. レイヤーの tile_set プロパティに TileSet を作成または割り当てます。 TileSet エディターでアトラスソース（タイルに分割されたテクスチャ）を追加します。複数のレイヤーやレベルで再利用できるように、TileSet は外部 .tres ファイルとして保存します。
3. TileSet エディターでタイルデータを追加します。 物理レイヤー（衝突ポリゴン）、ナビゲーションレイヤー、オクルージョン、カスタムデータレイヤー（damage や is_ladder など、タイルごとに型を指定した値）を追加します。
4. TileMap の下部パネルで ペイントします（Paint／Line／Rectangle／Bucket）。自動接続するタイルでは、地形セットを定義し、Connect／Path モードでペイントします。
5. レイヤーの collision_enabled／navigation_enabled プロパティで、レイヤーごとの衝突／ナビゲーションを有効にします。
6. local_to_map、set_cell、get_cell_source_id、get_cell_tile_data(...).get_custom_data(...) を使って、コードから読み書きします。

パターン

1. マウス位置をセルに変換してカスタムデータを読み取る

extends TileMapLayer

func _unhandled_input(event: InputEvent) -> void:
    if event is InputEventMouseButton and event.pressed:
        # local_to_map expects local coords; convert from global first.
        var cell := local_to_map(to_local(event.position))
        var data := get_cell_tile_data(cell)   # TileData or null
        if data:
            var dmg: int = data.get_custom_data("damage")  # custom data layer
            print("Cell %s deals %d damage" % [cell, dmg])

2. 実行時にタイルを配置・消去する

# set_cell(coords, source_id, atlas_coords, alternative_tile = 0)
func place_wall(cell: Vector2i) -> void:
    set_cell(cell, 0, Vector2i(2, 1))   # source 0, atlas tile at column 2, row 1

func dig(cell: Vector2i) -> void:
    erase_cell(cell)                    # same as set_cell(cell, -1)

func clear_level() -> void:
    clear()                             # remove every tile on this layer

3. 地形セットを使って領域をオートタイルする

# Paint a filled area with terrain `terrain` of terrain set `terrain_set`;
# Godot picks the correct edge/corner tiles to connect them.
func fill_with_grass(cells: Array[Vector2i]) -> void:
    var terrain_set := 0
    var grass_terrain := 0
    set_cells_terrain_connect(cells, terrain_set, grass_terrain, true)

4. 配置済みのタイルを反復処理する（例：スポーンタイルをすべて探す）

func find_spawns() -> Array[Vector2i]:
    var spawns: Array[Vector2i] = []
    for cell in get_used_cells():
        var data := get_cell_tile_data(cell)
        if data and data.get_custom_data("is_spawn"):
            spawns.append(cell)
    return spawns

注意点

• TileMap ノードは 4.3 で非推奨になりました。 TileMapLayer ノード（ノードごとに 1 レイヤー）を使用し、親の Node2D の下にまとめてください。layer 引数を取る従来の TileMap 呼び出し（set_cell(layer, ...)）は TileMapLayer には適用されません。
• local_to_map にはローカル座標が必要です。 マウス位置やグローバル位置は、先に to_local(...) で変換してください。変換しないとセルの位置がずれます。
• get_cell_tile_data は空のセルやアトラス以外のソースに対して null を返します。 get_custom_data を呼び出す前に必ず null チェックを行ってください。
• カスタムデータには型があります。 int として宣言されたレイヤーは int を返します。間違った型として読み取ったり、存在しないレイヤー名を参照したりするとエラーになります。先に TileSet でレイヤーを定義してください。
• 地形では、すべての組み合わせを定義する必要があります。 TileSet の地形ビットマスクの隣接設定が不完全だと、set_cells_terrain_connect の結果がおかしくなります。
• 実行時の編集はフレーム終了時までまとめて処理されます。 set_cell の直後に更新された内部状態を読み取る必要がある場合は、update_internals() を呼び出してください（処理コストが高いため、ループ内での使用は避けてください）。
• 衝突が機能しない場合は？ レイヤーの collision_enabled が有効か、タイルにポリゴンを持つ物理レイヤーがあるか、TileSet の物理レイヤーマスクがボディに一致しているかを確認してください。

参考資料

• TileSet の設定（アトラスソース、物理／ナビゲーション／カスタムデータレイヤー、地形ビットマスク）、シーンタイル、Y ソート、実行時のタイルデータの上書き（_use_tile_data_runtime_update）については、references/tileset-and-terrains.md を参照してください。

関連スキル

• godot-2d-movement — これらのタイル上を歩くキャラクター。
• godot-physics — タイルの衝突が関与する衝突レイヤー／マスク。
• procedural-gen — ノイズ／RNG からのタイルマップ生成。
• level-design / roguelike — レベル設計の実践とグリッドベースのジャンル。