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

创建 iOS 插件¶

本页说明 iOS 插件可以为你做什么、如何使用现有的插件、以及编写新插件的步骤。

iOS 插件允许你使用第三方库，并支持 iOS 特定功能，如应用内购买、GameCenter 集成、ARKit 支持等。

加载和使用现有的插件¶

一个iOS插件需要一个 .gdip 配置文件, 一个二进制文件, 它可以是 .a 静态库, 也可以是 .xcframework 包含 .a 静态库, 可能还有其他依赖关系. 要使用它, 你需要:

将插件的文件复制到Godot项目的 res://ios/plugins 目录中. 你也可以将文件分组在一个子目录中, 比如 res://ios/plugins/my_plugin .
Godot编辑器自动检测并导入 res://ios/plugins 及其子目录中的 .gdip 文件.
你可以通过进入项目->导出... ->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())

备注

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 作为你的开发环境.

参见

The Godot iOS Plugins.

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

要构建一个iOS插件:

在Xcode中为您的插件创建一个Objective-C静态库.
在 HEADER_SEARCH_PATHS 中添加Godot引擎头文件作为插件库的依赖. 你可以在 Build Settings 选项卡中找到这个设置:
- 从 Godot GitHub 页面下载 Godot 引擎的源代码。
- 运行SCons来生成头文件. 通过阅读为 iOS 平台编译来了解这个过程. 不需要等待编译完成就可以继续, 因为在引擎开始编译之前就会生成头文件.
- 你应该为iOS插件和iOS导出模板使用相同的头文件.
在 Build Settings 选项卡的 OTHER_CFLAGS 中指定静态库的编译选项。最重要的是 -fcxx-modules 和 -fmodules，如果你需要支持调试就还有 -DDEBUG。其他选项应该和你编译 Godot 时使用的一样。例如：

-DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND

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

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

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