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...

自訂平台移植

如同 以 C++ 自訂模組，Godot 的多平台架構設計允許你在不修改現有原始碼的情況下，建立自訂平台移植。

有一個獨立於引擎本體發佈的自訂平台移植範例為 FRT，其目標為單板電腦。請注意，該平台移植目前僅支援 Godot 3.x，因此並未使用 Godot 4 新增的 DisplayServer 抽象層。

你可能想建立自訂平台移植的原因包括：

• You want to port your game to consoles (see also the Godot website on console support), but wish to write the platform layer yourself. This is a long and arduous process, as it requires signing NDAs with console manufacturers, but it allows you to have full control over the console porting process.

• 你想將 Godot 移植到目前尚未支援的特殊平台。

如果你對建立自訂平台移植有任何問題，歡迎在 Godot 貢獻者聊天室 的「#platforms」頻道中發問。

備註

Godot 是一款現代化的引擎，對硬體有現代等級的需求。即使你只打算在目標平台上執行單純的 2D 專案，仍需消耗足夠的記憶體，使其無法在大多數復古主機上運作。以 Godot 4 為例，在 Linux 上執行一個空白專案約需 100 MB RAM（無頭模式約 50 MB）。

如果你想在記憶體非常有限的平台上運行 Godot，可以考慮使用較舊版本的 Godot，其記憶體需求較低。移植流程大致相同，唯一差異是舊版 Godot 並未將 DisplayServer 從 OS 單例中分離。

官方平台移植

建立自訂平台移植時，可參考官方平台移植的實作：

• Windows

• macOS

• Linux/*BSD

• Android

• iOS

• Web

雖然平台程式碼通常是獨立的，但也有例外。例如，跨多平台共用的音效驅動與算繪驅動程式，會被放在 Godot 原始碼的 drivers/ 資料夾 中。

建立自訂平台移植

建立自訂平台移植是一項龐大的工程，需要事先熟悉該平台的 SDK。你所需的功能越多，所需投入的工作量也會隨之增加：

平台移植必備功能

最低限度，平台移植必須實作 OS 單例中的方法，才能進行建置並支援無頭模式運作。此外，平台資料夾內必須有一個 logo.svg （32×32像素）向量圖，這個圖示將出現在匯出預設檔案中。

請參考 Linux/*BSD 平台的 這個實作 作為範例，也可參考 OS 單例標頭。

備註

如果你的目標平台類似 UNIX，建議繼承 OS_Unix 類別，這樣能自動完成大部分作業。

如果平台不是類 UNIX，可以參考 Windows 移植 的實作。

detect.py 檔案

你必須在平台資料夾下建立 detect.py 檔案並實作所有方法。SCons 需要這個檔案來判斷平台是否為可用的編譯選項。可參考 Linux/*BSD 平台的 detect.py 檔案。

detect.py 內應實作下列所有方法：

• is_active()：可用於暫時停用該平台建置。通常應永遠回傳 True。

• get_name()：回傳平台在使用者介面可見的名稱字串。

• can_build()：如果主機系統能建置該平台，則回傳 True，否則回傳 False。不要在這裡放慢速檢查，因為這會在使用者查詢平台清單時執行。請改用 configure() 進行較完整的相依檢查。

• get_opts()：回傳該平台可由使用者自訂的 SCons 建置選項清單。

• get_flags()：回傳此平台會覆寫的 SCons 旗標清單。

• configure()：執行建置組態，例如根據 SCons 選項自動選擇編譯器參數。

平台移植的選用功能

實務上，如果你要顯示畫面並處理輸入裝置，僅有無頭模式是不夠的。對大多數遊戲來說，也需要音效輸出功能。

本清單中的部分連結以 Linux/*BSD 平台實作為參考。

• 一個或多個 DisplayServer，需實作視窗管理相關方法。DisplayServer 也涵蓋滑鼠、觸控螢幕、繪圖板（筆輸入）等功能。可參考 DisplayServer 單例標頭。

  • 對於不具備完整視窗系統的平台（或你的移植不需要完整視窗支援），大部分視窗相關函式可以保持未實作。其功能僅需檢查視窗 ID 是否為 MAIN_WINDOW_ID，如調整大小等操作可直接對應到平台的螢幕解析度功能（如適用）。其他視窗 ID 的建立或操作可直接拒絕。

• 如果目標平台支援相關圖形 API： 需實作 Vulkan、Direct3D 12、OpenGL 3.3 或 OpenGL ES 3.0 的算繪上下文。

• 必須提供 鍵盤 與 控制器 的輸入處理程式。

• 一個或多個 音效驅動。音效驅動可以放在 platform/ 資料夾（如 Android、Web 平台），或若多平台共用則可放於 drivers/ 資料夾。可參考 AudioServer 單例標頭。

• 當機處理器，可於遊戲當機時列印回溯，有助於在無法直接取得日誌的平台上進行除錯。

• 文字轉語音驅動 （提升無障礙性）。

• 匯出處理器 （用於從編輯器匯出，包含 單鍵部署 功能）。如果你只需從編輯器匯出 PCK 並直接執行範本二進位檔，則不必實作匯出處理器。可參考 EditorExportPlatform 標頭 。若實作 單鍵部署 ，平台資料夾應包含 run_icon.svg （16×16），此圖示會顯示於編輯器上方。

如果目標平台不支援運行 Vulkan、Direct3D 12、OpenGL 3.3 或 OpenGL ES 3.0，你有兩種選擇：

• 於執行時使用函式庫將 Vulkan 或 OpenGL 呼叫轉換為其他圖形 API。例如，macOS 上會用 MoltenVK 將 Vulkan 呼叫即時轉換為 Metal。

• 從零開始設計新的算繪器。這是非常大的工程，尤其是如果你要同時支援進階 2D 與 3D 算繪功能。

發佈自訂平台移植

危險

在發佈自訂平台移植前，請確認你有權分發所有連結到的程式碼。主機平台 SDK 通常受 NDA 保護，禁止對外公開散布。

平台移植設計上儘量自給自足。大多數程式碼都能放在 platform/ 子資料夾內。與 以 C++ 自訂模組 類似，只需將平台資料夾 git clone 到 Godot 專案的 platform/ 目錄，執行 scons platform=<名稱> 就能建置。除非需要安裝第三方依賴，否則不需其他步驟。

但如果需要自訂算繪驅動，就必須在 drivers/ 資料夾下新增其他目錄。這種情況下，可以將平台移植作為 Godot 倉庫的 fork 發佈，或作為多個可套用到 Godot 倉庫 clone 的目錄組合發佈。