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 中的自訂繪圖

前言

Godot 內建了用於繪製精靈、Polygon、多邊形、粒子、文字等各種常見遊戲開發場景的節點。不過，如果你需要做一些標準節點無法覆蓋的特殊需求，可以讓任何 2D 節點（例如 Control 或 Node2D 衍生節點）用自訂繪圖指令直接在畫面上繪製。

2D 節點中的自訂繪製*非常*有用。下面是一些用例：

• 繪製現有節點型別無法完成的形狀或邏輯，例如帶有軌跡或特殊動態多邊形的圖像。

• 繪製大量簡單物件，例如 2D 遊戲用的格線或棋盤。自訂繪圖可以避免使用大量節點帶來的額外負擔，有機會降低記憶體用量並提升效能。

• 製作自訂的 UI 控制項，以滿足很多可用的控制項之外的特別需求。

繪製

將腳本新增到任何 CanvasItem 衍生節點（例如 Control 或 Node2D）上。然後覆寫 _draw() 方法。

GDScriptC#

extends Node2D

func _draw():
    pass  # Your draw commands here.

繪圖指令的詳細說明可參見 CanvasItem 類別說明文件。這類指令非常多，下面範例會介紹其中幾個常用的。

更新

_draw 方法只會被呼叫一次，之後繪圖指令會被快取起來，所以不需要再重複呼叫。

如果變數或狀態改變後需要重繪，只要在該節點呼叫 CanvasItem.queue_redraw，就會觸發新的 _draw() 呼叫。

以下是一個稍微複雜一點的範例，我們有一個可以隨時修改的貼圖變數，並且透過 setter，在貼圖變更時強制重繪：

GDScriptC#

extends Node2D

@export var texture : Texture2D:
    set(value):
        texture = value
        queue_redraw()

func _draw():
    draw_texture(texture, Vector2())

你可以在編輯器中將 FileSystem 分頁下的預設 icon.svg 拖曳到 Inspector 分頁的 Texture 屬性，來測試這段程式。當上面的腳本正在執行時，只要變更 Texture 屬性的值，貼圖也會隨之自動更新。

有時我們可能需要每一禎都重繪。這時可以在 _process 方法裡呼叫 queue_redraw，像這樣：

GDScriptC#

extends Node2D

func _draw():
    pass  # Your draw commands here.

func _process(_delta):
    queue_redraw()

座標與線寬對齊

繪圖 API 使用的是 CanvasItem 的座標系統，不一定是像素座標。也就是說，_draw() 用的是應用過 CanvasItem 轉換後的座標空間。此外，你還可以用 draw_set_transform 或 draw_set_transform_matrix 再加上自訂轉換。

使用 draw_line 時，應注意線寬。如果線寬為奇數，起點和終點座標應加上 0.5，才能讓線條置中，如下圖所示。

GDScriptC#

func _draw():
    draw_line(Vector2(1.5, 1.0), Vector2(1.5, 4.0), Color.GREEN, 1.0)
    draw_line(Vector2(4.0, 1.0), Vector2(4.0, 4.0), Color.GREEN, 2.0)
    draw_line(Vector2(7.5, 1.0), Vector2(7.5, 4.0), Color.GREEN, 3.0)

同理，對 draw_rect 方法（filled = false）也適用。

GDScriptC#

func _draw():
    draw_rect(Rect2(1.0, 1.0, 3.0, 3.0), Color.GREEN)
    draw_rect(Rect2(5.5, 1.5, 2.0, 2.0), Color.GREEN, false, 1.0)
    draw_rect(Rect2(9.0, 1.0, 5.0, 5.0), Color.GREEN)
    draw_rect(Rect2(16.0, 2.0, 3.0, 3.0), Color.GREEN, false, 2.0)

抗鋸齒繪圖

Godot在 draw_line 中提供方法參數來啟用抗鋸齒功能，但並非所有自訂繪圖方法都提供這個 抗鋸齒（antialiased） 參數。

對於不提供 抗鋸齒（antialiased） 參數的自訂繪圖方法，你可以啟用 2D MSAA，這會影響整個視口的算繪。這個功能（2D MSAA）提供了高品質的抗鋸齒，但性能成本更高，而且只適用於特定元素。參見 2D 抗鋸齒 以瞭解更多資訊。

