사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
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
TileMapnode (one node, many layers) toTileMapLayernodes.
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
- One `TileMapLayer` per layer (background, walls, foreground), grouped under a
Node2D. All layers share one TileSet saved as an external .tres.
- 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.
- 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).
- Place tiles from code with
set_cell,set_cells_terrain_connector
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.
- Turn on per-layer collision/navigation with
collision_enabled/
navigation_enabled on each TileMapLayer.
- Check before you finish.
- Run the
godot-nodes-scenesskill'sscripts/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
# 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
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
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 04. Headless test: a placed wall has collision and data
# 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
TileMapLayerper 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_connectplaces 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_enabledon 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.mdwhen 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-movementfor characters that walk on these tiles.godot-physicsfor the collision layers/masks tile collisions take part in.procedural-genfor generating the cell layout.create-game-assetsfor drawing the tile sheet.level-design/roguelikefor design practice and grid-based genres.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
TileMaphas been deprecated in favor ofTileMapLayersince 4.3.TileMapLayer.tile_map_datais stored as aPackedByteArrayin 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.