创建 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, 在选项卡中, 滚动到插件部分, 找到并激活检测到的插件.

当插件处于活动状态时，你可以使用 Engine.get_singleton() 访问插件：

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

备注

The plugin’s files have to be in the res://ios/plugins/ directory or a subdirectory, otherwise the Godot editor will not automatically detect them.

创建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 时使用的一样。例如：

-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 文件。你可以用类似这样的命令来生成它：

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 : 这应该是插件库( 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 类型。

       • If raw type is used value for corresponding key will be stored in Info.plist as is.

       • 如果使用 string_input 类型，你将能够在导出窗口中修改值。