Tutorial sulla riga di comando

Some developers like using the command line extensively. Godot is designed to be friendly to them, so here are the steps for working entirely from the command line. Given the engine relies on almost no external libraries, initialization times are pretty fast, making it suitable for this workflow.

Nota

On Windows and Linux, you can run a Godot binary in a terminal by specifying its relative or absolute path.

On macOS, the process is different due to Godot being contained within a .app bundle (which is a folder, not a file). To run a Godot binary from a terminal on macOS, you have to cd to the folder where the Godot application bundle is located, then run Godot.app/Contents/MacOS/Godot followed by any command line arguments. If you've renamed the application bundle from Godot to another name, make sure to edit this command line accordingly.

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.

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	Do not print engine version and rendering method header on startup.

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	"Start the editor in recovery mode, which disables features that can typically cause startup crashes, such as tool scripts, editor plugins, GDExtension addons, and others.
--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>	Use the specified port for the GDScript Debug Adapter Protocol. Recommended port range [1024, 49151].
--lsp-port <porta>	Use the specified port for the GDScript Language Server Protocol. Recommended port range [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>	Path or UID of a scene in the project that should be started.
-u, --upwards	Scansiona le cartelle verso l'alto per trovare il file 'project.godot'.
--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>	Override audio output latency in milliseconds (default is 15 ms). Lower values make sound playback more reactive but increase CPU usage, and may result in audio cracking if the CPU can't keep up
--rendering-method <renderer>	Nome del renderer. Richiede il supporto dal 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 (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	Write output/error log to the specified path instead of the default location defined by the project. <file> path should be absolute or relative to the project directory.
--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>	Request parented to window.
--accessibility <modalità>	Select accessibility mode ['auto' (when screen reader is running, default), '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	If debugger is connected, prevents sending error breakpoints.
--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	Abort on GPU errors (usually validation layer errors), may help see the problem if your system freezes.
--generate-spirv-debug-info	Generate SPIR-V debug information. This allows source-level shader debugging with RenderDoc.
--extra-gpu-memory-tracking	Enables additional memory tracking (see class reference for RenderingDevice.get_driver_and_device_memory_report() and linked methods). Currently only implemented for Vulkan. Enabling this feature may cause crashes on some systems due to buggy drivers or bugs in the Vulkan Loader. See https://github.com/godotengine/godot/issues/95967
--accurate-breadcrumbs	Force barriers between breadcrumbs. Useful for narrowing down a command causing GPU resets. Currently only implemented for 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	Display a rectangle each time a canvas item requests a redraw (useful to troubleshoot low processor mode).
--max-fps <fps>	Set a maximum number of frames per second rendered (can be used to limit power usage). A value of 0 results in unlimited framerate.
--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 risorse 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>	Run a MainLoop specified by its global class name.
--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>	Export the project in release mode using the given preset and output path. The preset name should match one defined in 'export_presets.cfg'. <path> should be absolute or relative to the project directory, and include the filename for the binary (e.g. 'builds/game.exe'). The target directory must exist.
--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>	Export pack with changed files only. See --export-pack description for other considerations.
--patches <percorsi>	List of patches to use with --export-patch. The list is comma-separated.
--install-android-build-template	Install the Android build template. Used in conjunction with --export-release or --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).
--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 "gdnative_interface.h" nella cartella attuale. Questo file è il file di base necessario per implementare una GDExtension.
--dump-extension-api	Genera un'estrazione in JSON dell'API di Godot per i binding di GDExtension denominato "extension_api.json" nella cartella attuale.
--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]	Run unit tests. Use --test --help for more information.

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 gruppi i contenuti 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