什麼是 GDExtension？

前言

GDExtension 是 Godot 專用的技術，允許引擎在執行時與原生 共用函式庫 互動。你可以利用它在不需要重新編譯引擎的情況下執行原生程式碼。

備註

GDExtension 不是 指令碼語言，也與 GDScript 無關。

GDExtension 與 C++ 模組的差異

你可以同時使用 GDExtension 和 C++ 模組 在 Godot 專案中執行 C 或 C++ 程式碼。

這兩者也都能將第三方函式庫整合進 Godot。你該選哪一種方式，取決於你的需求。

警告

GDExtension 目前屬於*實驗性*功能，這表示未來為了修正重大錯誤或加入關鍵功能，可能會破壞相容性。

GDExtension 的優點

與模組不同，GDExtension 不需要編譯引擎原始碼，使你的作品更容易分發。你可以存取 GDScript 與 C# 幾乎所有的 API，讓你編寫遊戲邏輯時能完全掌控效能。如果你需要將高效能程式碼作為外掛發布到 素材庫，這是理想的選擇。

此外：

  • GDExtension 不僅限於 C 和 C++。多虧有 第三方綁定，你還可以用許多其他語言來開發。

  • 你可以在編輯器和匯出專案時共用同一份已編譯的 GDExtension 函式庫。而 C++ 模組如果要在執行時提供這些功能，則必須為所有要用到的匯出範本重新編譯。

  • GDExtension 只需要你編譯自己的函式庫，不需要重新編譯整個引擎。這點和 C++ 模組不同，後者必須靜態編譯進引擎主體。每次變更模組內容，都必須重編整個引擎。即使使用增量編譯，這個流程還是會比 GDExtension 慢許多。

C++ 模組的優點

如果 GDExtension 無法滿足需求時，建議使用 C++ 模組：

  • C++ 模組可以與引擎有更深度的整合。GDExtension 的存取層級不如靜態模組。

  • 你可以透過 C++ 模組為專案加入額外功能，不必攜帶原生函式庫檔案。這同樣適用於匯出的專案。

備註

如果你發現有些功能只能透過自訂模組存取，而 GDExtension 無法做到，歡迎在 godot-cpp repository 提出議題，討論如何實作並開放這些缺失的功能。

支援的語言

Godot 開發團隊官方支援以下 GDExtension 語言綁定：

備註

官方暫無計畫為 GDExtension 提供更多語言支援。不過社群有提供多種其他語言的綁定（見下方列表）。

以下語言綁定由社群開發並維護：

備註

本頁所列的語言綁定未必都適合正式專案使用。建議你在專案開始前先仔細評估每個選項，也請再次確認該綁定是否與你目前使用的 Godot 版本相容。

版本相容性

通常，針對較早版本 Godot 開發的 GDExtension 可以在後續的小版本中運作，但反過來則不行。例如，為 Godot 4.2 開發的 GDExtension 可以在 Godot 4.3 運作，但為 Godot 4.3 開發的 GDExtension 則無法在 Godot 4.2 運作。

因此，在開發 GDExtension 時，建議以支援你所需功能的最低 Godot 版本為目標，而非最新版本。如此可避免為不同 Godot 版本重複建置多份函式庫。

不過，GDExtension 目前屬於*實驗性*功能，未來若需修正重大錯誤或加入關鍵功能，仍有可能破壞相容性。例如，針對 Godot 4.0 製作的 GDExtension 無法在 Godot 4.1 使用（詳情見 將 GDExtension 更新到 4.1）。

GDExtension 也僅支援與其編譯時浮點精度相同的引擎版本。也就是說，如果你使用的是雙精度浮點（double precision）引擎，GDExtension 也必須用雙精度建置，並且必須使用你自訂引擎版本所產生的 extension_api.json。詳情請參考 大世界座標。

一般來說，如果你有自訂 Godot 引擎版本，建議使用該版本產生一份 extension_api.json 來給你的 GDExtension 使用，因為這可能與官方版本有細微差異。