Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

2D 座標系與 2D 變換

前言

這是一份關於 Godot 內建 2D 座標系與 2D 變換的詳細說明。基本概念請參考 Viewport 和畫布變換。

Transform2D 是用來將座標從一個座標系轉換到另一個座標系的矩陣。要有效運用它們，建議先了解 Godot 支援哪些座標系。若想深入理解其底層原理，請參考 矩陣與轉換 教學。

Godot 2D 座標系

下方圖示概述了 Godot 2D 座標系，以及可用的節點變換、變換函式和座標系相關函式。左側為作業系統視窗管理器螢幕，右側為 CanvasItems。為簡化說明，圖中未包含 SubViewport、SubViewportContainer、ParallaxLayer 和 ParallaxBackground，這些也會影響變換。

該圖以如下結構的節點樹為基礎： 根視窗（嵌入視窗） ⇒ 視窗（不嵌入視窗） ⇒ CanvasLayer ⇒ CanvasItem ⇒ CanvasItem ⇒ CanvasItem 。實際應用中可能有更複雜的組合，例如多層嵌套的視窗和子視口，本範例僅做方法論上的概述。

點擊圖示可放大。

• 物件座標

  這是 CanvasItem 的本地座標系。

• 父物件座標

  這是父級 CanvasItem 的本地座標系。當在 Canvas 中擺放 CanvasItems 時，通常會繼承父級 CanvasItem 的變換。例外情況為 CanvasItems.top_level。

• 畫布座標

  如前述 畫布層，Godot 有兩種畫布（Viewport 畫布與 CanvasLayer 畫布），皆有其座標系。這些也稱為世界座標系。一個 Viewport 可包含多個不同座標系的畫布。

• 視口座標

  這是 Viewport 的座標系。

• 相機座標

  這僅供內部如 3D 相機射線投影等功能使用。

• 嵌入器座標／螢幕座標

  場景樹中的每個 Viewport*（*Window 或 SubViewport）都會嵌入於其他節點，或作業系統的視窗管理器中。此座標系的原點為 Window 或 SubViewport 的左上角，比例則與其嵌入對象或作業系統視窗管理器一致。

  若嵌入對象為作業系統視窗管理器，則稱為螢幕座標。

• 絕對嵌入器座標／絕對螢幕座標

  此座標系的原點是嵌入節點或作業系統視窗管理器畫面的左上角，比例與嵌入器或作業系統視窗管理器相同。

  若嵌入對象為作業系統視窗管理器，則稱為絕對螢幕座標。

節點變換

上述每個節點皆有一個或多個變換，這些節點組合起來便構成不同座標系間的變換。除了少數例外，這些變換均為 Transform2D，下方列表說明各自細節與影響。

• CanvasItem 變換

  CanvasItem 可以是 Control 節點或 Node2D 節點。

  對於 Control 節點，變換包含相對於父節點原點的 position，以及以 pivot point 為中心的 scale 與 rotation。

  對於 Node2D 節點，transform 包含 position、rotation、scale 以及 skew。

  這個變換會影響自身，通常也會連帶影響子 CanvasItem；若為 SubViewportContainer，則會影響其所包含的 SubViewport。

• CanvasLayer 變換

  CanvasLayer 的 transform 會影響該層內所有 CanvasItem，但不會影響同一 Viewport 內的其他 CanvasLayer 或 Window。

• CanvasLayer 跟隨視口變換

  跟隨視口變換 是一種自動計算的變換，依據 Viewport 的 canvas transform 及 CanvasLayer 的 follow viewport scale 而定。若啟用 follow viewport enabled，可用來實現類 3D 效果。其影響對象與 CanvasLayer 變換 相同。

• Viewport 畫布變換

  canvas transform 會影響 Viewport 預設畫布內的所有 CanvasItem，也會影響啟用跟隨視口變換的 CanvasLayer。Viewport 內活動的 Camera2D 會調整這個變換。但不影響該 Viewport 下嵌入的 Window。

• Viewport 全域畫布變換

  Viewport 也有 global canvas transform，這是主變換，會影響所有子 CanvasLayer 及嵌入的 Window 變換。此功能主要用於 Godot 編輯器的 CanvasItem 編輯工具。

• Viewport 拉伸變換

  最後, Viewport 有 拉伸變換, 當視口調整大小或拉伸時會套用這個變換。此變換用於 Window (詳見 多重解析度) , 也可透過 size 或 size_2d_override 手動設定於 SubViewport。其 translation 、 rotation 、 skew 為預設值, 僅 scale 可設為非預設值。

• Window 變換

  為了按照 多重解析度 的描述縮放與定位 Window 內容，每個 Window 都有一個 window transform。例如，這就是讓 Window 兩側出現黑邊，確保 Viewport 以固定寬高比顯示的原因。

• Window 位置

  每個 Window 也有 position，用來描述其在嵌入器（例如另一個 Viewport 或作業系統視窗管理器）內的位置。

• SubViewportContainer 縮放變換

  stretch 搭配 stretch_shrink，用以設定 SubViewportContainer 內的 SubViewport 是否要根據容器大小縮放，以及縮放的整數比例因數。