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

Criando plugins para iOS

Esta página explica o que os plugins do iOS podem fazer por você, como usar um plugin existente e os passos para programar um novo.

Plugins de iOS permitem que você use bibliotecas de terceiros e ofereça suporte a recursos específicos do iOS, como Compras no Aplicativo (In-App Purchases), integração com GameCenter, suporte ao ARKit e muito mais.

Carregando e usando um plugin existente

Um plugin do iOS requer um arquivo de configuração .gdip, um arquivo binário que pode ser uma biblioteca estática .a ou um .xcframework contendo bibliotecas estáticas .a, além de possivelmente outras dependências. Para usá-lo, você precisa:

1. Copiar os arquivos do plugin para o diretório res://ios/plugins do seu projeto Godot. Você também pode agrupar os arquivos em um subdiretório, como res://ios/plugins/meu_plugin.

2. O editor do Godot detecta e importa automaticamente arquivos .gdip dentro de res://ios/plugins e seus subdiretórios.

3. Você pode encontrar e ativar os plugins detectados acessando Projeto -> Exportar... -> iOS e, na aba Opções, rolando até a seção Plugins.

Quando um plugin está ativo, você pode acessá-lo em seu código usando Engine.get_singleton():

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

Nota

Os arquivos do plugin devem estar no diretório res://ios/plugins/ ou em um subdiretório, caso contrário, o editor do Godot não os detectará automaticamente.

Criando um plug-in para iOS

Em sua essência, um plugin do iOS do Godot é uma biblioteca iOS (arquivo de arquivo .a ou .xcframework contendo bibliotecas estáticas) com os seguintes requisitos:

• A biblioteca deve ter uma dependência dos cabeçalhos do mecanismo Godot.

• A biblioteca deve vir acompanhada de um arquivo de configuração .gdip.

Um plugin do iOS pode ter a mesma funcionalidade que um módulo do Godot, mas oferece mais flexibilidade e não exige a recompilação do motor.

Aqui estão os passos para iniciar o desenvolvimento de um plugin. Recomendamos usar o Xcode como seu ambiente de desenvolvimento.

Ver também

Os Plugins de iOS do Godot.

O modelo de plugin Godot iOS fornece todo o código padrão (boilerplate) que você precisa para começar seu plugin iOS.

Para construir um plugin para iOS:

1. Crie uma biblioteca estática em Objective-C para o seu plugin no Xcode.

2. Adicione os arquivos de cabeçalho do motor do Godot como uma dependência para a biblioteca do seu plugin em HEADER_SEARCH_PATHS. Você pode encontrar essa configuração na aba Build Settings:

   • Baixe a fonte do engine Godot na página Godot GitHub.

   • Execute o SCons para gerar os cabeçalhos. Você pode aprender o processo lendo Compilando para iOS. Você não precisa esperar que a compilação termine para prosseguir, pois os cabeçalhos são gerados antes de o motor começar a compilar.

   • Você deve usar os mesmos arquivos de cabeçalho para os plugins do iOS e para o modelo de exportação do iOS.

3. Na aba Build Settings, especifique as flags de compilação para sua biblioteca estática em OTHER_CFLAGS. As mais importantes são -fcxx-modules, -fmodules e -DDEBUG se precisar de suporte a depuração. Outras flags devem ser as mesmas que você usa para compilar o Godot. Por exemplo:

-DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND

4. Adicione a lógica necessária para o seu plugin e compile sua biblioteca para gerar um arquivo .a. Você provavelmente precisará compilar arquivos .a para os alvos debug e release. Dependendo de suas necessidades, escolha um ou ambos. Se você precisar de ambos os arquivos .a (debug e release), seus nomes devem seguir o padrão: [PluginName].[TargetType].a. Você também pode compilar a biblioteca estática com sua configuração SCons.

5. O sistema de plugins do iOS também suporta arquivos .xcframework. Para gerar um, você pode usar um comando como:

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

6. Crie um arquivo de configuração de Plugin iOS do Godot para ajudar o sistema a detectar e carregar seu plugin:

   • A extensão do arquivo de configuração deve ser gdip (ex.: MeuPlugin.gdip).

   • O formato do arquivo de configuração é o seguinte:

   [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"
   

A seção config e os campos são obrigatórios e são definidos da seguinte forma:

• name: nome do plugin

• binary: este deve ser o caminho do arquivo da biblioteca do plugin (a ou xcframework).

  • O caminho do arquivo pode ser relativo (ex.: MeuPlugin.a, MeuPlugin.xcframework), caso em que será relativo ao diretório onde o arquivo gdip está localizado.

  • O caminho do arquivo pode ser absoluto: res://algum_caminho/MeuPlugin.a ou res://algum_caminho/MeuPlugin.xcframework.

  • Caso precise usar uma biblioteca multi-alvo, o nome do arquivo deve ser MeuPlugin.a e os arquivos .a devem ser nomeados como MeuPlugin.release.a e MeuPlugin.debug.a.

  • Caso use bibliotecas xcframework multi-alvo, o nome do arquivo na configuração deve ser MeuPlugin.xcframework. Os arquivos .xcframework devem ser nomeados como MeuPlugin.release.xcframework and MeuPlugin.debug.xcframework.

As seções dependencies e plist são opcionais e definidas da seguinte forma:

• dependências:

  • linked: contém uma lista de frameworks iOS com os quais a aplicação iOS deve ser vinculada.

  • embedded: contém uma lista de frameworks ou bibliotecas iOS que devem ser vinculadas e incorporadas à aplicação iOS resultante.

  • system: contém uma lista de frameworks de sistema do iOS que são necessários para o plugin.

  • capabilities: contém uma lista de capacidades iOS necessárias para o plugin. Uma lista de capacidades disponíveis pode ser encontrada na página de documentação Apple UIRequiredDeviceCapabilities.

  • files: contém uma lista de arquivos que devem ser copiados na exportação. Isso é útil para arquivos de dados ou imagens.

  • linker_flags: contém uma lista de sinalizadores de vinculador (linker flags) para adicionar ao projeto Xcode ao exportar o plugin.

• plist: deve conter chaves e valores que precisam estar presentes no arquivo Info.plist.

  • Cada linha deve seguir o padrão: NomeDaChave:TipoDaChave=ValorDaChave

  • Os valores suportados para TipoDaChave são string, integer, boolean, raw, string_input

  • Se nenhum tipo for usado (ex.: NomeDaChave="ValorDaChave"), o tipo string será utilizado.

  • Se o tipo raw for usado, o valor da chave correspondente será armazenado no Info.plist exatamente como está.

  • Se o tipo string_input for usado, você poderá modificar o valor na janela de Exportação.