下圖比較了最小寬度（width=-1）的線條在 antialiased=false、antialiased=true，以及啟用 2D MSAA 2x、4x、8x（antialiased=false）下的效果。

工具

有時你也會希望在編輯器中運行節點時自訂繪圖，這可以用來做功能或行為的預覽與視覺化。

你可以在 GDScript 和 C# 中使用 tool annotation 來達成這個效果。更多資訊請參考下方 範例 以及 在編輯器中執行程式碼。

範例 1：繪製自訂形狀

現在我們會用 Godot 的自訂繪圖功能，畫出 Godot 內建函式無法直接繪製的東西。我們將用程式碼，純粹用繪圖指令重現 Godot 標誌。

你需要自行寫一個函式來完成這個繪圖。

備註

以下教學會使用固定座標集，這在高解析度螢幕（大於 1080p）下可能會顯得太小。如果你遇到這種情況，可以在專案設定的 Display > Window > Stretch > Scale 中調高視窗縮放比例（2 或 4 通常效果不錯），以因應高解析度顯示。

繪製自訂多邊形

雖然有專門用來繪製自訂多邊形的節點（Polygon2D），但這裡我們只用較低階的繪圖函式，將所有形狀畫在同一個節點上，這樣之後也方便擴充出更複雜的圖形。

首先，我們要定義一組點（X 和 Y 座標），作為這個形狀的基礎：

GDScriptC#

extends Node2D

var coords_head : Array = [
    [ 22.952, 83.271 ],  [ 28.385, 98.623 ],
    [ 53.168, 107.647 ], [ 72.998, 107.647 ],
    [ 99.546, 98.623 ],  [ 105.048, 83.271 ],
    [ 105.029, 55.237 ], [ 110.740, 47.082 ],
    [ 102.364, 36.104 ], [ 94.050, 40.940 ],
    [ 85.189, 34.445 ],  [ 85.963, 24.194 ],
    [ 73.507, 19.930 ],  [ 68.883, 28.936 ],
    [ 59.118, 28.936 ],  [ 54.494, 19.930 ],
    [ 42.039, 24.194 ],  [ 42.814, 34.445 ],
    [ 33.951, 40.940 ],  [ 25.637, 36.104 ],
    [ 17.262, 47.082 ],  [ 22.973, 55.237 ]
]

這種格式雖然精簡，但 Godot 並不直接支援用來繪製多邊形。在不同情境下，你可能需要從檔案讀取這些座標，或在執行時動態計算，因此可能要進行額外的轉換。

為了將這些座標轉換成 Godot 可用的格式，我們會寫一個新的方法 float_array_to_Vector2Array()。接著覆寫 _ready() 函式（Godot 會在執行開始時只呼叫一次），將這些座標載入變數：

GDScriptC#

var head : PackedVector2Array

func float_array_to_Vector2Array(coords : Array) -> PackedVector2Array:
    # Convert the array of floats into a PackedVector2Array.
    var array : PackedVector2Array = []
    for coord in coords:
        array.append(Vector2(coord[0], coord[1]))
    return array

func _ready():
    head = float_array_to_Vector2Array(coords_head);

最後，我們會使用 draw_polygon 方法來繪製這個形狀，傳入點的陣列（Vector2 格式）和顏色，如下所示：

GDScriptC#

func _draw():
    # We are going to paint with this color.
    var godot_blue : Color = Color("478cbf")
    # We pass the PackedVector2Array to draw the shape.
    draw_polygon(head, [ godot_blue ])

執行時你應該會看到類似這樣的畫面：

請注意，Logo 下半部看起來呈現分段狀，這是因為這部分只用了少量點來定義。若想要模擬平滑曲線，可以在陣列中增加更多點，或用數學函式來插值產生曲線，直接在程式碼中建立平滑形狀（詳見 範例 2）。

多邊形會自動將最後一個點與第一個點連接，形成封閉形狀。

繪製連續線段

繪製一串不封閉成多邊形的連續線段，其方式與前述方法相似。我們會用連續線段來繪製 Godot 標誌上的嘴巴。

