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 librería 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.

En macOS, el proceso es diferente debido a que Godot está contenido en un paquete .app (que es una carpeta, no un archivo). Para ejecutar un binario de Godot desde un terminal en macOS, debe cd en la carpeta donde se encuentra el paquete de aplicaciones de Godot, luego ejecutar Godot.app / Contents / MacOS / Godot seguido de cualquier línea de comando argumentos. Si ha cambiado el nombre del paquete de aplicaciones de Godot a otro nombre, asegúrese de editar esta línea de comando en consecuencia.

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.

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

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.
--debug-server <uri>	Inicia el servidor de depuración del editor (<protocolo>://<host/IP>[:<puerto>], ej. tcp:127.0.0.1:6007)
--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 dónde language es un código de idioma de 2 o 3 letras en minúsculas y el resto es opcional. Consultar :ref: `doc_locales`para más detalles.
--path <directorio>	La ruta a un proyecto (directory debe contener un archivo 'project.godot').
-u, --upwards	Buscar un archivo 'project.godot' en las carpetas recursivamente.
--main-pack <archivo>	Ruta a un archivo de paquete (.pck) a cargar.
--render-thread <modo>	Modo de renderizado con hilos ('unsafe', 'safe', 'separate'). Ver Thread Model para más detalles.
--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.
--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.
--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>	Selecciona el modo XR ('default', 'off', 'on').

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).
--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.
--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.
--frame-delay <ms>	Simular una alta carga de CPU (retrasar cada fotograma <ms> milisegundos).
--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 anula 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>	Activa o desactiva el suavizado del delta de fotogramas ('enable', 'disable').
--print-fps	Imprime los fotogramas por segundo en la stdout.

Herramientas independientes

Comando	Descripción
-s, --script <script>	Ejecutar un script. <script> debe ser una ruta de recurso relativa al proyecto (myscript.gd se interpretará como res://myscript.gd) o una ruta absoluta del sistema de archivos (por ejemplo en Windows C:/tmp/myscript.gd)
--check-only	Analizar solo los errores y salir (usar con `` --script``).
--import	Inicia el editor, espera a que se importen los recursos y luego sale. Implica --editor y --quit.
--export-release <preset> <path>	Exporta el proyecto usando el preset dado y la plantilla de lanzamiento correspondiente. El nombre del preset debe coincidir el definido en export_preset.cfg. La <ruta> debería ser absoluta o relativa al directorio del proyecto, y debería incluir el nombre del archivo binario (ej: 'builds/game.exe'). El directorio de destino debe existir. Implica --import.
--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 preset dado. La extensión de <path> determina si será en formato PCK o ZIP. Implica --import.
--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).
--gdscript-docs <path>	En vez de volcar los datos de la API del motor, genera una referencia de la API a partir de la documentación incluida dentro de los archivos GDScript que se encuentren en la <ruta> (utilizado con --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	Genera el archivo cabecera de GDExtension 'gdnative_interface.h' en la carpeta actual. Este archivo es el archivo base necesario para implementar una GDExtension.
--dump-extension-api	Genera un volcado en JSON de la API de Godot para los bindings de la GDExtension llamado 'extension_api.json' en la carpeta actual.
--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.

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