gamedev-skills/awesome-gamedev-agent-skills

godot-tilemap

Godot 4.7 tile maps with TileMapLayer and TileSet: atlas sources, data layers, terrain autotiling and setcell or localtomap at runtime.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-tilemap

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Godot TileMap (4.7 TileMapLayer)

Author tile levels with TileMapLayer + TileSet, attach per-tile collision and data, autotile with terrains, and edit cells at runtime. Targets Godot 4.7, where TileMapLayer replaces the deprecated TileMap node (see Version notes).

When to use

  • 2D levels on a tile grid, configuring a TileSet (collision, navigation, custom data,

terrains), or reading/writing tiles from code.

  • Migrating a TileMap node (one node, many layers) to TileMapLayer nodes.

When not to use:* moving the player across tiles → godot-2d-movement; general bodies and raycasts → godot-physics; generation algorithms → procedural-gen; level design practice → level-design; 3D grids → godot-3d-essentials (GridMap).

Core workflow

  1. One `TileMapLayer` per layer (background, walls, foreground), grouped under a

Node2D. All layers share one TileSet saved as an external .tres.

  1. Build the TileSet. The TileSet editor is click-only, so when you cannot drive the

editor, generate the .tres with a headless tool script (Pattern 1) and keep that script in the repo. Otherwise, ask the user to make the change in the editor and report the source id, atlas coordinates and layer names.

  1. Add data layers on the TileSet: physics layers (collision polygons plus their

collision layer/mask bits), navigation layers, occlusion, and typed custom data layers (damage: int, is_ladder: bool).

  1. Place tiles from code with set_cell, set_cells_terrain_connect or

set_cells_terrain_path. The cells in a .tscn are an encoded tile_map_data byte array, so never edit them by hand; write a generator script or ask the user to paint in the editor.

  1. Turn on per-layer collision/navigation with collision_enabled /

navigation_enabled on each TileMapLayer.

  1. Check before you finish.
  • Run the godot-nodes-scenes skill's scripts/check_godot_project.py <project-dir>

to catch a TileSet .tres whose texture or script path is broken.

  • Prove the tiles behave with a headless test (Pattern 4): on a fresh checkout run

godot --headless --path . --import first so the tile texture is imported, then godot --headless --path . --script res://tests/test_tiles.gd, and read the exit code. With no Godot binary (godot, godot4 or $GODOT_BIN), ask the user to run it and paste the output. For a visual check, ask the user to run godot --path . --debug-collisions and report whether walls show shapes.

Patterns

1. Generate a TileSet .tres in code

gdscript
# res://tools/make_tileset.gd
# Run: godot --headless --path . --script res://tools/make_tileset.gd
extends SceneTree

func _initialize() -> void:
    var tile_set := TileSet.new()
    tile_set.tile_size = Vector2i(16, 16)
    tile_set.add_physics_layer()
    tile_set.set_physics_layer_collision_layer(0, 1 << 1)   # bit 2 ("walls")
    tile_set.add_custom_data_layer()
    tile_set.set_custom_data_layer_name(0, "damage")
    tile_set.set_custom_data_layer_type(0, TYPE_INT)

    var atlas := TileSetAtlasSource.new()
    atlas.texture = load("res://art/tiles.png")
    atlas.texture_region_size = Vector2i(16, 16)
    tile_set.add_source(atlas, 0)                  # add before creating tiles
    atlas.create_tile(Vector2i(2, 1))              # column 2, row 1 of the texture
    var wall := atlas.get_tile_data(Vector2i(2, 1), 0)
    wall.add_collision_polygon(0)
    wall.set_collision_polygon_points(0, 0, PackedVector2Array([
        Vector2(-8, -8), Vector2(8, -8), Vector2(8, 8), Vector2(-8, 8)]))  # cell-centred
    wall.set_custom_data("damage", 0)

    var err := ResourceSaver.save(tile_set, "res://tiles/world_tileset.tres")
    print("saved tileset: ", error_string(err))
    quit(0 if err == OK else 1)

Add the source to the TileSet before create_tile, so the tile's data knows the TileSet's physics and custom data layers. Polygon points are relative to the cell centre.

2. Mouse position to a cell, then read custom data

gdscript
extends TileMapLayer