首先，定義構成嘴巴形狀的座標列表，如下所示：

GDScriptC#

var coords_mouth = [
    [ 22.817, 81.100 ], [ 38.522, 82.740 ],
    [ 39.001, 90.887 ], [ 54.465, 92.204 ],
    [ 55.641, 84.260 ], [ 72.418, 84.177 ],
    [ 73.629, 92.158 ], [ 88.895, 90.923 ],
    [ 89.556, 82.673 ], [ 105.005, 81.100 ]
]

我們會將這些座標載入一個變數，並另外定義一個可調整的線寬變數：

GDScriptC#

var mouth : PackedVector2Array
var _mouth_width : float = 4.4

func _ready():
    head = float_array_to_Vector2Array(coords_head);
    mouth = float_array_to_Vector2Array(coords_mouth);

最後，我們用 draw_polyline 方法來真正畫出這條線，如下：

GDScriptC#

func _draw():
    # We will use white to draw the line.
    var white : Color = Color.WHITE
    var godot_blue : Color = Color("478cbf")

    draw_polygon(head, [ godot_blue ])

    # We draw the while line on top of the previous shape.
    draw_polyline(mouth, white, _mouth_width)

你應該會看到以下結果：

和 draw_polygon() 不同的是，polyline 只能為所有點指定一個單一顏色（第二個參數）。這個方法還有兩個額外參數：線寬（預設為最細），以及是否啟用抗鋸齒（預設關閉）。

_draw 的呼叫順序很重要——就像場景樹中的節點一樣，繪圖會從上到下依序執行，被後畫的圖形會覆蓋在前面的圖形上。如果兩個圖形重疊，最晚繪製的會蓋住之前的。在這個例子中，我們希望嘴巴畫在頭的上方，所以將其放在後面。

注意，我們可以用不同的方式定義顏色，例如十六進位色碼或預設顏色名稱。更多常數和顏色定義方式請參考 Color 類別。

繪製圓形

要畫出眼睛，我們會額外呼叫 4 次繪圖函式，分別以不同的大小、顏色與位置來畫出眼睛的形狀。

要畫圓形，可以用 draw_circle 方法，指定圓心的位置（以 Vector2 表示）、半徑與顏色：

GDScriptC#

func _draw():
    var white : Color = Color.WHITE
    var godot_blue : Color = Color("478cbf")
    var grey : Color = Color("414042")

    draw_polygon(head, [ godot_blue ])
    draw_polyline(mouth, white, _mouth_width)

    # Four circles for the 2 eyes: 2 white, 2 grey.
    draw_circle(Vector2(42.479, 65.4825), 9.3905, white)
    draw_circle(Vector2(85.524, 65.4825), 9.3905, white)
    draw_circle(Vector2(43.423, 65.92), 6.246, grey)
    draw_circle(Vector2(84.626, 66.008), 6.246, grey)

執行時你應該會看到這樣的畫面：

若要繪製不填滿的圓弧（由特定角度決定的圓的一部分），可以用 draw_arc 方法。

繪製線條

最後要繪製鼻子這個形狀時，我們會用一條線來近似。

你可以用 draw_line 方法來畫一段線段，只需提供起點和終點座標，如下：

GDScriptC#

func _draw():
    var white : Color = Color.WHITE
    var godot_blue : Color = Color("478cbf")
    var grey : Color = Color("414042")

    draw_polygon(head, [ godot_blue ])
    draw_polyline(mouth, white, _mouth_width)
    draw_circle(Vector2(42.479, 65.4825), 9.3905, white)
    draw_circle(Vector2(85.524, 65.4825), 9.3905, white)
    draw_circle(Vector2(43.423, 65.92), 6.246, grey)
    draw_circle(Vector2(84.626, 66.008), 6.246, grey)

    # Draw a short but thick white vertical line for the nose.
    draw_line(Vector2(64.273, 60.564), Vector2(64.273, 74.349), white, 5.8)

現在你應該能在螢幕上看到下列形狀：

注意，如果要同時畫多條不連接的線段，可以用 draw_multiline 方法一次畫出所有線段，這樣效能會更好。

繪製文字

