创建 iOS 插件

本页说明 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() 访问插件：

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

创建iOS插件

Godot iOS插件的核心是一个iOS库( .a 档文件或 .xcframework 包含静态库), 其要求如下:

  • 该库必须依赖Godot引擎头文件.

  • 该库必须附带一个 .gdip 配置文件.

一个iOS插件可以拥有与Godot模块相同的功能, 但提供了更多的灵活性, 并且不需要重新构建引擎.

下面是开始开发插件的步骤. 我们建议使用 Xcode 作为你的开发环境.

参见

Godot iOS 插件 .

Godot iOS 插件模板 为您提供了启动iOS插件所需的所有样板.

要构建一个iOS插件:

  1. 在Xcode中为您的插件创建一个Objective-C静态库.

  2. 在 HEADER_SEARCH_PATHS 中添加Godot引擎头文件作为插件库的依赖. 你可以在 Build Settings 选项卡中找到这个设置:

    • 从 Godot GitHub 页面下载 Godot 引擎的源代码。

    • 运行SCons来生成头文件. 通过阅读 为 iOS 平台编译 来了解这个过程. 不需要等待编译完成就可以继续, 因为在引擎开始编译之前就会生成头文件.

    • 你应该为iOS插件和iOS导出模板使用相同的头文件.

  3. 在 Build Settings 选项卡的 OTHER_CFLAGS 中指定静态库的编译选项。最重要的是 -fcxx-modules 和 -fmodules，如果你需要支持调试就还有 -DDEBUG。其他选项应该和你编译 Godot 时使用的一样。例如：

  1. -DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND

  1. 为你的插件添加所需的逻辑, 并建立你的库以生成一个 .a 文件. 你可能需要同时建立 debug 和 release 目标 .a 文件. 根据你的需要, 选择其中一个或两个. 如果你同时需要调试和发布 .a 文件, 它们的名字应该符合以下模式: [PluginName].[TargetType].a . 你也可以用SCons配置来构建静态库.

  2. iOS 插件系统也支持 .xcframework 文件。你可以用类似这样的命令来生成它：

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

  1. 创建一个Godot iOS插件配置文件, 以帮助系统检测和加载你的插件:

    • 配置文件的扩展名必须是 gdip (e.g.: MyPlugin.gdip ).

    • 配置文件格式如下：

      1. [config]
      2. name="MyPlugin"
      3. binary="MyPlugin.a"
      5. initialization="init_my_plugin"
      6. deinitialization="deinit_my_plugin"
      8. [dependencies]
      9. linked=[]
      10. embedded=[]
      11. system=["Foundation.framework"]
      13. capabilities=["arkit", "metal"]
      15. files=["data.json"]
      17. linker_flags=["-ObjC"]
      19. [plist]
      20. PlistKeyWithDefaultType="Some Info.plist key you might need"
      21. StringPlistKey:string="String value"
      22. IntegerPlistKey:integer=42
      23. BooleanPlistKey:boolean=true
      24. RawPlistKey:raw="
      25. <array>
      26.     <string>UIInterfaceOrientationPortrait</string>
      27. </array>
      28. "
      29. 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 , .a 文件应该命名为 MyPlugin.release.a 和 MyPlugin.debug.a .

        • 如果你使用多目标库 xcframework , 它们在配置中的文件名应该是 MyPlugin.xcframework. .xcframework 文件应该被命名为 MyPlugin.release.xcframework 和 MyPlugin.debug.xcframework .

      dependencies 和 plist 部分是可选的, 定义如下:

      • 依赖 :

        • 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 类型，你将能够在导出窗口中修改值。