Tutorial de línea de comandos

A algunos desarrolladores les gusta usar la línea de comandos extensivamente. Godot está diseñado para ser amigable con ellos, así que aquí están los pasos para trabajar completamente desde la línea de comandos. Dado que el motor depende de pocas o ninguna biblioteca externa, los tiempos de inicialización son bastante rápidos, lo que lo hace adecuado para este flujo de trabajo.

Nota

En Windows y Linux, puedes ejecutar un binario de Godot en una terminal especificando su ruta relativa o absoluta.

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.

Referencia de la línea de comandos

Leyenda

• Disponible en la versión de editor, en las plantillas de exportación de depuración y de lanzamiento.

• Disponible únicamente en las versiones de editor y en las plantillas de exportación.

• Only available in editor builds, and export templates compiled with disable_path_overrides=false.

• Disponible únicamente en la versión de editor.

Ten en cuenta que los argumentos desconocidos de la línea de comandos no tienen ningún efecto en absoluto. El motor no te dará ningún aviso cuando uses un argumento en la línea de comandos que no exista para una compilación determinada.

Opciones generales

Comando	Descripción
-h, --help	Muestra la lista de opciones de línea de comandos.
--version	Muestra una cadena con la versión.
-v, --verbose	Usa el modo stdout detallado.
-q, --quiet	Modo silencioso, silencia los mensajes de stdout. Los errores seguirán siendo mostrados.
--no-header	Do not print engine version and rendering method header on startup.

Opciones de ejecución