雖然最常見的文字顯示方法是使用 Label 節點，但底層的 _draw 函式也能讓你在自訂節點繪圖中加入文字。我們會用這個方法在機器人頭下方加上「GODOT」字樣。

這裡我們會用 draw_string 方法來達成：

GDScriptC#

var default_font : Font = ThemeDB.fallback_font;

func _draw():
    var white : Color = Color.WHITE
    var godot_blue : Color = Color("478cbf")
    var grey : Color = Color("414042")

    draw_polygon(head, [ godot_blue ])
    draw_polyline(mouth, white, _mouth_width)
    draw_circle(Vector2(42.479, 65.4825), 9.3905, white)
    draw_circle(Vector2(85.524, 65.4825), 9.3905, white)
    draw_circle(Vector2(43.423, 65.92), 6.246, grey)
    draw_circle(Vector2(84.626, 66.008), 6.246, grey)
    draw_line(Vector2(64.273, 60.564), Vector2(64.273, 74.349), white, 5.8)

    # Draw GODOT text below the logo with the default font, size 22.
    draw_string(default_font, Vector2(20, 130), "GODOT",
                HORIZONTAL_ALIGNMENT_CENTER, 90, 22)

這裡我們先將預設主題字型載入到 defaultFont 變數（你也可以用自訂字型），接著傳入參數：字型、位置、文字內容、水平對齊方式、寬度，以及字體大小。

你應該會在螢幕上看到下列畫面：

更多文字相關的參數與方法，請參考 CanvasItem 類別說明文件。

在編輯時顯示繪圖

目前為止的程式碼雖然能在執行時畫出 logo，但在編輯器的「2D 檢視」中並不會顯示。有些情況下，你也會希望自訂的 Node2D 或控制項能在編輯器中顯示，方便定位和調整大小，就像其他節點一樣。

若要讓 logo 直接在編輯器中顯示（不執行時也能看見），你可以加上 @tool 註解，讓自訂節點的繪圖也會在編輯時出現，例如：

GDScriptC#

@tool
extends Node2D

在你第一次新增或移除 @tool 註解後，需要儲存場景，並（C# 專案）重新編譯，再從選單選取「場景 > 重新載入已儲存場景」刷新 2D 檢視，這樣才能看到節點的最新繪圖。

動畫

如果想在執行時讓自訂形狀變化，可以在執行期間修改呼叫的方法或其參數，或是套用變換。

例如，若想讓剛剛設計的自訂形狀旋轉，可以在 _ready 和 _process 方法中加上以下變數與程式碼：

GDScriptC#

extends Node2D

@export var rotation_speed : float = 1  # In radians per second.

func _ready():
    rotation = 0
    ...

func _process(delta: float):
    rotation -= rotation_speed * delta

上面的程式碼有個問題：由於我們的點是從左上角 (0, 0) 開始，一路往右下建立，因此旋轉時會以左上角為中心。單純改變節點的位置變換沒辦法解決，因為旋轉變換會先套用。

雖然我們可以將所有點的座標重寫成以 (0, 0) 為中心（包含負座標），但這樣會相當麻煩。

一個解決方式是用較低階的 draw_set_transform 方法，先把所有點在 CanvasItem 的座標空間中平移，把中心移到你想要的軸心，然後再用節點的平移將它移回原本位置（可在編輯器或程式中設定），像這樣：

GDScriptC#

func _ready():
    rotation = 0
    position = Vector2(60, 60)
    ...

func _draw():
    draw_set_transform(Vector2(-60, -60))
    ...

這樣結果就會繞著 (60, 60) 為中心旋轉：

如果想讓 _draw() 中的某個屬性產生動畫，要記得呼叫 queue_redraw() 強制重繪，否則畫面不會即時更新。

例如，我們可以改變機器人嘴巴的線段寬度，讓它看起來像是在張嘴和閉嘴，讓寬度隨著正弦波（sin）變化：

GDScriptC#

var _mouth_width : float = 4.4
var _max_width : float = 7
var _time : float = 0

func _process(delta : float):
    _time += delta
    _mouth_width = abs(sin(_time) * _max_width)
    queue_redraw()

