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

Creare estensioni per iOS

Questa pagina spiega cosa possono fare i plugin di iOS, come utilizzare un plugin esistente e i passaggi per programmarne uno nuovo.

I plugin di iOS consentono di utilizzare librerie di terze parti e supportano funzionalità specifiche di iOS come acquisti in-app, integrazione con GameCenter, supporto ARKit e altro ancora.

Caricare e utilizzare un'estensione esistente

Un plugin iOS richiede un file di configurazione .gdip, un file binario che può essere una libreria statica .a o .xcframework contenente librerie statiche .a, ed eventualmente altre dipendenze. Per utilizzarlo, è necessario:

Copiare i file del plugin nella cartella res://ios/plugins del progetto Godot. È anche possibile raggruppare i file in una sottocartella, ad esempio res://ios/plugins/my_plugin.
L'editor Godot rileva e importa automaticamente i file .gdip dentro res://ios/plugins e le sue sottocartelle.
È possibile trovare e attivare i plugin rilevati andando su Progetto -> Esporta... -> iOS e, nella scheda Opzioni, scorrendo fino alla sezione Plugin.

../../../_images/ios_export_preset_plugins_section.png

Quando un plugin è attivo, è possibile accedervi nel codice tramite Engine.get_singleton():

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

Nota

I file del plugin devono trovarsi nella cartella res://ios/plugins/ o in una sua sottocartella, altrimenti l'editor Godot non li rileverà automaticamente.

Creare un'estensione iOS

In sostanza, un plugin Godot per iOS è una libreria iOS (file di archivio .a o .xcframework contenente librerie statiche) con i seguenti requisiti:

La libreria deve avere una dipendenza dagli header del motore Godot.
La libreria deve essere dotata di un file di configurazione .gdip.

Un plugin per iOS può avere le stesse funzionalità di un modulo Godot, ma offre maggiore flessibilità e non richiede di ricompilare il motore.

Ecco i passaggi per cominciare lo sviluppo di un plugin. Consigliamo di utilizzare Xcode come ambiente di sviluppo.

Vedi anche

Le estensioni iOS di Godot.

Il modello del plugin Godot per iOS fornisce tutto il codice iniziale necessario per cominciare con il plugin per iOS.

Per compilare un plugin iOS:

Creare una libreria statica Objective-C per il plugin all'interno di Xcode.
Aggiungere i file header del motore Godot come dipendenza per la libreria del plugin in HEADER_SEARCH_PATHS. È possibile trovare l'impostazione nella scheda Build Settings:
- Scarica il codice sorgente del motore Godot dalla pagina GitHub di Godot.
- Eseguire SCons per generare gli header. È possibile imparare il procedimento leggendo Compilare per iOS. Non è necessario attendere il completamento della compilazione per continuare, poiché gli header vengono generati prima che il motore inizi la compilazione.
- Si dovrebbero usare gli stessi file header per i plugin iOS e per il modello di esportazione iOS.
Nella scheda Build Settings, specificare i flag di compilazione per la propria libreria statica in OTHER_CFLAGS. I più importanti sono -fcxx-modules, -fmodules e -DDEBUG se c'è bisogno di supporto per il debug. Gli altri flag dovrebbero essere gli stessi che si usano per compilare Godot. Per esempio:

-DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND

Aggiungere la logica richiesta per il plugin e compilare la libreria per generare un file .a. Probabilmente sarà necessario compilare il file .a per le destinazioni debug o release. A seconda delle proprie esigenze, sceglierne uno o entrambi. Se servono entrambi i file .a di debug e di rilascio, il loro nome dovrebbe corrispondere al seguente schema: [NomePlugin].[TipoDestinazione].a. È possibile anche compilare la libreria statica con la propria configurazione SCons.
Il sistema di plugin iOS supporta anche i file .xcframework. Per generarne uno, si può usare un comando come:

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

Creare un file di configurazione del plugin Godot iOS per aiutare il sistema a rilevare e caricare il proprio plugin:

L'estensione del file di configurazione deve essere gdip (ad esempio: MyPlugin.gdip).
Il file di configurazione è quanto segue:

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

La sezione e i campi config sono obbligatori e definiti come segue:

name: nome del plugin

binary: questo dovrebbe essere il percorso del file della libreria del plugin (a o xcframework).

Il percorso può essere relativo (ad esempio: MyPlugin.a, MyPlugin.xcframework), nel qual caso è relativo alla cartella in cui si trova il file gdip.

Il percorso può anche essere assoluto: res://some_path/MyPlugin.a o res://some_path/MyPlugin.xcframework.

Nel caso in cui sia necessario utilizzare una libreria multitarget, il nome del file dovrebbe essere MyPlugin.a e i file .a dovrebbero essere denominati MyPlugin.release.a e MyPlugin.debug.a.

Nel caso in cui si utilizzino librerie xcframework multitarget, il loro nome file nella configurazione dovrebbe essere MyPlugin.xcframework. I file .xcframework dovrebbero essere denominati MyPlugin.release.xcframework e MyPlugin.debug.xcframework.

Le sezioni dependencies e plist sono facoltative e definite come segue:

dependencies:

linked: contiene un elenco di framework iOS a cui l'applicazione iOS deve essere collegata.

embedded: contiene un elenco di framework o librerie iOS che devono essere collegati e incorporati nell'applicazione iOS risultante.

system: contiene un elenco di framework di sistema iOS necessari per il plugin.

capabilities: contiene un elenco di funzionalità iOS necessarie per il plugin. Un elenco delle funzionalità disponibili si può trovare nella pagina di documentazione di Apple per UIRequiredDeviceCapabilities.

files: contiene un elenco di file che devono essere copiati durante l'esportazione. È utile per file di dati o immagini.

linker_flags: contiene un elenco di flag del linker da aggiungere al progetto Xcode durante l'esportazione del plugin.

plist: dovrebbe contenere chiavi e valori che devono essere presenti nel file Info.plist.

Ogni riga deve seguire lo schema: KeyName:KeyType=KeyValue

I valori supportati per KeyType sono string, integer, boolean, raw, string_input

Se nessun tipo è specificato (ad esempio: KeyName="KeyValue"), sarà usato il tipo string.

Se si usa il tipo raw, il valore per la chiave corrispondente sarà memorizzato in Info.plist così com'è.

Se si usa il tipo string_input, sarà possibile modificare il valore nella finestra Esportazione.