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

Tutorial sulla riga di comando

Ad alcuni sviluppatori piace usare ampiamente la riga di comando. Godot è progettato per tenerne conto, quindi ecco i passaggi per lavorare interamente dalla riga di comando. Dato che il motore dipende da quasi nessuna libreria esterna, i tempi di inizializzazione sono piuttosto rapidi, rendendolo adatto a questo flusso di lavoro.

Nota

Su Windows e Linux, è possibile avviare un'eseguibile di Godot in un terminale specificandone il percorso relativo o assoluto.

Su macOS, il processo è diverso perché Godot è contenuto in un pacchetto .app (che è una cartella, non un file). Per avviare un eseguibile di Godot da un terminale su macOS, è necessario cd nella cartella in cui si trova il pacchetto dell'applicazione Godot, quindi eseguire Godot.app/Contents/MacOS/Godot seguito da eventuali argomenti della riga di comando. Se il pacchetto dell'applicazione è stato rinominato da Godot a un altro nome, assicurarsi pertanto di aggiustare questa riga di comando.

Riferimento della riga di comando

Legenda

• Disponibile nelle build dell'editor, nei modelli di esportazione di debug e nei modelli di esportazione di rilascio.

• Disponibile solo nelle build dell'editor e nei modelli di esportazione di debug.

• Disponibile solo nelle build dell'editor, nei modelli di esportazione compilati con disable_path_overrides=false.

• Disponibile solo nelle build dell'editor.

Si noti che gli argomenti della riga di comando sconosciuti non hanno alcun effetto. Il motore non avvertirà quando si utilizza un argomento che non esiste con un determinato tipo di build.

Opzioni generali

Comando	Descrizione
-h, --help	Visualizza l'elenco delle opzioni della riga di comando.
--version	Visualizza la stringa della versione.
-v, --verbose	Usa la modalità stdout verboso.
-q, --quiet	Modalità silenziosa, silenzia i messaggi di stdout. Gli errori sono comunque visualizzati.
--no-header	Non stampare all'avvio l'intestazione contenente la versione del motore e il metodo di rendering.

Opzioni di esecuzione

