godot-tilemap-mastery

TileMap で絶対にしてはいけないこと

• バッチ処理せずに巨大なループ内で set_cell() を呼び出さないでください — 地形接続、パターン、またはチャンクバッチ処理を使用してください。
• set_cell で source_id を忘れないでください — オーバーロードの誤りにより、クラッシュまたは何も起きない場合があります。
• ワールド座標とタイル座標を混在させないでください — 必ず local_to_map / map_to_local を使用してください。
• 地形がある場合、有機的な形状を手作業で塗らないでください — 地形セットと set_cells_terrain_connect を使用してください。
• 動的なアクターを TileMap に配置しないでください — 敵やピックアップはノードです。タイルはジオメトリ／破壊可能なセルに使用します。
• 物理フレームごとに get_cell_tile_data() を頻繁に呼び出さないでください — メタデータをキャッシュしてください（fast_metadata_cache.gd）。

---

判断ツリー：セルの書き込み方法

目的	推奨方法	スクリプト	トレードオフ
有機的な地面／道路／川	地形オートタイル	terrain_autotile.gd / terrain_path_painter.gd	TileSet のセットアップコストがかかりますが、デザイナーによる反復作業は最速です
プレハブの部屋／家／スタンプ	TileMapPattern	tile_pattern_stamper.gd	プロシージャル生成のパーツに最適ですが、セルごとの柔軟性は低くなります
まばらな／正確な編集	set_cell	—	少数のセルには適していますが、フレームごとに数千セルを処理するには不向きです
大規模なストリーミングワールド	チャンク	tilemap_chunking.gd / procedural_chunk_batcher.gd / tilemap_data_manager.gd	間接参照とロード境界が発生します
破壊可能な採掘／破壊	カスタムデータの HP	destructible_tile_logic.gd	編集後にナビゲーション／物理を更新する必要があります
ゲームプレイの問い合わせ（摩擦／危険）	カスタムデータ＋キャッシュ	gameplay_data_query.gd / fast_metadata_cache.gd	set_cell 時にキャッシュを無効化する必要があります
編集後のナビゲーション	ランタイムのナビゲーション修正	nav_mesh_teleport_fix.gd	セルごとに行うとコストがかかるため、まとめて再構築してください
一方向／物理レイヤー	TileSet の物理	physics_shape_interaction.gd	CharacterBody のマスクに合わせてください
アイソメトリック／複数階層のソート	Y ソートレイヤー	sorting_Z_layering.gd	親ノードとすべてのレイヤーで y_sort が必要です
旧式 TileMap → レイヤー	移行	tilemap_layer_v43_upgrade.gd	一度限りのアップグレード支援です

エディターでのアトラス／物理の塗り方の設定：Reference の公式ドキュメントを参照してください。このスキル本文から手順 1～3 や flood_fill のチュートリアルを再読み込みしないでください。

利用可能なスクリプト（一覧と必須の使用条件）

タスク	必須スクリプト
シリアライズ／大規模ワールドデータ	tilemap_data_manager.gd
ランタイムの地形パス	terrain_path_painter.gd / terrain_autotile.gd
破壊可能なタイル	destructible_tile_logic.gd
カスタムデータのゲームプレイ時読み取り	gameplay_data_query.gd（頻繁に使う場合は fast_metadata_cache.gd も使用）
プロシージャルな一括配置	procedural_chunk_batcher.gd
チャンクのストリーミング読み込み／解放	tilemap_chunking.gd
プレハブのパターンスタンプ	tile_pattern_stamper.gd
編集後のナビゲーション修復	nav_mesh_teleport_fix.gd
一方向／物理レイヤー操作	physics_shape_interaction.gd
Y ソート／Z レイヤー	sorting_Z_layering.gd
4.3 以降の複数レイヤーへのアップグレード	tilemap_layer_v43_upgrade.gd

エキスパート向けのトレードオフ（ルーティングのみ）

• アイソメトリックの Y ソート： 親と各 TileMapLayer で y_sort_enabled を有効にし、高さのあるタイルでは y_sort_origin を調整します — sorting_Z_layering.gd を参照してください。
• プロシージャル生成： パターンをスタンプするか、地形を一括処理します。セルごとの set_cell の大量呼び出しは避けてください — tile_pattern_stamper.gd / procedural_chunk_batcher.gd。
• 差分／セーブデータの差分： レイヤー間で get_used_cells() の source_id／atlas を比較し、可能であればマップ全体ではなく tilemap_data_manager.gd で差分を保存します。

詳細レシピ（必要に応じて）

LLM の知識不足に関するルール：一般的なエージェントが読む前には知らない内容は、ここまたは scripts/ に記載します — 削除せず、移動のみ行ってください。

