Work in progress

The content of this page was not yet updated for Godot 4.2 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 特定功能,如應用內購買、GameCenter 集成、ARKit 支援等。

建立內容

一個iOS外掛程式需要一個 .gdip 設定檔, 一個二進位檔案, 它可以是 .a 靜態程式庫, 也可以是 .xcframework 包含 .a 靜態程式庫, 可能還有其他依賴關係. 要使用它, 你需要:

  1. 將外掛程式的檔複製到Godot專案的 res://ios/plugins 目錄中. 你也可以將檔群組在一個子目錄中, 比如 res://ios/plugins/my_plugin .

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

  3. 你可以通過進入專案->匯出... ->iOS, 在分頁中, 滾動到外掛程式部分, 找到並啟動偵測到的外掛程式.

../../../_images/ios_export_preset_plugins_section.png

當外掛程式處於活動狀態時,您可以使用 Engine.get_singleton() 存取外掛程式:

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

備註

插件的檔案必須位於「res://ios/plugins/」目錄或子目錄中,否則Godot編輯器將不會自動偵測到它們。

建立內容

Godot iOS外掛程式的核心是一個iOS庫( .a 檔檔案或 .xcframework 包含靜態程式庫), 其要求如下:

  • 該庫必須依賴Godot引擎標頭檔.

  • 該庫必須附帶一個 .gdip 設定檔.

一個iOS外掛程式可以擁有與Godot模組相同的功能, 但提供了更多的靈活性, 並且不需要重新建構引擎.

下面是開始開發外掛程式的步驟. 我們建議使用 Xcode 作為你的開發環境.

也參考

在這份文件之外,你可能也會想看看 Godot 的 demo 專案

Godot iOS 外掛程式範本 為您提供了啟動iOS外掛程式所需的所有樣板.

建立內容

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

  2. HEADER_SEARCH_PATHS 中新增Godot引擎標頭檔作為外掛程式庫的依賴. 你可以在 Build Settings 分頁中找到這個設定:

    • 在這份文件之外,你可能也會想看看 Godot 的 demo 專案

    • 運作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
  1. 為你的外掛程式新增所需的邏輯, 並建立你的庫以生成一個 .a 檔案. 你可能需要同時建立 debugrelease 目標 .a 檔案. 根據你的需要, 選擇其中一個或兩個. 如果你同時需要除錯和發行 .a 檔, 它們的名字應該符合以下模式: [PluginName].[TargetType].a . 你也可以用SCons配置來建構靜態程式庫.

  2. iOS 外掛程式系統也支援 .xcframework 檔案。你可以用類似這樣的命令來生成它:

xcodebuild -create-xcframework -library [DeviceLibrary].a -library [SimulatorLibrary].a -output [PluginName].xcframework
  1. 建立一個Godot iOS外掛程式設定檔, 以説明系統偵測和載入你的外掛程式:

    • 設定檔的副檔名必須是 gdip (e.g.: 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 : 這應該是外掛程式庫( axcframework )檔的路徑.

        • 檔路徑可以是相對的(例如: MyPlugin.a , MyPlugin.xcframework ), 在這種情況下, 它是相對於 gdip 檔所在的目錄.

        • 檔路徑可以是絕對的: res://some_path/MyPlugin.ares://some_path/MyPlugin.xcframework .

        • 如果你需要多目標庫使用, 檔案名應該是 MyPlugin.a , .a 檔應該命名為 MyPlugin.release.aMyPlugin.debug.a .

        • 如果你使用多目標庫 xcframework , 它們在配置中的檔案名應該是 MyPlugin.xcframework. .xcframework 檔應該被命名為 MyPlugin.release.xcframeworkMyPlugin.debug.xcframework .

      dependenciesplist 部分是可選的, 定義如下:

      • 依賴 :

        • linked(連結) : 包含iOS應用應該包含的iOS框架列表.

        • embedded : 嵌入包含一個iOS框架或庫的列表, 這些框架或庫將被連結並嵌入到最終的iOS應用程式中.

        • system : 包含外掛程式所需的iOS系統框架的列表.

        • capabilities(功能) : 包含外掛程式所需的iOS功能列表, 可用功能列表可以在 Apple UIRequiredDeviceCapabilities documentation page 找到.

        • files(檔案) : 包含匯出時應複製的檔列表. 這對資料檔案或圖像很有用.

        • linker_flags : 包含一個連結器旗標的列表, 在匯出外掛程式時新增到Xcode專案中.

      • plist: 應該有鍵和值,應該存在於 Info.plist 檔案中。

        • 每行應遵循模式: KeyName:KeyType=KeyValue

        • KeyType 支援的值是 string, integer, boolean, raw, string_input

        • 如果沒有使用型別,例如: KeyName="KeyValue" ,將使用 string 型別。

        • 如果使用 raw 型別,對應鍵的值將按原樣儲存在 Info.plist 中。

        • 如果使用 string_input 型別,你將能夠在匯出視窗中修改值。