Work in progress

The content of this page was not yet updated for Godot 4.4 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

建立 iOS 外掛程式

本頁將說明 iOS 外掛程式能為你做什麼、如何使用現有外掛，以及如何自行開發新的外掛。

iOS 外掛程式可讓你整合第三方函式庫，並支援 iOS 特有功能，例如：應用程式內購（In-App Purchases）、GameCenter 連動、ARKit 支援等。

載入並使用現有外掛程式

一個 iOS 外掛程式需要一個 .gdip 設定檔，以及一個二進位檔案（可以是 .a 靜態函式庫，或包含 .a 的 .xcframework），以及可能的其他依賴檔案。要使用外掛程式，你需要：

1. 將外掛程式檔案複製到 Godot 專案的 res://ios/plugins 目錄中。你也可以將檔案集中於子目錄，例如 res://ios/plugins/my_plugin。

2. Godot 編輯器會自動偵測並匯入 res://ios/plugins 及其子目錄內的 .gdip 檔案。

3. 你可以到「專案」>「匯出...」>「iOS」，於「選項」分頁往下滾動到「外掛程式」區塊，即可看到並啟用已偵測到的外掛程式。

當外掛程式已啟用時，你可以透過 Engine.get_singleton() 來存取該外掛：

if Engine.has_singleton("MyPlugin"):
    var singleton = Engine.get_singleton("MyPlugin")
    print(singleton.foo())

備註

外掛程式的檔案必須放在 res://ios/plugins/ 目錄或其子目錄下，否則 Godot 編輯器將無法自動偵測。

建立 iOS 外掛程式

本質上，一個 Godot iOS 外掛程式是一個 iOS 函式庫（.a 檔或包含靜態函式庫的 .xcframework），並需符合以下要求：

• 該函式庫必須依賴 Godot 引擎標頭檔。

• 該函式庫必須附有一個 .gdip 設定檔。

iOS 外掛程式可具備與 Godot 模組相同的功能，但更具彈性，且不需重新編譯整個引擎。

以下為開始開發外掛程式的流程。我們建議以 Xcode 作為主要開發環境。

也參考

Godot iOS 外掛程式。

Godot iOS 外掛程式範本 提供所有啟動 iOS 外掛所需的樣板。

建立 iOS 外掛程式：

1. 在 Xcode 中為你的外掛建立一個 Objective-C 靜態函式庫。

2. 在 Xcode「Build Settings」分頁的 HEADER_SEARCH_PATHS 中，新增 Godot 引擎標頭檔案作為外掛函式庫的依賴：

   • 從 Godot GitHub 頁面 下載 Godot 引擎原始碼。

   • 執行 SCons 來產生標頭檔。詳見 為 iOS 編譯。標頭檔會在引擎開始編譯前產生，因此無需等全部編譯完成即可繼續後續步驟。

   • iOS 外掛程式與 iOS 匯出範本應共用相同的標頭檔。

3. 於「Build Settings」分頁的 OTHER_CFLAGS 內指定靜態函式庫的編譯選項。最重要的標記為 -fcxx-modules、-fmodules，如需除錯還要加 -DDEBUG。其他旗標應與你編譯 Godot 時相同。例如：

-DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND

4. 實作所需的外掛邏輯並建構函式庫產生 .a 檔案。通常你會需要建立 debug 與 release 目標的 .a 檔案。若兩者皆需，請分別命名為 [PluginName].release.a 與 [PluginName].debug.a。也可改用 SCons 設定來建置靜態函式庫。

5. iOS 外掛系統亦支援 .xcframework 檔案。你可以用下列指令產生：

xcodebuild -create-xcframework -library [DeviceLibrary].a -library [SimulatorLibrary].a -output [PluginName].xcframework

6. 建立 Godot iOS 外掛程式的設定檔，讓系統可偵測並載入你的外掛：

   • 設定檔副檔名必須為 gdip``（例如：``MyPlugin.gdip）。

   • 設定檔格式如下：

     [config]
     name="MyPlugin"
     binary="MyPlugin.a"
     
     initialization="init_my_plugin"
     deinitialization="deinit_my_plugin"
     
     [dependencies]
     linked=[]
     embedded=[]
     system=["Foundation.framework"]
     
     capabilities=["arkit", "metal"]
     
     files=["data.json"]
     
     linker_flags=["-ObjC"]
     
     [plist]
     PlistKeyWithDefaultType="Some Info.plist key you might need"
     StringPlistKey:string="String value"
     IntegerPlistKey:integer=42
     BooleanPlistKey:boolean=true
     RawPlistKey:raw="
     <array>
         <string>UIInterfaceOrientationPortrait</string>
     </array>
     "
     StringPlistKeyToInput:string_input="Type something"
     

     config 區段及欄位為必填，定義如下：

     • name：外掛名稱

     • binary：外掛函式庫（a 或 xcframework）的檔案路徑。

       • 檔案路徑可為相對路徑（如 MyPlugin.a、MyPlugin.xcframework），此時會以 gdip 檔案所在目錄為基準。

       • 檔案路徑亦可為絕對路徑，如 res://some_path/MyPlugin.a 或 res://some_path/MyPlugin.xcframework。

       • 若需多目標函式庫，檔名統一為 MyPlugin.a，並分別提供 MyPlugin.release.a 與 MyPlugin.debug.a。

       • 若使用多目標 xcframework，設定內檔名應為 MyPlugin.xcframework，並分別提供 MyPlugin.release.xcframework 與 MyPlugin.debug.xcframework。

     dependencies 與 plist 區段為選填，定義如下：

     • dependencies：

       • linked：需連結的 iOS framework 清單。

       • embedded：需同時連結且嵌入於 iOS 應用程式中的 framework 或函式庫清單。

       • system：外掛所需的 iOS 系統 framework 清單。

       • capabilities：外掛需宣告的 iOS 裝置能力。完整列表見 Apple 官方文件：UIRequiredDeviceCapabilities。

       • files：匯出時應一併複製的檔案清單，適合用於資料檔或圖片等。

       • linker_flags：外掛匯出時需加到 Xcode 專案的 linker 旗標清單。

     • plist：需寫入至 Info.plist 的鍵值對。

       • 每行格式為：KeyName:KeyType=KeyValue

       • KeyType 支援：string、integer、boolean、raw、string_input

       • 若未指定型別（如：KeyName="KeyValue"），預設採用 string 型別。

       • 若指定 raw，該鍵值將直接以原始內容寫入 Info.plist。

       • 若選用 string_input，可於匯出視窗中編輯此欄值。