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

Tutoriel de ligne de commande

Certains développeurs aiment beaucoup utiliser la ligne de commande. Godot est conçu pour leur être agréable, alors voici les étapes pour travailler entièrement à partir de la ligne de commande. Étant donné que le moteur ne nécessite que peu ou pas de bibliothèques externes, les temps d’initialisation sont assez rapides, ce qui le rend adapté à cette méthode de travail.

Note

Sur Windows et Linux, vous pouvez executer un binaire Godot dans un terminal en spécifiant son chemin relatif ou absolu.

Sur macOS, le processus est différent parce que Godot est intégré dans un paquet .app (qui est un répertoire et pas un fichier). Pour exécuter un binaire Godot depuis un terminal macOS, vous devez cd dans le répertoire du paquet et puis exécuter Godot.app/Contents/MacOS/Godot suivi par les arguments de ligne de commande. Si vous avez renommé le paquet Godot en un autre nom, assurez-vous de remplacer Godot dans la commande par ce nom.

Référence de ligne de commande

Légende

• Disponible dans les compilations de l'éditeur, des modèles d'export de débogage et des modèles d'export de publication.

• Disponible uniquement dans les modèles d'export de l'éditeur et de debug.

• Disponible seulement dans les compilations de l'éditeur et les modèle d'export compilés avec disable_path_overrides=false.

• Seulement disponible dans les compilations de l'éditeur.

Notez que les arguments de ligne de commande inconnus n'ont aucun effet. Le moteur ne vous avertira pas si vous utilisez un argument de ligne de commande qui n'existe pas avec un type de compilation donné.

Options générales

Commande	Description
-h, --help	Affiche la liste des options de ligne de commande.
--version	Afficher la chaîne de caractère de version.
-v, --verbose	Utiliser le mode verbeux pour la sortie standard (stdout).
-q, --quiet	Mode silencieux qui désactive les messages de stdout. Les erreurs sont quand même affichées.
--no-header	Ne pas afficher le numéro de version du moteur de jeu ni les entêtes des méthodes de rendu au lancement.

Options d'exécution

Commande	Description
--, ++	Séparateur pour les arguments donnés par l'utilisateur. Les arguments suivants ne sont pas utilisés par le moteur, mais peuvent être lus avec OS.get_cmdline_user_args().
-e, --editor	Démarrer l'éditeur au lieu de lancer la scène.
-p, --project-manager	Démarrer le gestionnaire de projet, même si un projet est autodétecté.
--recovery-mode	Lancer l'éditeur en mode de récupération, cela désactivera les fonctionnalités qui peuvent potentiellement causer des plantages au lancement, tel que les scripts d'outils, les extensions d'éditeurs, les greffons GDExtenstion, et autres.
--debug-server <uri>	Démarrer le serveur de débogage de l'éditeur ( <protocol>://<host/IP>[:<port>], par ex. 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 <port>	Use the specified port for the GDScript Language Server Protocol. Recommended port range [1024, 49151].
--quit	Quitter après la première itération.
--quit-after	Arrête après le nombre donné d'itérations. Définir à 0 pour désactiver.
-l, --language <locale>	Utiliser un langage spécifique. <locale> suit le format language_Script_COUNTRY_VARIANT où la langue est un code de langue 2 ou 3 lettres en minuscule et le reste est optionnel. Voir Code de localisation pour plus de détails.
--path <répertoire>	Chemin vers un projet (<dossier> doit contenir un fichier "project.godot").
--scene <chemin>	Chemin ou UID d'une scène dans le projet qui devrait être démarrée.
--main-pack <file>	Chemin vers le fichier pack (.pck) à charger.
--render-thread <mode>	Render thread mode ("unsafe", "safe", "separate"). See Thread Model for more details.
--remote-fs <address>	Système de fichiers distant (Adresse <hôte/IP>[:<port>]).
--remote-fs-password <mot de passe>	Mot de passe pour le système de fichiers distant.
--audio-driver <driver>	Pilote audio. Utilisez d'abord la commande --help pour afficher la liste des pilotes disponibles.
--display-driver <driver>	Pilote vidéo (et pilote de rendu). Utilisez d'abord la commande --help pour afficher la liste des pilotes disponibles.
--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>	Renderer name. Valid values are forward_plus, mobile, and gl_compatibility. Requires driver support.
--rendering-driver <driver>	Pilote de rendu (dépend du pilote vidéo). Utilisez d'abord la commande --help pour afficher la liste des pilotes disponibles.
--gpu-index <device_index>	Use a specific GPU (only available on the Forward+/Mobile renderers; run with --verbose to get available device list).
--text-driver <driver>	Pilote de texte (Polices, BiDi, mise en forme).
--tablet-driver <driver>	Pilote pour les entrées de tablette graphique.
--headless	Activer le mode sans tête (--display-driver headless --audio-driver Dummy). Utile pour des serveurs et avec -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>	Exécute le moteur pour qu'un film soit enregistré (généralement avec une extension .avi ou .png). --fixed-fps est forcé quand c'est activé, mais peut être utilisé pour changer les FPS du film. --disable-vsync peut accélérer l'enregistrement du film mais rend l'interaction plus difficile. -quit-after peut être utilisé pour spécifier le nombre de trames à enregistrer.

