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

Port su piattaforme personalizzate

Simile a Moduli personalizzati in C++, l'architettura multipiattaforma di Godot è progettata in modo da consentire la creazione di port di piattaforma senza modificare alcun codice sorgente esistente.

Un esempio di port di piattaforma personalizzato distribuito indipendentemente dal motore è FRT, destinato ai computer a scheda singola. Si noti che questo port di piattaforma è attualmente destinato a Godot 3.x; pertanto, non utilizza l'astrazione DisplayServer introdotta in Godot 4.

Alcuni motivi per cui è consigliabile creare port personalizzati di piattaforma potrebbero essere:

• Serve portare il proprio gioco su console (consultare anche il sito di Godot sul supporto per console), ma si desidera scrivere personalmente il lato piattaforma. Questo è un processo lungo e arduo, poiché richiede la firma di accordi di riservatezza con i produttori di console, ma consente di avere il pieno controllo sul processo di porting sulla console.

• Serve portare Godot su una piattaforma esotica che al momento non è supportata.

Se ci sono domande sulla creazione di un port personalizzato per una piattaforma, non esitare a chiedere nel canale #platforms della Godot Contributors Chat.

Nota

Godot è un motore grafico moderno con requisiti moderni. Anche se si intende eseguire solo semplici progetti 2D sulla piattaforma di destinazione, richiede comunque una quantità di memoria che lo rende inadatto all'esecuzione sulla maggior parte delle console retrò. Per avere un riferimento, in Godot 4, un progetto vuoto senza nulla di visibile richiede circa 100 MB di RAM per essere eseguito su Linux (50 MB in modalità headless).

Se si desidera eseguire Godot su piattaforme con forti limitazioni di memoria, le versioni precedenti di Godot richiedono meno memoria. Il processo di porting è simile, con l'eccezione che DisplayServer non è separato dal singleton OS.

Port su piattaforme ufficiali

I port per le piattaforme ufficiali si possono usare come riferimento durante la creazione di un port personalizzato per una piattaforma:

• Windows

• macOS