func _draw():
    ...
    draw_polyline(mouth, white, _mouth_width)
    ...

執行時大致會長這樣：

請注意，_mouth_width 和其他自訂屬性一樣，也可以用更高階的方式（例如 Tween 或 AnimationPlayer 節點）來製作動畫。唯一的差別是，你必須呼叫 queue_redraw() 才會讓螢幕及時顯示動畫效果。

範例 2：繪製動態線段

前面的範例讓你學會了如何用自訂形狀和動畫來繪製和修改節點。這種做法有一些優點，例如可用精確座標與向量繪圖（不是用點陣圖），因此在螢幕縮放時會維持品質。有時候也可以用更高階的元件組合出類似效果，例如用 Sprite2D、AnimatedSprite2D 載入 SVG 資源（SVG 也是向量圖），搭配 AnimationPlayer 節點。

有些情況下，執行前並不知道圖形的最終樣貌，因此無法預先準備。這裡我們會示範如何畫出一條座標未知、會根據使用者輸入動態變化的線段。

繪製兩點之間的直線

假設我們要畫一條連接兩點的直線，第一個點固定在左上角 (0, 0)，第二個點則由螢幕上的游標位置決定。

可以用下列方式畫出這兩點之間的動態直線：

GDScriptC#

extends Node2D

var point1 : Vector2 = Vector2(0, 0)
var width : int = 10
var color : Color = Color.GREEN

var _point2 : Vector2

func _process(_delta):
    var mouse_position = get_viewport().get_mouse_position()
    if mouse_position != _point2:
        _point2 = mouse_position
        queue_redraw()

func _draw():
    draw_line(point1, _point2, color, width)

這個範例中，我們每一禎都用 get_mouse_position 取得滑鼠在預設視口中的位置。如果位置自上次繪製以來有變化（這樣可以避免每一禎都重繪），就安排重繪。_draw() 方法只會畫一條線：從左上角到滑鼠位置的綠色線段，寬度為 10 像素。

線段的寬度、顏色和起點位置都可以用對應的屬性來設定。

執行時效果如下：

繪製兩點之間的圓弧

上面的範例可以運作，不過有時候你可能想用直線以外的形狀或方式連接這兩個點。

這次我們試著在兩點間畫出一段圓弧（圓的一部分）。

如果將線的起點、分段數、寬度、顏色與抗鋸齒等屬性導出（export），就可以直接在編輯器屬性面板輕鬆調整這些參數：

GDScriptC#

extends Node2D

@export var point1 : Vector2 = Vector2(0, 0)
@export_range(1, 1000) var segments : int = 100
@export var width : int = 10
@export var color : Color = Color.GREEN
@export var antialiasing : bool = false

var _point2 : Vector2

畫圓弧時，可以用 draw_arc 方法。能通過兩點的圓弧有很多種，這裡我們選擇將圓心設在這兩點的中點，畫出一段半圓。

計算這段圓弧會比直線稍微複雜一點：

GDScriptC#

func _draw():
    # Average points to get center.
    var center : Vector2 = Vector2((_point2.x + point1.x) / 2,
                                   (_point2.y + point1.y) / 2)
    # Calculate the rest of the arc parameters.
    var radius : float = point1.distance_to(_point2) / 2
    var start_angle : float = (_point2 - point1).angle()
    var end_angle : float = (point1 - _point2).angle()
    if end_angle < 0:  # end_angle is likely negative, normalize it.
        end_angle += TAU

    # Finally, draw the arc.
    draw_arc(center, radius, start_angle, end_angle, segments, color,
             width, antialiasing)

這裡半圓的圓心會設在兩點的中點，半徑是兩點距離的一半。起始角度和結束角度分別是 point1 到 point2 或從 point2 到 point1 的向量角度。注意我們要把 end_angle 轉成正值，否則如果 end_angle 小於 start_angle，圓弧會逆時針繪製（這不是我們想要的，因為這樣會畫在上方）。

結果應該會如下圖，圓弧往下並連接兩點：

你可以隨意在屬性面板調整這些參數，獲得不同效果：改變顏色、線寬、抗鋸齒或增加分段數讓曲線更平滑（但會消耗更多效能）。