Options d'affichage

Commande	Description
-f, --fullscreen	Demander le mode plein écran.
-m, --maximized	Demander une fenêtre maximisée.
-w, --windowed	Demander le mode fenêtré.
-t, --always-on-top	Demander une fenêtre toujours au premier plan.
--resolution <W>x<H>	Demander la résolution de la fenêtre.
--position <X>,<Y>	Demander la position de la fenêtre.
--screen <N>	Demander l'écran de la fenêtre.
--single-window	Utilisez une seule fenêtre (pas de sous-fenêtres séparées).
--xr-mode <mode>	Sélectionner le mode XR ("default", "off", "on").
--wid <id_fenetre>	Request parented to window.
--accessibility <mode>	Select accessibility mode ['auto" (when screen reader is running, default), "always", "disabled'].

Options de débogage

Commande	Description
-d, --debug	Débogage (débogueur stdout local).
-b, --breakpoints	Liste de points d'arrêt comme paires source::ligne séparées par des virgules, sans espace (utilisez %20 à la place).
--ignore-error-breaks	If debugger is connected, prevents sending error breakpoints.
--profiling	Activer le profilage dans le débogueur de script.
--gpu-profile	Afficher un profil GPU des tâches qui ont pris le plus de temps pendant le rendu des trames.
--gpu-validation	Active l'api graphique validation layers pour du debuggage.
--gpu-abort	Avorter sur les erreurs GPU (généralement les erreurs de couche de validation), peut aider à voir le problème si votre système freeze.
--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>	Débogage à distance (<protocol>://<host/IP>[:<port>], par ex. tcp://127.0.0.1:6007).
--single-threaded-scene	L'arbre de la scène s'exécute en mode thread unique. Les groupes de sous-thread sont désactivés et s'exécutent sur le fil principal.
--debug-collisions	Afficher les formes de collision lors de l'exécution de la scène.
--debug-paths	Afficher les lignes de chemin lors de l'exécution de la scène.
--debug-navigation	Afficher les polygones de navigation lors de l'exécution de la scène.
--debug-avoidance	Afficher les visuels de débogage de navigation d'évitement lors de l'exécution de la scène.
--debug-stringnames	Affiche tous les allocations de StringName vers stdout quand le moteur quitte.
--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>	Simuler une charge CPU élevée (retarder chaque trame de <ms> millisecondes). N'utilisez pas un limiteur de FPS, utilisez plutôt --max-fps.
--time-scale <scale>	Forcer l'échelle de temps (plus rapide avec des valeurs plus élevées, 1.0 pour une vitesse normale).
--disable-vsync	Force la désactivation de la synchronisation verticale, même si elle est activée dans les paramètres du projet. Ne remplace pas l'exécution de la synchronisation verticale au niveau du pilote.
--disable-render-loop	Désactive la boucle de rendu pour que le rendu ne se produise que lorsqu'il est appelé explicitement depuis le script.
--disable-crash-handler	Désactiver le gestionnaire de crash lorsqu'il est pris en charge par le code de la plate-forme.
--fixed-fps <fps>	Force un nombre fixe d'images par seconde. Ce paramètre désactive la synchronisation temps-réel.
--delta-smoothing <enable>	Enable or disable frame delta smoothing ("enable", "disable").
--print-fps	Affiche les images par second à la sortie standard stdout.
--editor-pseudolocalization	Enable pseudolocalization for the editor and the project manager.

Outils autonomes

Commande	Description
-s, --script <script>	Exécute un script. <script> doit être un chemin de ressource relatif au projet ( monscript.gd sera interprété comme res://mon_script.gd) ou un chemin du système de fichiers absolu (par exemple sur Windows : C:/tmp/mon_script.gd).
--main-loop <nom_boucle_principale>	Run a MainLoop specified by its global class name.
--check-only	Parse uniquement les erreurs et quitte (à utiliser avec --script).
--import	Démarre l'éditeur, attend que toutes les ressources soient importées, puis quitte. Implique --editor et --quit.
--export-release <preset> <path>	Exporte le projet en mode release en utilisant le préréglage et le chemin de sortie donnés. Le nom du préréglage doit correspondre à un nom défini dans "export_presets.cfg". <path> doit être absolu ou relatif au répertoire du projet, et inclure le nom du fichier pour le binaire (par ex. 'builds/jeu.exe'). Le répertoire cible doit exister.
--export-debug <preset> <path>	Comme --export-release, mais utilise le modèle de débogage. Implique --import.
--export-pack <preset> <path>	Comme --export-release, mais n'exporter que le pack de jeu pour le préréglage donné. L'extension <path> détermine s'il sera au format PCK ou ZIP. Implique --import.
--export-patch <préréglage> <chemin>	Export pack with changed files only. See --export-pack description for other considerations.
--patches <chemin>	Liste des correctifs à utiliser avec --export-patch. La liste est séparée par des virgules.
--install-android-build-template	Installer le modèle de compilation Android. Utilisé conjointement avec --export-release ou --export-debug.
--convert-3to4 [<max_file_kb>] [<max_line_size>]	Convertit un projet de Godot 3.x en Godot 4.x.
--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]	Affiche quels éléments seront renommés lors de la conversion du projet de Godot 3.x à Godot 4.x.
--doctool [<path>]	Écrit la référence de l'API du moteur vers le chemin <path> au format XML, fusionnant les fichiers s'ils existent.
--no-docbase	Interdit de dump les types de base (utilisé avec --doctool).
--gdextension-docs	Plutôt que de dump l'API du moteur, génère la référence de l'API à partir de toutes les GDExtensions chargées dans le projet actuel (utilisée avec --doctool).
--gdscript-docs <path>	Rather than dumping the engine API, generate API reference from the inline documentation in the GDScript files found in <path> (used with --doctool).
--build-solutions	Construit les solutions de scripts (par ex. pour les projets C#). Implique --editor et nécessite un projet valide à éditer.
--dump-gdextension-interface	Génère un fichier d'entête GDExtension 'gdextension_interface.h' dans le dossier courant. Ce fichier est le fichier de base requis pour implémenter une GDExtension.
--dump-gdextension-interface-json	Génère un dump JSON de l'API Godot pour l'interface GDExtension, appelé 'gdextension_interface.json', dans le dossier actuel.
--dump-extension-api	Génère le dump JSON de l'API Godot pour les liaisons GDExtension, appelé 'extension_api.json', dans le dossier actuel.
--dump-extension-api-with-docs	Génère le dump JSON de l'API Godot comme pour l'option précédente, mais en incluant la documentation.
--validate-extension-api <path>	Valide un fichier API d'extension extrait (avec l'option ci-dessus) d'une version précédente du moteur pour assurer la compatibilité de l'API. Si des incompatibilités ou des erreurs sont détectées, le code renvoyé sera non nul.
--benchmark	Benchmark le temps d'exécution et l'affiche dans la console.
--benchmark-file <path>	Benchmark le temps d'exécution et enregistre le en format JSON dans le fichier donné. Le chemin doit être absolu.
--test [--help]	Run unit tests (requires compiling the engine with tests=yes). Use --test --help for more information.

Chemin

Il est recommandé que votre binaire d'éditeur Godot soit dans votre variable d'environnement PATH, de sorte qu'il puisse être exécuté facilement à partir de n'importe quel endroit en tapant godot. Vous pouvez le faire sous Linux en plaçant le binaire Godot dans /usr/local/bin et en vous assurant qu'il s'appelle godot (sensible à la casse).

Pour effectuer cela sur Windows ou macOS facilement, vous pouvez installer Godot en utilisant Scoop (sur Windows) ou Homebrew (sur macOS). Ceci rendra automatiquement la copie de Godot installée disponible dans le 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

Définir le chemin du projet

Selon l'endroit où se trouve votre binaire Godot et votre répertoire de travail actuel, vous devrez peut-être définir le chemin d'accès à votre projet pour que les commandes suivantes fonctionnent correctement.

Lors de l'exécution de l'éditeur, cela peut être fait en donnant le chemin du fichier project.godot de votre projet soit en tant que premier argument, comme ceci :

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

Pour toutes les commandes, cela peut être fait en utilisant l'argument --path :

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

Par exemple, la commande complète pour exporter votre jeu (comme expliqué ci-dessous) pourrait ressembler à ceci :

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

En commençant dans un sous-répertoire de votre projet, utilisez l'argument --upwards pour que Godot trouve automatiquement le fichier project.godot en recherchant de manière récursive les répertoires parents.

Par exemple, exécuter une scène (comme expliqué ci-dessous) nichée dans un sous-répertoire pourrait ressembler à ceci lorsque votre répertoire de travail est dans le même chemin :

godot --upwards nested_scene.tscn

Créer un projet

La création d'un projet à partir de la ligne de commande peut se faire en naviguant dans le shell jusqu'à l'endroit désiré et en créant un fichier project.godot.

mkdir newgame
cd newgame
touch project.godot

Le projet peut maintenant être ouvert avec Godot.

Exécution de l'éditeur

L'exécution de l'éditeur se fait en exécutant Godot avec le paramètre -e. Cela doit être fait depuis le répertoire du projet ou un sous-répertoire comme expliqué au dessus, sinon la commande est ignorée et le gestionnaire de projet apparaît.

godot -e

En passant le chemin complet vers le fichier project.godot, le drapeau -e peut être omis.

Si une scène a été créée et enregistrée, elle peut être modifiée ultérieurement en exécutant le même code avec la dite scène en argument.

godot -e scene.tscn

Effacer une scène

Godot respecte votre système de fichiers et ne créera pas de fichiers de métadonnées supplémentaires. Utilisez rm pour effacer un fichier de scène. Assurez-vous que rien ne fait référence à cette scène, sinon cela provoquera une erreur à l’ouverture.

rm scene.tscn

Éxécuter le jeu

Pour lancer le jeu, il suffit d'exécuter Godot dans le répertoire ou sous-répertoire du projet comme expliqué au dessus.

godot

Notez que passer le fichier project.godot va toujours exécuter l'éditeur au lieu d’exécuter le jeu.

Lorsqu'une scène spécifique doit être testée, passez cette scène à la ligne de commande.

godot scene.tscn

Débogage

Intercepter les erreurs dans la ligne de commande peut être une tâche difficile car elles ne font que défiler. Pour cela, un débogueur de ligne de commande est fourni en ajoutant -d. Cela fonctionne à la fois pour exécuter le jeu ou une simple scène.

godot -d

godot -d scene.tscn

Exportation

L'exportation du projet à partir de la ligne de commande est également prise en charge. Ceci est particulièrement utile pour les configurations d'intégration continue.

Note

Utiliser l'argument de ligne de commande --headless est requis sur les plates-formes qui n'ont pas d'accès au GPU (comme en intégration continue). Sur les plates-formes avec accès au GPU, --headless empêche une fenêtre d'apparaître pendant que le projet est exporté.

# `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

Le nom du préréglage doit correspondre au nom d'un préréglage d'exportation défini dans le fichier export_presets.cfg du projet. Si le nom du préréglage contient des espaces ou des caractères spéciaux (tels que "Windows Desktop"), il doit être entouré de guillemets.

Pour exporter une version de débogage du jeu, utilisez le commutateur --export-debug au lieu de --export-release. Leurs paramètres et leur utilisation sont les mêmes.

Pour exporter uniquement un fichier PCK, utilisez l'option --export-pack suivie du nom du préréglage et du chemin de sortie, avec l'extension du fichier, au lieu de --export-release ou export-debug. L'extension du chemin de sortie détermine le format du paquet, soit PCK soit ZIP.

Avertissement

Lorsque vous spécifiez un chemin relatif comme chemin pour --export-release, --export-debug ou --export-pack, le chemin sera relatif au répertoire contenant le fichier project.godot, non relatif au répertoire de travail actuel.

Exécuter un script

Il est possible d'exécuter un simple script .gd en ligne de commande. Cette fonctionnalité est particulièrement utile dans les grands projets, par ex. pour la conversion groupée de ressources, ou l’import/export personnalisé.

Le script doit hériter de SceneTree ou MainLoop.

Voici un exemple sayhello.gd, montrant son fonctionnement :

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

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

Et comment l'exécuter :

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

Si aucun fichier project.godot n'existe au chemin, le chemin courant est supposé être le répertoire de travail courant (sauf si --path est spécifié).

The script path will be interpreted as a resource path relative to the project, here res://sayhello.gd. You can also use an absolute filesystem path instead, which is useful if the script is located outside of the project directory.

La première ligne de sayhello.gd ci-dessus est communément appelée shebang. Si le binaire Godot se trouve dans votre PATH en tant que godot, il vous permet d'exécuter le script comme suit dans les distributions Linux modernes, ainsi que dans macOS :

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

Si ce qui précède ne fonctionne pas dans votre version actuelle de Linux ou de macOS, vous pouvez toujours faire en sorte que le shebang exécute Godot directement à partir de l'endroit où il se trouve comme suit :

#!/usr/bin/godot -s