Comando	Descrizione
--, ++	Separatore per gli argomenti forniti dall'utente. Gli argomenti seguenti non sono utilizzati dal motore, ma si possono leggere da OS.get_cmdline_user_args().
-e, --editor	Avvia l'editor invece di eseguire la scena.
-p, --project-manager	Avvia il Gestore dei progetti, anche se un progetto è rilevato automaticamente.
--recovery-mode	"Avvia l'editor in modalità di recupero, che disabilita le funzionalità che in genere possono causare arresti anomali all'avvio, come script strumento (tool), estensioni dell'editor, componenti aggiuntivi in GDExtension e altri.
--debug-server <uri>	Avvia il server di debug dell'editor (<protocollo>://<host/IP>[:<porta>], ad esempio tcp://127.0.0.1:6007)
--dap-port <port>	Utilizza la porta specificata per il protocollo GDScript Debug Adapter. Intervallo di porte consigliato [1024, 49151].
--lsp-port <porta>	Utilizza la porta specificata per il protocollo GDScript Language Server Protocol. Intervallo di porte consigliato [1024, 49151].
--quit	Termina dopo la prima iterazione.
--quit-after	Termina dopo il numero specificato di iterazioni. Impostare a 0 per disabilitare.
-l, --language <locale>	Usa una localizzazione specifica. <locale> segue il formato language_Script_COUNTRY_VARIANT, dove language_Script_COUNTRY_VARIANT è un codice lingua di 2 o 3 lettere minuscole e il resto è facoltativo. Consultare Codici di localizzazione per più dettagli.
--path <directory>	Percorso a un progetto (<directory> deve contenere un file "project.godot").
--scene <path>	Percorso o UID di una scena nel progetto che deve essere avviata.
--main-pack <file>	Percorso al file di pacchetto (.pck) da caricare.
--render-thread <mode>	Modalità dei thread di rendering ("unsafe", "safe", "separate"). Consultare Thread Model per più dettagli.
--remote-fs <address>	File system remoto (indirizzo <host/IP>[:<porta>]).
--remote-fs-password <password>	Password per il file system remoto.
--audio-driver <driver>	Driver audio. Utilizzare il comando --help per visualizzare l'elenco dei driver disponibili.
--display-driver <driver>	Driver video (e driver di rendering). Utilizzare il comando --help per visualizzare l'elenco dei driver disponibili.
--audio-output-latency <ms>	Sovrascrive la latenza dell'uscita audio in millisecondi (il valore predefinito è 15 ms). Valori inferiori rendono la riproduzione audio più reattiva, ma aumentano l'utilizzo della CPU e possono causare audio scoppiettante se la CPU non riesce a tenere il passo.
--rendering-method <renderer>	Nome del renderer. I valori validi sono forward_plus, mobile e gl_compatibility. Richiede il supporto del driver.
--rendering-driver <driver>	Driver di rendering (dipende dal driver video). Utilizzare il comando --help per visualizzare l'elenco dei driver disponibili.
--gpu-index <device_index>	Utilizza una GPU specifica (disponibile solo nei renderer Forward+/Mobile; eseguire con --verbose per ottenere l'elenco dei dispositivi disponibili).
--text-driver <driver>	Driver di testo (Font, BiDi, formazione).
--tablet-driver <driver>	Driver per input da tavoletta grafica.
--headless	Abilita la modalità headless (--display-driver headless --audio-driver Dummy). Utile per i server e con --script.
--log-file	Scrive il log di output/errori nel percorso specificato anziché nella posizione predefinita definita dal progetto. Il percorso <file> deve essere assoluto o relativo alla cartella del progetto.
--write-movie <file>	Esegue il motore in modo che sia registrato un filmato (solitamente con estensione .avi o .png). --fixed-fps è forzato quando abilitato, ma si può utilizzare per cambiare gli FPS del filmato. --disable-vsync può velocizzare la registrazione del filmato ma rende più difficile l'interazione. --quit-after si può utilizzare per specificare il numero di fotogrammi da registrare.

Opzioni di visualizzazione

Comando	Descrizione
-f, --fullscreen	Richiede la modalità a schermo intero.
-m, --maximized	Richiede una finestra massimizzata.
-w, --windowed	Richiede la modalità finestra.
-t, --always-on-top	Richiede una finestra sempre in primo piano.
--resolution <W>x<H>	Richiede una risoluzione per la finestra.
--position <X>,<Y>	Richiede una posizione per la finestra.
--screen <N>	Richiede uno schermo per la finestra.
--single-window	Utilizza una singola finestra (nessuna sotto-finestra separata).
--xr-mode <mode>	Seleziona la modalità XR ("default", "off", "on").
--wid <id_finestra>	Richiede una finestra da appartenere come figlia.
--accessibility <modalità>	Seleziona la modalità di accessibilità ["auto" (quando il lettore dello schermo è in esecuzione, predefinito), "always", "disabled"].

Opzioni di debug

Comando	Descrizione
-d, --debug	Debug (debugger stdout locale).
-b, --breakpoints	Lista dei punti di interruzione come coppie separate da virgole sorgente::riga, senza spazi (utilizzare invece %20).
--ignore-error-breaks	Se il debugger è connesso, impedisce di inviare i punti d'interruzione di errore.
--profiling	Abilita la profilazione nel debugger di script.
--gpu-profile	Mostra un profilo di GPU delle attività che hanno richiesto più tempo durante il rendering dei frame.
--gpu-validation	Abilita i validation layers dell'API grafica per il debug.
--gpu-abort	Interrompe in caso di errori di GPU (solitamente errori di livelli di convalida), potrebbe aiutare a individuare il problema se il sistema si blocca.
--generate-spirv-debug-info	Genera informazioni di debug SPIR-V. Ciò consente il debug degli shader a livello sorgente con RenderDoc.
--extra-gpu-memory-tracking	Abilita un ulteriore tracciamento di memoria (consultare il riferimento alla classe per RenderingDevice.get_driver_and_device_memory_report() e i metodi collegati). Attualmente implementato solo per Vulkan. Abilitare questa funzionalità potrebbe causare arresti anomali su alcuni sistemi a causa di driver difettosi o bug nel Vulkan Loader. Consultare https://github.com/godotengine/godot/issues/95967
--accurate-breadcrumbs	Forza barriere tra i breadcrumb. Utile per restringere la portata di un comando che causa il riavvio della GPU. Attualmente implementato solo per Vulkan.
--remote-debug <uri>	Debug remoto (<protocollo>://<host/IP>[:<porta>], ad esempio tcp://127.0.0.1:6007).
--single-threaded-scene	L'albero di scene è eseguito in modalità a singolo thread. I gruppi di thread secondari sono disabilitati e sono eseguiti sul thread principale.
--debug-collisions	Mostra le forme di collisione durante l'esecuzione della scena.
--debug-paths	Mostra le linee dei percorsi durante l'esecuzione della scena.
--debug-navigation	Mostra i poligoni di navigazione durante l'esecuzione della scena.
--debug-avoidance	Mostra le visuali di debug per l'evasione di navigazione durante l'esecuzione della scena.
--debug-stringnames	Stampa tutte le allocazioni di StringName su stdout quando il motore si chiude.
--debug-canvas-item-redraw	Mostra un rettangolo ogni volta che un elemento canvas richiede un ridisegno (utile per risolvere i problemi della modalità basso consumo del processore).
--max-fps <fps>	Imposta un numero massimo di frame al secondo renderizzati (si può utilizzare per limitare il consumo energetico). Un valore pari a 0 risulta in una frequenza dei frame illimitata.
--frame-delay <ms>	Simula un carico elevato sulla CPU (ritarda ogni frame di <ms> millisecondi). Non usare un limitatore di FPS; usa invece --max-fps.
--time-scale <scale>	Forza la scala del tempo (più veloce con valori più alti, 1,0 per la velocità normale).
--disable-vsync	Forza la disattivazione della sincronizzazione verticale, anche se abilitata nelle impostazioni del progetto. Non sovrascrive l'applicazione della sincronizzazione verticale a livello del driver.
--disable-render-loop	Disabilita il ciclo di rendering in modo che il rendering avvenga solo quando chiamato esplicitamente da codice.
--disable-crash-handler	Disabilita il gestore dei crash quando supportato dal codice della piattaforma.
--fixed-fps <fps>	Forza un numero fisso di frame al secondo. Questa impostazione disabilita la sincronizzazione in tempo reale.
--delta-smoothing <enable>	Abilita o disabilita il livellamento delta dei frame ("enable", "disable").
--print-fps	Stampa i frame al secondo sullo stdout.
--editor-pseudolocalization	Abilita la pseudolocalizzazione per l'editor e il gestore dei progetti.

Strumenti autonomi

Comando	Descrizione
-s, --script <script>	Esegue uno script. <script> deve essere un percorso di risorsa relativo al progetto (myscript.gd sarà interpretato come res://myscript.gd) o un percorso assoluto del file system (ad esempio, su Windows: C:/tmp/myscript.gd).
--main-loop <nome_loop_principale>	Esegue un MainLoop specificato dal nome della sua classe globale.
--check-only	Analizza solamente gli errori e termina (da usare con --script).
--import	Avvia l'editor, attende che tutte le risorse siano importate, quindi esce. Implica --editor e --quit.
--export-release <preset> <path>	Esporta il progetto in modalità di rilascio utilizzando la preimpostazione fornita e il percorso di output specificati. Il nome della preimpostazione deve corrispondere a uno definito in "export_presets.cfg". Il percorso <path> deve essere assoluto o relativo alla cartella del progetto e includere il nome dell'eseguibile (ad esempio, "builds/game.exe"). La cartella di destinazione deve esistere.
--export-debug <preset> <path>	Come --export-release, ma usa il modello di debug. Implica --import.
--export-pack <preset> <path>	Come --export-release, ma esporta solo il pacchetto di gioco per la preimpostazione specificata. L'estensione del percorso <path> determina se sarà in formato PCK o ZIP. Implica --import.
--export-patch <preset> <percorso>	Esporta il pacchetto solo con i file cambiati. Consultare la descrizione di --export-pack per altre considerazioni.
--patches <percorsi>	Elenco delle patch da utilizzare con --export-patch. L'elenco è separato da virgole.
--install-android-build-template	Installa il modello di compilazione Android. Utilizzato insieme a --export-release o --export-debug.
--convert-3to4 [<max_file_kb>] [<max_line_size>]	Converte il progetto da Godot 3.x a Godot 4.x.
--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]	Mostra quali elementi saranno rinominati durante la conversione di un progetto da Godot 3.x a Godot 4.x.
--doctool [<path>]	Estrae il riferimento dell'API del motore nel percorso <path> in formato XML, unendolo se vengono trovati file esistenti.
--no-docbase	Non consente l'estrazione dei tipi di base (utilizzato con --doctool).
--gdextension-docs	Anziché estrarre l'API del motore, genera un riferimento dell'API da tutte le GDExtension caricate nel progetto attuale (utilizzato con --doctool).
--gdscript-docs <path>	Anziché estrarre l'API del motore, genera un riferimento dell'API dalla documentazione inclusa nei file GDScript che si trovano in <path> (utilizzato con --doctool).
--build-solutions	Costruisce le soluzioni di scripting (ad esempio per progetti in C#). Implica --editor e richiede un progetto valido da modificare.
--dump-gdextension-interface	Genera il file di intestazione GDExtension "gdextension_interface.h" nella cartella attuale. Questo file è il file di base necessario per implementare una GDExtension.
--dump-gdextension-interface-json	Genera un'estrazione in JSON dell'API di Godot per l'interfaccia di GDExtension denominato "gdextension_interface.json" nella cartella attuale.
--dump-extension-api	Genera un'estrazione in JSON dell'API di Godot per i binding di GDExtension denominato "extension_api.json" nella cartella attuale.
--dump-extension-api-with-docs	Genera un'estrazione in JSON dell'API di Godot come l'opzione precedente, ma includendo la documentazione.
--validate-extension-api <path>	Convalida un file API di estensione estratto (con l'opzione sopra) da una versione precedente del motore per garantire la compatibilità dell'API. Se vengono rilevate incompatibilità o errori, il codice restituito sarà diverso da zero.
--benchmark	Esegue un benchmark del tempo di esecuzione e lo visualizza nella console.
--benchmark-file <path>	Esegue un benchmark del tempo di esecuzione e lo salva in un file specificato in formato JSON. Il percorso deve essere assoluto.
--test [--help]	Esegue test unitari (richiede compilare il motore con tests=yes). Usare --test --help per maggiori informazioni.

Percorso

Si consiglia di inserire l'eseguibile dell'editor Godot nella variabile d'ambiente PATH, in modo che si possa eseguire facilmente da qualsiasi punto digitando godot. Su Linux, è possibile farlo inserendo l'eseguibile di Godot in /usr/local/bin e assicurandosi che si chiami godot (con distinzione tra maiuscole e minuscole).

Per farlo facilmente su Windows o macOS, è possibile installare Godot usando Scoop (su Windows) o Homebrew (su macOS). Ciò renderà automaticamente disponibile la copia di Godot installata nella variabile d'ambiente PATH:

WindowsmacOS

# Add "Extras" bucket
scoop bucket add extras

# Standard editor:
scoop install godot

# Editor with C# support (will be available as `godot-mono` in `PATH`):
scoop install godot-mono

Impostare il percorso del progetto

A seconda di dove si trova l'eseguibile Godot e cartella di lavoro attuale, potrebbe essere necessario impostare il percorso del progetto affinché qualunque dei seguenti comandi funzioni correttamente.

Quando si esegue l'editor, è possibile fare ciò specificando il percorso al file project.godot del progetto come primo argomento, in questo modo:

godot path_to_your_project/project.godot [other] [commands] [and] [args]

Per tutti i comandi, è possibile fare ciò utilizzando l'argomento --path:

godot --path path_to_your_project [other] [commands] [and] [args]

Ad esempio, il comando completo per esportare il gioco (come spiegato di seguito) potrebbe essere qualcosa del genere:

godot --headless --path path_to_your_project --export-release my_export_preset_name game.exe

Quando si inizia da una sottocartella del progetto, utilizzare l'argomento --upwards affinché Godot trovi automaticamente il file project.godot ricercando ricorsivamente nelle cartelle padre.

Ad esempio, l'esecuzione di una scena (come spiegato di seguito) annidata in una sottocartella, quando la cartella di lavoro si trova nello stesso percorso, potrebbe essere qualcosa del genere:

godot --upwards nested_scene.tscn

Creare un progetto

Per creare un progetto dalla riga di comando, navigare nella shell nel punto desiderato e creare un file project.godot.

mkdir newgame
cd newgame
touch project.godot

Ora è possibile aprire il progetto con Godot.

Eseguire l'editor

L'editor si avvia eseguendo Godot con il flag -e. È necessario effettuare questa operazione dalla cartella del progetto o impostando il percorso del progetto come spiegato in precedenza, altrimenti il comando è ignorato e appare il Gestore dei progetti.

godot -e

Quando si passa il percorso completo al file project.godot, il flag -e si può omettere.

Se una scena è stata creata e salvata, è possibile modificarla in seguito eseguendo lo stesso codice con quella scena come argomento.

godot -e scene.tscn

Eliminare una scena

Godot rispetta il file system e non creerà file aggiuntivi di metadati. Usa rm per cancellare un file di scena. Assicurarsi che non vi sia alcun riferimento a quella scena. Altrimenti, verrà generato un errore all'apertura del progetto.

rm scene.tscn

Eseguire il gioco

Per eseguire il gioco, eseguire Godot all'interno della cartella del progetto o con il percorso del progetto come spiegato in precedenza.

godot

Si noti che passando il file project.godot sarà sempre eseguito l'editor anziché il gioco.

Quando è necessario testare una scena specifica, passare la scena alla riga di comando.

godot scene.tscn

Debugging

Rilevare gli errori nella riga di comando può essere un compito difficile, perché scorrono rapidamente. Per questo, è fornito un debugger da riga di comando aggiungendo -d. Funziona sia per l'esecuzione del gioco sia per una singola scena.

godot -d

godot -d scene.tscn

Esportazione

Anche l'esportazione del progetto dalla riga di comando è supportata. Questa funzionalità è particolarmente utile per le configurazioni di integrazione continua.

Nota

L'utilizzo dell'argomento da riga di comando --headless è obbligatorio sulle piattaforme che non hanno accesso alla GPU (come nell'integrazione continua). Sulle piattaforme con accesso alla GPU, --headless impedisce che una finestra sia generata durante l'esportazione del progetto.

# `godot` must be a Godot editor binary, not an export template.
# Also, export templates must be installed for the editor
# (or a valid custom export template must be defined in the export preset).
godot --headless --export-release "Linux/X11" /var/builds/project
godot --headless --export-release Android /var/builds/project.apk

Il nome della preimpostazione deve corrispondere al nome di una preimpostazione di esportazione definita nel file export_presets.cfg del progetto. Se il nome della preimpostazione contiene spazi o caratteri speciali (ad esempio "Windows Desktop"), deve essere racchiuso tra virgolette.

Per esportare una versione di debug del gioco, utilizzare l'opzione --export-debug invece di --export-release. I parametri e l'utilizzo sono gli stessi.

Per esportare solo un file PCK, utilizzare l'opzione --export-pack seguita dal nome della preimpostazione e dal percorso di output, con l'estensione del file, invece di --export-release o --export-debug. L'estensione del percorso di output determina il formato del pacchetto, PCK o ZIP.

Avvertimento

Quando si specifica un percorso relativo come percorso per --export-release, --export-debug o --export-pack, il percorso sarà relativo alla cartella contenente il file project.godot, non relativo alla cartella di lavoro attuale.

Eseguire uno script

È possibile eseguire uno script .gd dalla riga di comando. Questa funzionalità è particolarmente utile nei progetti grandi, ad esempio per convertire in massa le risorse o per l'importazione/esportazione personalizzata.

Lo script deve ereditare da SceneTree o MainLoop.

Ecco un semplice esempio sayhello.gd che ne mostra il funzionamento:

#!/usr/bin/env -S godot -s
extends SceneTree

func _init():
    print("Hello!")
    quit()

E come eseguirlo:

# Prints "Hello!" to standard output.
godot -s sayhello.gd

Se nessun file project.godot esiste nel percorso, si assume che il percorso attuale sia la cartella di lavoro attuale (a meno che --path non sia specificato).

Il percorso dello script sarà interpretato come un percorso di risorsa relativo al progetto, in questo caso res://sayhello.gd. È anche possibile utilizzare un percorso assoluto del file system, utile se lo script si trova al di fuori della cartella del progetto.

La prima riga di sayhello.gd qui sopra è comunemente nota come shebang. Se l'eseguibile di Godot si trova in PATH come godot, sarà possibile eseguire lo script come segue nelle distribuzioni Linux moderne, così come su macOS:

# Mark script as executable.
chmod +x sayhello.gd
# Prints "Hello!" to standard output.
./sayhello.gd

Se quanto precede non funziona nell'attuale versione di Linux o macOS, si può sempre far eseguire Godot direttamente dallo shebang, da dove si trova, come segue:

#!/usr/bin/godot -s