func _unhandled_input(event: InputEvent) -> void:
    if event is InputEventMouseButton and event.pressed:
        # event.position is in viewport pixels and ignores Camera2D scroll/zoom.
        var local_event := make_input_local(event) as InputEventMouseButton
        var cell := local_to_map(local_event.position)
        var data := get_cell_tile_data(cell)       # TileData or null
        if data:
            var dmg: int = data.get_custom_data("damage")
            print("Cell %s deals %d damage" % [cell, dmg])

3. Place, erase and autotile at runtime

gdscript
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 fill_with_grass(cells: Array[Vector2i]) -> void:
    set_cells_terrain_connect(cells, 0, 0, true)   # terrain set 0, terrain 0

4. Headless test: a placed wall has collision and data

gdscript
# res://tests/test_tiles.gd
extends SceneTree

func _initialize() -> void:
    var layer := TileMapLayer.new()
    layer.tile_set = load("res://tiles/world_tileset.tres")
    root.add_child(layer)
    layer.set_cell(Vector2i(0, 0), 0, Vector2i(2, 1))
    var data := layer.get_cell_tile_data(Vector2i(0, 0))
    var failed := 0
    if data == null:
        failed += 1
        push_error("wall tile missing: wrong source id or atlas coords?")
    elif data.get_collision_polygons_count(0) == 0:
        failed += 1
        push_error("wall tile has no collision polygon on physics layer 0")
    print("Results: %d failed" % failed)
    quit(1 if failed > 0 else 0)

Gotchas

  • `TileMap` node is deprecated since 4.3. Use one TileMapLayer per layer. Old calls

with a leading layer argument (set_cell(layer, ...)) do not apply to TileMapLayer.

  • `local_to_map` needs layer-local coordinates. Convert a world position with

to_local(...) first. A mouse event's position is in viewport pixels, so it breaks as soon as a Camera2D scrolls or zooms; use make_input_local(event) or get_local_mouse_position().

  • `get_cell_tile_data` returns `null` for empty cells and non-atlas sources; check

before get_custom_data.

  • Custom data is typed and named. Reading a layer name that doesn't exist errors;

define the layer on the TileSet first.

  • "Cannot create tile. The tile is outside the texture..." → the atlas has no texture

yet, the coordinates fall outside it, or a tile already covers that space. Set texture and texture_region_size before create_tile.

  • Terrains need every combination defined. set_cells_terrain_connect places odd or

placeholder tiles when the TileSet's peering bits are incomplete.

  • Runtime edits are batched to the end of the frame. Call update_internals() only if

you must read updated internals immediately (expensive in loops).

  • Collision not working? Check collision_enabled on the layer, that the tile has a

polygon on a physics layer, and that the physics layer's bits match your bodies' masks.

References

  • Read references/tileset-and-terrains.md when you need atlas vs scene-collection

sources, the per-tile data layer types, terrain set modes and painting, coordinate helpers, Y-sorting, runtime tile-data overrides, or the TileMap-to-TileMapLayer migration steps.

Related skills

  • godot-2d-movement for characters that walk on these tiles.
  • godot-physics for the collision layers/masks tile collisions take part in.
  • procedural-gen for generating the cell layout.
  • create-game-assets for drawing the tile sheet.
  • level-design / roguelike for design practice and grid-based genres.

Version notes

Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).

  • TileMap has been deprecated in favor of TileMapLayer since 4.3.
  • TileMapLayer.tile_map_data is stored as a PackedByteArray in scenes.

Sources: TileMapLayer @ 4.7.2-stable, TileSet @ 4.7.2-stable, TileSetAtlasSource @ 4.7.2-stable, tile_map_layer.cpp @ 4.7.2-stable, Using TileMaps.

同じリポジトリから

関連する Skills

すべての Skills
gamedev-skills
コミュニティ

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

24時間の導入数
433
GitHub Stars
1万
更新日
11月12日
gamedev-skills
コミュニティ

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

24時間の導入数
431
GitHub Stars
1万
更新日
11月12日
gamedev-skills
コミュニティ

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

24時間の導入数
365
GitHub Stars
1万
更新日
11月12日
gamedev-skills
コミュニティ

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

24時間の導入数
360
GitHub Stars
1万
更新日
11月12日