Godot4 タイルマップが用いるセル座標とローカル座標とグローバル座標の関係

無料・軽快な 2D / 3D 用のゲームエンジン Godot Engine 4 で、タイルマップを実現する TileMapLayer の各タイルを指定するセルの座標と、Node2D で用いられるローカル座標とグローバル座標の関係と、その変換に便利な関数について紹介します。
セル座標に変換する関数の注意点についても紹介します。

※ GodotEngine 4.3 を使用しています。.NET 版ではありません。
※スクリプトは自己責任でご使用ください。

タイルマップのセル座標とローカル座標とグローバル座標

Node2D 派生のクラスには２次元を扱うローカル座標とグローバル座標があります。
グローバル座標は、シーンで一意の位置を表します。
ローカル座標は、そのノード自体が中心である原点（0, 0) を表します。

階層的には

• グローバル座標（シーンの座標）
  • ローカル座標（TileMapLayer オブジェクト内の座標）
    • セルの座標（TileMapLayer オブジェクト内のローカル座標をマスで分割）

と、表せます。

タイルマップでは、TileMapLayer クラスの内部に持つ格子状に並んだセルを、タイルの縦横の幅をひとつの単位にしてセルの座標も指定できます。

上図では、TileMapLayer ノードのグローバル座標を初期値の (0, 0) から (-16, 32) に移動しています。
マスに書かれている (1, 0) などはセルの座標で、 TileMapLayer ノードのローカル座標 (0, 0) = グローバル座標 (-16, 32) を起点にします。

座標はすべて、右・下方向がプラスで、左・上方向がマイナスです。

グローバル座標とローカル座標の変換関数

Node2D の to_global, to_local メンバ関数でグローバル座標とローカル座標を相互変換できます。
ノードのグローバル座標は global_position メンバ変数で確認・設定できます。

グローカル座標をローバル座標に変換する Node2D のメンバ関数は以下です。

Vector2 to_global(local_point: Vector2) const

Transforms the provided local position into a position in global coordinate space. The input is expected to be local relative to the Node2D it is called on. e.g. Applying this method to the positions of child nodes will correctly transform their positions into the global coordinate space, but applying it to a node’s own position will give an incorrect result, as it will incorporate the node’s own transformation into its global position.

指定されたローカル位置をグローバル座標空間内の位置に変換します。入力は、呼び出される Node2D に対してローカルであることが期待されます。例えばこのメソッドを子ノードの位置に適用すると、子ノードの位置がグローバル座標空間に正しく変換されますが、このメソッドをノード自体の位置に適用すると、ノード自体の変換がグローバル位置に組み込まれるため、不正確な結果が得られます。

Node2D — Godot Engine (4.x)の日本語のドキュメント #to-global と Google 翻訳

グローバル座標をローカル座標に変換する Node2D のメンバ関数は以下です。

Vector2 to_local(global_point: Vector2) const 

Transforms the provided global position into a position in local coordinate space. The output will be local relative to the Node2D it is called on. e.g. It is appropriate for determining the positions of child nodes, but it is not appropriate for determining its own position relative to its parent.

指定されたグローバル位置をローカル座標空間の位置に変換します。出力は、呼び出される Node2D に対してローカルになります。例えばこれは子ノードの位置を決定するのには適していますが、親に対する相対的な自身の位置を決定するのには適していません。

Node2D — Godot Engine (4.x)の日本語のドキュメント #to-local と Google 翻訳

使用例

先ほどの図にあった TileMapLayer ノードのグローバル座標を global_position メンバ変数で確認して、それを to_local 関数でローカル座標に変換した結果と、to_global 関数でグローバル座標に再び変換した結果を確認します。

テストのコードは以下です。

func _ready():
	print("$TileMapLayer.global_position = ", $TileMapLayer.global_position)
	var local_pos = $TileMapLayer.to_local($TileMapLayer.global_position)
	print("local_pos = ", local_pos)
	var global_pos = $TileMapLayer.to_global(local_pos)
	print("global_pos = ", global_pos)

下パネルの出力に表示された結果は以下です。
グローバル座標とローカル座標が正しく変換されています。

$TileMapLayer.global_position = (-16, 32)
local_pos = (0, 0)
global_pos = (-16, 32)

ローカル座標とセル座標の変換関数

TileMapLayer の local_to_map 、 map_to_local 関数を使うことで、 TileMapLayer ノードのローカル座標とセルの座標を相互変換できます。
この変換処理は、TileMapLayer に設定されたタイルセットのタイルのサイズによる変換です。

TileMapLayer のローカル座標をセルの座標に変換するメンバ関数は以下です。
local_position の値が、タイルのサイズで割り切れない場合は、小数切り捨てで整数に変換されます。

小数切り上げについては、自作関数を作成して検証した次回の記事を参照してください。

Vector2i local_to_map(local_position: Vector2) const 🔗

Returns the map coordinates of the cell containing the given local_position. If local_position is in global coordinates, consider using Node2D.to_local before passing it to this method. See also map_to_local.

指定された local_position を含むセルの地図座標を返します。 local_position がグローバル座標にある場合は、このメソッドに渡す前に Node2D.to_local を使用することを検討してください。 「map_to_local」もご覧ください。

TileMapLayer — Godot Engine (4.x)の日本語のドキュメント local-to-map

セルの座標を TileMapLayer のローカル座標に変換するメンバ関数は以下です。

Vector2 map_to_local(map_position: Vector2i) const 

Returns the centered position of a cell in the TileMapLayer‘s local coordinate space. To convert the returned value into global coordinates, use Node2D.to_global. See also local_to_map.

TileMapLayer のローカル座標空間内のセルの中心位置を返します。返された値をグローバル座標に変換するには、Node2D.to_global を使用します。 「local_to_map」もご覧ください。

Note: This may not correspond to the visual position of the tile, i.e. it ignores the TileData.texture_origin property of individual tiles.

TileMapLayer — Godot Engine (4.x)の日本語のドキュメント #map-to-local と Google 翻訳

筆者が勘違いした点

map_to_local 関数は、セルの座標をローカル座標に変換します。
なぜか、セルの左上のローカル座標を得られると勘違いしていて、タイルサイズが 16 × 16 ならば 0, 16, 32 と 16 の倍数で得られると思っていました。
しかし実際は、セルの座標 (1, 0) とローカル座標に変換すると (24, 8) が得られました。

先ほどの引用に書いてある通り、 map_to_local 関数はセルの左上ではなくセルの中心のローカル座標を返します。
(1, 0) のセルの座標をローカル座標に変換した場合、 (16 * 1 + 8, 16 * 0 + 8) = (24, 8) が得られます。

まとめ

今回は、無料・軽快な 2D / 3D 用のゲームエンジン Godot Engine 4 で、タイルマップを実現する TileMapLayer の各タイルを指定するセルの座標と、Node2D で用いられるローカル座標とグローバル座標の関係と、その変換に便利な関数について紹介しました。
セル座標に変換する関数の注意点についても紹介しました。

参照サイト Thank You!

• Godot Engine – Free and open source 2D and 3D game engine
• Using TileSets — Godot Engine (4.x)の日本語のドキュメント
• TileMapLayer — Godot Engine (4.x)の日本語のドキュメント
• Node2D — Godot Engine (4.x)の日本語のドキュメント

記事一覧 → Compota-Soft-Press