トピック	参照
TileSet エディターの手順	tileset-editor-setup.md
ランタイム API ＋フラッド／地形	runtime-tile-patterns.md
アイソメトリック／パターン／差分	expert-tilemap-architectures.md

リファレンス

段階的開示：特定の API を調査する場合にのみ公式ドキュメントへのリンクを開き、関連スキルは同じ領域の別スキルへルーティングする場合に読み込みます — 全体を事前に読み込まないでください。

公式ドキュメント

• TileMap の使用 — TileMapLayer のワークフロー、レイヤー、ランタイムでの set_cell／地形のペイント、旧式の TileMap を 1 つ使うより複数のレイヤーが適するケース。
• TileSet の使用 — TileSet エディターでペイントするアトラスソース、地形、物理／ナビゲーション／カスタムデータレイヤー。
• TileMapLayer — セル API、地形の接続、パターン、座標変換、ランタイムのタイルデータ更新。
• TileSet — このリソースを参照するすべての TileMapLayer で共有される物理／地形／カスタムデータレイヤーの定義。
• TileSetAtlasSource — アトラスのグリッド、代替タイル、衝突とメタデータを制御するタイルごとの TileData。
• TileData — カスタムデータ、物理ポリゴン、ナビゲーションポリゴン、クエリ時に使用される y_sort_origin。
• TileMapPattern — セルごとの set_cell ループを使わずに、複数タイルのプレハブをキャプチャ／スタンプします。
• 衝突形状（2D） — TileSet の物理レイヤーが CharacterBody2D に公開する形状の選択肢と一方向衝突のパターン。
• ナビゲーション入門（2D） — 編集後にタイルのナビゲーションポリゴンが NavigationRegion2D／NavigationAgent2D に反映される仕組み。
• キャンバスレイヤー — 地面、装飾、屋根の TileMapLayer を分けるための z-index／CanvasLayer。
• バックグラウンド読み込み — チャンクの TileSet／タイルマップシーンを、処理落ちを発生させずにストリーミングするためのスレッド化された ResourceLoader のパターン。

関連スキル

前提条件

• godot-project-foundations — TileSet アトラスやマルチレイヤーのレベルシーンを作成する前に、シーンツリー、リソース、インポートレイアウトを確認します。
• godot-gdscript-mastery — ランタイムのタイルマネージャーで使用される、型付き Vector2i API、キャッシュパターン、シグナルアップ/コールダウン構造を扱います。
• godot-2d-physics — TileMapLayer の物理レイヤーが関与するコリジョンレイヤー/マスクと、StaticBody2D 相当の挙動について扱います。

補完

• godot-version-migration — tilemap_layer_v43_upgrade と TileMap→TileMapLayer は 4.x への移行パス上にあります。レイヤースクリプトを適用する前に、移行ハブを通してエンジンのアップグレードを実行してください。
• godot-characterbody-2d — タイルコライダーに対する move_and_slide、一方通行プラットフォーム、TileMapLayer ジオメトリ上での床/壁クエリについて扱います。
• godot-navigation-pathfinding — 破壊可能またはプロシージャルなタイルによって歩行可能ポリゴンが変化する際の NavigationAgent2D / リージョン更新について扱います。
• godot-camera-systems — プレイヤー周辺のチャンクロード/アンロードを駆動する Camera2D の制限と追従半径について扱います。
• godot-adapt-3d-to-2d — TILE_SHAPE_ISOMETRIC やマルチフロア TileMapLayer と組み合わせる、アイソメトリック / Y ソートの奥行きテクニックについて扱います。
• godot-scene-management — 大規模なタイルワールドを孤立したレイヤーなしでストリーミングするための、チャンクシーンのパッキングと切り替えについて扱います。
• godot-performance-optimization — set_cell / カスタムデータクエリがフレーム時間を支配する場合の、バッチ処理、キャッシュ予算、プロファイラーチェックについて扱います。

ダウンストリーム / コンシューマー

• godot-procedural-generation — テレイン接続、パターン、チャンクバッチャーを介してセルを書き込むノイズ/BSP/WFC ジェネレーターです。
• godot-genre-platformer — TileSet 物理、一方通行、ハザードのカスタムデータから構築される精密プラットフォーマーのレベルです。
• godot-genre-metroidvania — TileMapLayer チャンク上に重ねられる、相互接続された部屋グリッド、アビリティゲート、マップの開示です。
• godot-genre-sandbox — TileMapLayer を編集可能なテレインバックエンドとして扱う、掘削/建築可能な 2D ワールドです。
• godot-monte-carlo-balancer — マップを出荷する前に、タイルのカスタムデータにエンコードされたハザード密度、破壊可能 HP、移動コストをシミュレートします。

マスター

• godot-master — クロススキルの発見のための、ライブラリルーターおよびミラーリングされたモジュールエントリです。