Godot iOS plugins

master branch is the current development branch and can introduce breaking changes to plugin’s public interface. 3.3 branch’s aim is to provide same public interface as it was before the switch to new iOS plugin system.

Note: iOS plugins are only effective on iOS (either on a physical device or in the Xcode simulator). Their singletons will not be available when running the project from the editor, so you need to export your project to test your changes.


  • Clone this repository and its submodules:
git clone --recursive

You might have to the update godot submodule in case you require latest (unreleased) Godot changes. To do this, run:

cd godot
git fetch
git checkout origin/<branch you want to use>
  • Alternatively, you can use pre-extracted Godot headers that will be provided with release tag on the Releases page. To do this, clone this repository without submodules:
git clone

Then place the extracted Godot headers in the godot/ directory. If you choose this option, you can skip next the step which generates Godot headers.

  • To generate Godot headers, you need to run the compilation command inside the godot submodule directory:

For Godot 3.x:

scons platform=iphone target=debug

For Godot 4.x:

scons platform=ios target=debug

You don’t have to wait for full engine compilation, as header files are generated first. Once the actual compilation starts, you can stop this command by pressing Ctrl + C.

  • Run the command below to generate an .a static library for chosen target:
scons target=<debug|release|release_debug> arch=<arch> simulator=<no|yes> plugin=<plugin_name> version=<3.x|4.0>

Note: Godot’s official debug export templates are compiled with the release_debug target, not the debug target.

Building a .a library

  • Run ./scripts/ <plugin_name> <debug|release|release_debug> <godot_version> to generate fat static library with specific configuration.
  • The result .a binary will be stored in the bin/ folder.

Building a .xcframework library

  • Run ./scripts/ <plugin_name> <debug|release|release_debug> <godot_version> to generate xcframework with specific configuration. xcframework allows plugin to support both arm64 device and arm64 simulator.
  • The result .xcframework will be stored in the bin/ folder as well as intermidiate .a binaries.


Each plugin provides a file which contains documentation and examples.