Comando	Descripción
--, ++	Separador para los argumentos proveídos por el usuario. Los argumentos que sigan no son usados por el motor, pero pueden ser leídos desde OS.get_cmdline_user_args().
-e, --editor	Inicia el editor en lugar de ejecutar la escena.
-p, --project-manager	Inicia el Administrador de Proyectos, incluso si el proyecto es detectado de forma automática.
--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>	Inicia el servidor de depuración del editor (<protocolo>://<host/IP>[:<puerto>], ej. 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	Salir después de la primera iteración.
--quit-after	Se cierra luego de un número dado de iteraciones. Establecer en 0 para desactivar.
-l, --language <locale>	Utilizar una localización específica. <locale> sigue el formato language_Script_COUNTRY_VARIANT donde language es un código de idioma de 2 o 3 letras en minúsculas y el resto es opcional. Consultar Códigos de localización para más detalles.
--path <directorio>	Path to a project (<directory> must contain a "project.godot" file).
--scene <path>	Path or UID of a scene in the project that should be started.
--main-pack <archivo>	Path to a pack (.pck) file to load.
--render-thread <modo>	Render thread mode ("unsafe", "safe", "separate"). See Thread Model for more details.
--remote-fs <dirección>	Sistema de archivos remoto (<host/IP>[:<port>] dirección).
--remote-fs-password <password>	Contraseña para el sistema de archivos remoto.
--audio-driver <driver>	Controlador de audio. Usa --help primero para mostrar la lista de controladores disponibles.
--display-driver <driver>	Controlador de video (y controlador de renderizado). Usa --help primero para mostrar la lista de controladores 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>	Nombre del renderizador. Requiere soporte para el driver.
--rendering-driver <driver>	Controlador de video (depende del controlador de pantalla). Usa --help primero para mostrar la lista de controladores disponibles.
--gpu-index <device_index>	Utilizar un GPU concreto (ejecutar con --verbose para obtener una lista de dispositivos disponibles).
--text-driver <driver>	Driver de texto (Fuentes, BiDi, shaping).
--tablet-driver <driver>	Driver de entrada del lápiz/tableta.
--headless	Habilitar el modo descabezado (--display-driver headless --audio-driver Dummy). Útil para servidores y 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>	Ejecutar el motor en cierto modo tal que una película es grabada en disco (usualmente con una extensión .avi or .png). La opción --fixed-fps es forzada cuando se activa, pero puede ser utilizada para cambiar los FPS de la película. La opción --disable-vsync puede acelerar la grabación de la película pero dificulta la interacción. La opción --quit-after puede ser utilizada para especificar el número de fotogramas a grabar.

Opciones de visualización

Comando	Descripción
-f, --fullscreen	Solicitar modo de pantalla completa.
-m, --maximized	Solicitar una ventana maximizada.
-w, --windowed	Solicitar modo ventana.
-t, --always-on-top	Solicita una ventana siempre encima.
--resolution <W>x<H>	Solicitar resolución de ventana.
--position <X>,<Y>	Solicitar posición de la ventana.
--screen <N>	Solicitar pantalla de la ventana.
--single-window	Utiliza una ventana única (no sub-ventanas separadas).
--xr-mode <mode>	Select XR mode ("default", "off", "on").
--wid <window_id>	Request parented to window.
--accessibility <mode>	Select accessibility mode ['auto" (when screen reader is running, default), "always", "disabled'].

Opciones de depuración

Comando	Descripción
-d, --debug	Depurar (depurador stdout local).
-b, --breakpoints	Lista de puntos de interrupción como fuente::pares separados por comas, sin espacios (usar %20 en su lugar).
--ignore-error-breaks	If debugger is connected, prevents sending error breakpoints.
--profiling	Habilitar la creación de perfiles en el depurador de scripts.
--gpu-profile	Muestra un perfil de GPU de las tareas que ocuparon el mayor tiempo durante el renderizado de fotogramas.
--gpu-validation	Habilita los validation layers de la API gráfica para depuración.
--gpu-abort	Aborta ante errores de GPU (usualmente errores de layers de validación), puede ser útil para visualizar los problemas si tu sistema se congela.
--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	Fuerza barreras entre rutas de navegación. Útil para restringir un comando que provoca reinicios de la GPU. Actualmente solo está implementado para Vulkan.
--remote-debug <uri>	Depuración remota (<protocolo>://<host/IP>[:<puerto>]` , ej. ``tcp://127.0.01:6007).
--single-threaded-scene	El árbol de escena se ejecuta en modo de un solo hilo. Los grupos de sub-hilos son desactivados y corren en el hilo principal.
--debug-collisions	Mostrar la forma de la colisión mientras se ejecuta la escena.
--debug-paths	Mostrar las líneas de rutas mientras se ejecuta la escena.
--debug-navigation	Mostrar polígonos de navegación mientras se ejecuta la escena.
--debug-avoidance	Mostrar visuales de depuración de evasión de navegación mientras se ejecuta la escena.
--debug-stringnames	Imprime todas las asignaciones de StringName en stdout cuando el motor se cierra.
--debug-canvas-item-redraw	Display a rectangle each time a canvas item requests a redraw (useful to troubleshoot low processor mode).
--max-fps <fps>	Establece un número máximo de fotogramas por segundo renderizados (se puede usar para limitar el consumo de energía). Un valor de 0 da como resultado una velocidad de fotogramas ilimitada.
--frame-delay <ms>	Simulate high CPU load (delay each frame by <ms> milliseconds). Do not use as a FPS limiter; use --max-fps instead.
--time-scale <escala>	Forzar la escala de tiempo (los valores altos son más rápidos, 1.0 es la velocidad normal).
--disable-vsync	Fuerza la desactivación de la sincronización vertical, incluso si esta activada en la configuración del proyecto. No sobrescribe la aplicación del V-Sync a nivel del driver.
--disable-render-loop	Deshabilita el bucle de renderizado para que el renderizado solo ocurra cuando se llama explícitamente desde un script.
--disable-crash-handler	Deshabilite el controlador de fallas cuando sea compatible con el código de la plataforma.
--fixed-fps <fps>	Fuerza un número fijo de fotogramas por segundo. Esta configuración deshabilita la sincronización en tiempo real.
--delta-smoothing <enable>	Enable or disable frame delta smoothing ("enable", "disable").
--print-fps	Imprime los fotogramas por segundo en la stdout.
--editor-pseudolocalization	Enable pseudolocalization for the editor and the project manager.

Herramientas independientes

Comando	Descripción
-s, --script <script>	Run a script. <script> must be a resource path relative to the project (myscript.gd will be interpreted as res://my_script.gd) or an absolute filesystem path (for example, on Windows: C:/tmp/my_script.gd).
--main-loop <main_loop_name>	Run a MainLoop specified by its global class name.
--check-only	Only parse for errors and quit (use with --script).
--import	Inicia el editor, espera a que se importen los recursos y luego sale. Implica --editor y --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>	Como --export-release, pero utiliza la plantilla de depuración. Implica --import.
--export-pack <preestablecido> <ruta>	Como --export-release, pero sólo para exportar el paquete del juego para un ajuste preestablecido dado. La extensión de <path> determina si será en formato PCK o ZIP. Implica --import.
--export-patch <preset> <path>	Export pack with changed files only. See --export-pack description for other considerations.
--patches <paths>	List of patches to use with --export-patch. The list is comma-separated.
--instalar-plantilla-de-compilación-de-android	Install the Android build template. Used in conjunction with --export-release or --export-debug.
--convert-3to4 [<max_file_kb>] [<max_line_size>]	Convierte el proyecto de Godot 3.x a Godot 4.x.
--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]	Muestra aquellos elementos que serán renombrados al convertir de Godot 3.x a Godot 4.x.
--doctool [<path>]	Volcar la API de referencia del motor al <path> dado en formato XML, si encuentra archivos existentes, los combina.
--no-docbase	Impide el volcado de los tipos base (utilizado con --doctool).
--gdextension-docs	Rather than dumping the engine API, generate API reference from all the GDExtensions loaded in the current project (used with --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	Construye las soluciones de scripting (ej. para proyectos en C#). Implica --editor y requiere un proyecto válido para editar.
--dump-gdextension-interface	Generate GDExtension header file "gdextension_interface.h" in the current folder. This file is the base file required to implement a GDExtension.
--dump-gdextension-interface-json	Generate a JSON dump of the GDExtension interface named "gdextension_interface.json" in the current folder.
--dump-extension-api	Generate JSON dump of the Godot API for GDExtension bindings named "extension_api.json" in the current folder.
--dump-extension-api-with-docs	Generate JSON dump of the Godot API like the previous option, but including documentation.
--validate-extension-api <path>	Valida el archivo de una API de extensión (con la opción anterior) volcado desde una versión anterior del motor para garantizar la compatibilidad de la API. Si se detectan incompatibilidades o errores, el código retornado será distinto de cero.
--benchmark	Realiza una prueba de rendimiento del tiempo de ejecución y lo muestra en la consola.
--benchmark-file <ruta>	Realiza una prueba de rendimiento del tiempo de ejecución y la guarda en un archivo especificado en formato JSON. La ruta debe ser absoluta.
--test [--help]	Run unit tests (requires compiling the engine with tests=yes). Use --test --help for more information.

Ruta

Se recomienda que el binario de Godot se encuentre en la variable de entorno PATH, para que pueda ejecutarse fácilmente desde cualquier lugar escribiendo godot. Puedes hacerlo en Linux colocando el binario de Godot en /usr/local/bin y asegurándote de que se llame godot (sensible a mayúsculas).

Para lograr esto fácilmente en Windows o macOS, puedes instalar Godot usando Scoop (en Windows) o Homebrew (en macOS). Esto automáticamente hará que la copia de Godot instalada esté disponible en la variable de entorno 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

Configuración de la ruta del proyecto

Dependiendo de dónde se encuentre el binario de Godot y cuál sea su directorio de trabajo actual, es posible que necesites establecer la ruta a tu proyecto para que cualquiera de los siguientes comandos funcione correctamente.

Cuando ejecutas el editor, esto se puede hacer proporcionando la ruta al archivo project.godot de tu proyecto como el primer argumento, de esta manera:

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

Para todos los comandos, esto se puede hacer utilizando el argumento --path:

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

Por ejemplo, el comando completo para exportar tu juego (como se explica a continuación) podría verse así:

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

Cuando comiences desde un subdirectorio de tu proyecto, usa el argumento --upwards para que Godot encuentre automáticamente el archivo project.godot buscando recursivamente en los directorios superiores.

Por ejemplo, ejecutar una escena (como se explica a continuación) anidada en un subdirectorio podría parecerse a esto cuando tu directorio de trabajo está en la misma ruta:

godot --upwards nested_scene.tscn

Creación de un proyecto

Para crear un proyecto desde la línea de comandos, navega hasta el lugar deseado en el shell y crea un archivo project.godot.

mkdir newgame
cd newgame
touch project.godot

El proyecto ahora puede abrirse con Godot.

Ejecutar el editor

La ejecución del editor se realiza ejecutando Godot con la bandera -e. Esto debe hacerse desde dentro del directorio del proyecto o estableciendo la ruta del proyecto como se explicó anteriormente, de lo contrario el comando es ignorado y aparece el Administrador de Proyectos.

godot -e

Cuando se pasa la ruta completa al archivo project.godot, se puede omitir la bandera -e.

Si una escena ha sido creada y guardada, puede ser editada más tarde ejecutando el mismo código con esa escena como argumento.

godot -e scene.tscn

Borrar una escena

Godot es amigo de tu sistema de archivos y no creará archivos de metadatos adicionales. Usa rm para borrar un archivo de escena. Asegúrate de que nada referencie esa escena, de lo contrario se producirá un error al abrir el proyecto.

rm scene.tscn

Ejecutar el juego

Para ejecutar el juego, ejecuta Godot dentro del directorio del proyecto o con la ruta del proyecto como se explicó anteriormente.

godot

Ten en cuenta que al pasar el archivo project.godot siempre se ejecutará el editor en lugar de ejecutar el juego.

Cuando sea necesario probar una escena específica, pásala por línea de comandos.

godot scene.tscn

Depuración

Capturar errores en línea de comandos puede ser una tarea difícil porque simplemente pasanmuy rápido. Para esto, se proporciona un depurador de línea de comandos añadiendo -d. Funciona tanto para ejecutar el juego como para una sola escena.

godot -d

godot -d scene.tscn

Exportar

También se puede exportar el proyecto desde la línea de comandos. Esto es especialmente útil para configuraciones de integración continua.

Nota

El uso del argumento de línea de comandos --headless``es **requerido** en plataformas que no tienen acceso a una GPU (como en la integración continua). En plataformas con acceso a una GPU, ``--headless evita que se genere una ventana mientras se exporta el proyecto.

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

El nombre del preset debe coincidir con el nombre de un ajuste preestablecido de exportación definido en el archivo `` export_presets.cfg `` del proyecto. Si el nombre predeterminado contiene espacios o caracteres especiales (como "Escritorio de Windows"), debe estar entre comillas.

Para exportar una versión de depuración del juego, utiliza la opción --export-debug en lugar de --export-release. Sus parámetros y uso son los mismos.

Para exportar sólo un archivo PCK, utiliza la opción --export-pack seguida del nombre y la ruta de salida preestablecidos, con la extensión del archivo, en lugar de --export-release o --export-debug. La extensión de la ruta de salida determina el formato del paquete, ya sea PCK o ZIP.

Advertencia

Al especificar una ruta relativa como ruta para --export-release,` --export-debug` o --export-pack, la ruta será relativa al directorio que contiene el archivo` project.godot`, ** no** relativo al directorio de trabajo actual.

Ejecutar un script

Es posible ejecutar un script .gd desde la línea de comandos. Esta función es especialmente útil en proyectos grandes, por ejemplo, para la conversión por lotes de recursos o la importación/exportación personalizada.

El script debe heredar de SceneTree o MainLoop.

He aquí un ejemplo sayhello.gd, mostrando como funciona:

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

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

Y cómo ejecutarlo:

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

Si project.godot no existe en la ruta, se asume que la ruta actual es el directorio de trabajo a utilizar (a menos que se especifique --path).

La ruta del script se interpretará como una ruta de recurso relativa al proyecto; en este caso, "res://sayhello.gd". También puedes usar una ruta absoluta del sistema de archivos, lo cual resulta útil si el script se encuentra fuera del directorio del proyecto.

La primera línea de sayhello.gd se conoce comúnmente como shebang. Si el binario Godot está en tu PATH como godot, te permite ejecutar el script de la siguiente manera en distribuciones Linux modernas, así como en macOS:

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

Si lo anterior no funciona en su versión actual de Linux o MacOS, siempre puede hacer que el shebang ejecute Godot directamente desde donde se encuentra, de la siguiente manera:

#!/usr/bin/godot -s