• Linux/*BSD

• Android

• iOS

• Web

Sebbene il codice di piattaforma sia solitamente autosufficiente, esistono delle eccezioni a questa regola. Ad esempio, i driver audio condivisi su più piattaforme e i driver di rendering si trovano nella cartella drivers/ del codice sorgente di Godot.

Creare un port su piattaforma personalizzata

Creare un port personalizzata per una piattaforma è un'impresa ardua che richiede una conoscenza approfondita degli SDK della piattaforma. La quantità di lavoro necessaria varia a seconda delle funzionalità richieste:

Funzionalità richieste di un port per una piattaforma

Come minimo, un port per una piattaforma deve implementare i metodi del singleton OS per essere compilabile e utilizzabile per operazioni headless. All'interno della cartella della piattaforma deve essere presente anche un'immagine vettoriale logo.svg (32×32). Questo logo è visualizzato nella finestra di dialogo Esporta per ogni preimpostazione di esportazione destinato alla piattaforma in questione.

Vedere questa implementazione per la piattaforma Linux/*BSD come esempio. Vedere anche l'intestazione del singleton OS come riferimento.

Nota

If your target platform is UNIX-like, consider inheriting from the OS_Unix class to get much of the work done automatically.

Se la piattaforma non è di tipo UNIX, potresti usare il port per Windows come riferimento.

file detect.py

È necessario creare un file detect.py all'interno della cartella della piattaforma con tutti i metodi implementati. Questo file è necessario affinché SCons rilevi la piattaforma come opzione valida per la compilazione. Vedere il file detect.py per la piattaforma Linux/*BSD come esempio.

Tutti i metodi devono essere implementati all'interno di detect.py come segue:

• is_active(): può servire per disabilitare temporaneamente la compilazione per una piattaforma. Generalmente, dovrebbe sempre restituire True.

• get_name(): restituisce il nome della piattaforma visibile all'utente come stringa.

• can_build(): restituisce True se il sistema host è in grado di compilare per la piattaforma di destinazione, altrimenti False . Non inserire verifiche lente qui, poiché questo viene interrogato quando l'utente richiede l'elenco delle piattaforme. Utilizzare invece configure() per le verifiche approfondite di dipendenza.

• get_opts(): restituisce l'elenco delle opzioni di build SCons che l'utente può definire per questa piattaforma.

• get_flags(): restituisce l'elenco dei flag SCons sovrascritti per questa piattaforma.

• configure(): esegue la configurazione della build, ad esempio selezionando le opzioni del compilatore in base alle opzioni SCons scelte.

Funzionalità opzionali di un port per una piattaforma

In pratica, il funzionamento headless non è sufficiente se si desidera visualizzare qualsiasi cosa sullo schermo e gestire i dispositivi di input. Potrebbe essere necessario anche un output audio per la maggior parte dei giochi.

Alcuni link in questo elenco puntano all'implementazione della piattaforma Linux/*BSD come riferimento.

• Uno o più DisplayServer, con i metodi di windowing implementati. DisplayServer include anche funzionalità come il supporto per mouse, touchscreen e driver per tablet (per input tramite penna). Vedere l'header del singleton DisplayServer come riferimento.

  • Per le piattaforme che non offrono il supporto completo per il windowing (o se non è rilevante per il port che si sta realizzando), la maggior parte delle funzioni di windowing si può lasciare per lo più non implementata. Queste funzioni si possono creare solo per verificare se l'ID della finestra è MAIN_WINDOW_ID e operazioni specifiche come il ridimensionamento si possono legare alla risoluzione dello schermo della piattaforma (se pertinente). Qualsiasi tentativo di creare o manipolare altri ID di finestra può essere rifiutato.

• Se la piattaforma di destinazione supporta le API grafiche in questione: Contesto di rendering per Vulkan, Direct3D 12 OpenGL 3.3 o OpenGL ES 3.0.

• Gestori di input per tastiera e controller.

• Uno o più driver audio <https://github.com/godotengine/godot/blob/master/drivers/pulseaudio/audio_driver_pulseaudio.cpp>`__. Il driver audio si può posizionare nella cartella platform/ (questa operazione è necessaria per le piattaforme Android e Web) oppure nella cartella drivers/ se più piattaforme utilizzano questo driver audio. Vedere l'header del singleton AudioServer come riferimento.

• Gestore di crash, per stampare i backtrace dei crash quando il gioco si blocca. Questo rende più facile risolvere problemi sulle piattaforme in cui i log non sono facilmente accessibili.

• Driver di sintesi vocale (per accessibilità).

• Gestore di esportazione (per l'esportazione dall'editor, incluso Distribuzione con un clic). Non necessario se si intende esportare solo un PCK dall'editor, quindi eseguire direttamente il binario del modello di esportazione rinominandolo in modo che corrisponda al file PCK. Vedere l'header di EditorExportPlatform come riferimento. run_icon.svg (16×16) dovrebbe essere presente nella cartella platform se Distribuzione con un clic è implementato per la piattaforma di destinazione. Questa icona è visualizzata in alto all'editor quando la distribuzione con un clic è configurata per la piattaforma di destinazione.

Se la piattaforma di destinazione non supporta l'esecuzione di Vulkan, Direct3D 12, OpenGL 3.3 o OpenGL ES 3.0, ci sono due opzioni:

• Utilizzare una libreria in fase di esecuzione per tradurre le chiamate di Vulkan o OpenGL in un'altra API grafica. Ad esempio, MoltenVK è utilizzato su macOS per tradurre Vulkan in Metal in fase di esecuzione.

• Creare un nuovo motore di rendering da zero. È un'impresa impegnativa, soprattutto se si desidera supportare sia il rendering 2D sia quello 3D con funzionalità avanzate.

Distribuire un port personalizzato per una piattaforma

Pericolo

Prima di distribuire un port personalizzato per una piattaforma, assicurarsi di avere l'autorizzazione a distribuire tutto il codice a cui è collegato. Gli SDK per console sono in genere coperti da NDA, che ne impediscono la ridistribuzione al pubblico.

I port per una piattaforma sono progettati per essere il più autonomi possibile. La maggior parte del codice può essere conservata in un'unica cartella situata in platform/. Come Moduli personalizzati in C++, il che consente di semplificare il processo di compilazione rendendo possibile usare git clone su una cartella di piattaforma all'interno della cartella platform/ all'interno di un clone del repository di Godot, quindi eseguire scons platform=<name>. Non sono necessari altri passaggi per la compilazione, a meno che non sia necessario installare prima le dipendenze di terze parti specifiche della piattaforma.

Tuttavia, quando è necessario un driver di rendering personalizzato, è necessario aggiungere un'altra cartella in drivers/. In questo caso, il port per la piattaforma può essere distribuito come fork del repository do Godot o come una raccolta di diverse cartelle che si possono aggiungere tramite un clone del repository Git di Godot.