Руководство по командной строке

Некоторым разработчикам нравится широко использовать командную строку. Godot разработан для того, чтобы быть дружелюбным к ним, поэтому здесь приведены шаги для работы полностью из командной строки. Поскольку механизм практически не опирается на внешние библиотеки, время инициализации довольно быстрое, что делает его подходящим для данного рабочего процесса.

Примечание

В Windows и Linux вы можете запустить исполняемый файл Godot в терминале, указав его относительный или абсолютный путь.

На MacOS процесс отличается для Godot из-за того что Godot содержится в .app (который является папкой, а не файлом). Что бы запустить бинарный файл движка Godot с терминала на MacOS, надо перейти в папку где находится Godot с помощью команды cd, а затем запустить Godot, введя в терминал следующее: Godot.app/Contents/MacOS/Godot указав после этого аргументы запуска. Если вы переименовали папку с Godot, то убедитесь в том что вы изменили команду для запуска Godot соответсвующе.

Ссылка на командную строку

Легенда

• Доступно в эдитор сборках, при дебажном экспорте и в релизном экспорте шаблонов.

• Доступно только в эдитор сборках и при дебажном экспорте шаблонов.

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

• Доступно только в эдитор сборках.

Учтите, что неизвестные аргументы командной строки проигнорируются. Движок не сообщит вам о том, что вы используете несуществующие в выбранном варианте сборки аргументы.

Основные настройки

Command	Описание
-h, --help	Отобразить список опций командной строки.
--version	Показать строку версии.
-v, --verbose	Использовать подробный режим stdout.
-q, --quiet	Тихий режим, заглушает сообщения stdout. Ошибки по-прежнему отображаются.
--no-header	Не выводить версию движка и заголовок метода рендеринга при запуске.

Параметры запуска

Command	Описание
--, ++	Разделитель для пользовательских аргументов. Приведенные аргументы не используются движком, но могут быть прочитаны с помощью OS.get_cmdline_user_args().
-e, --editor	Запустить редактор вместо запуска сцены.
-p, --project-manager	Запустить Проектный Менеджер, даже если проект был найден автоматически.
--recovery-mode	Запустить редактор в режиме восстановления, в котором отключены функции, которые обычно могут вызывать сбои при запуске, такие как скрипты инструментов, плагины редактора, надстройки GDExtension и другие.
--debug-server <uri>	Запустить дебаг сервер для редактора (<protocol>://<host/IP>[:<port>], например tcp://127.0.0.1:6007)
--dap-port <port>	Использовать указанный порт для протокола отладочного адаптера GDScript. Рекомендуемый диапазон портов. [1024, 49151].
--lsp-port <port>	Использовать указанный порт для протокола сервера языка GDScript. Рекомендуемый диапазон портов. [1024, 49151].
--quit	Выйти после первой итерации.
--quit-after	Выйти после заданного числа итераций. Передайте 0 для отключения.
-l, --language <locale>	Использовать заданную локализацию. <locale> задается в формате language_Script_COUNTRY_VARIANT где 'language' двух-трех буквенное обозначение кода языка в нижнем регистре, все остальное опционально. Коды локалей (языков) для более подробной информации.
--path <directory>	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 <file>	Path to a pack (.pck) file to load.
--render-thread <mode>	Render thread mode ("unsafe", "safe", "separate"). See Thread Model for more details.
--remote-fs <address>	Удаленная файловая система (адрес <host/IP>[:<port>]).
--remote-fs-password <пароль>	Пароль для удаленного доступа к файловой системе.
--audio-driver <driver>	Аудио драйвер. Сначала используйте --help, чтобы отобразить список доступных драйверов.
--display-driver <драйвер>	Драйвер дисплея (и драйвер рендеринга). Сначала используйте --help, чтобы отобразить список доступных драйверов.
--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>	Имя рендерера. Требуется поддержка драйвера.
--rendering-driver <driver>	Драйвер рендеринга (зависит от драйвера дисплея). Сначала используйте --help, чтобы отобразить список доступных драйверов.
--gpu-index <индекс_устройства>	Использовать определенный GPU (запустите с --verbose чтобы получить список доступных устройств).
--text-driver <драйвер>	Текстовый драйвер (Шрифты, BiDi, shaping).
--tablet-driver <драйвер>	Драйвер ввода графического планшета.
--headless	Включает headless (безоконный) режим (--display-driver headless --audio-driver Dummy). Полезен для серверов и со --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 <файл>	Запустите движок таким образом, чтобы создать фильм (обычно с расширением .avi или .png). --fixed-fps применяется по умолчанию при включении, но может использоваться для изменения FPS фильма. --disable-vsync может ускорить запись фильма, но делает взаимодействие более сложным. --quit-after можно использовать для указания количества кадров для записи.

Опции дисплея

Command	Описание
-f, --fullscreen	Запросить полноэкранный режим.
-m, --maximized	Запросить развернутое окно.
-w, --windowed	Запросить оконный режим.
-t, --always-on-top	Запросить окно, которое всегда будет поверх остальных окон.
--resolution <W>x<H>	Запросить разрешение окна.
--position <X>,<Y>	Запросить позицию окна.
--screen <N>	Запросить экран окна.
--single-window	Использовать одиночное окно (без отдельных подокон).
--xr-mode <режим>	Select XR mode ("default", "off", "on").
--wid <window_id>	Запрос привязан к окну.
--accessibility <mode>	Select accessibility mode ['auto" (when screen reader is running, default), "always", "disabled'].

Опции отладки

Command	Описание
-d, --debug	Отладка (локальный отладчик стандартного вывода).
-b, --breakpoints	Список точек останова в виде пар source::line, разделенных запятыми, без пробелов (вместо этого используйте %20).
--ignore-error-breaks	Если подключен отладчик, предотвращает отправку точек останова при ошибках.
--profiling	Включить профилирование в отладчике скриптов.
--gpu-profile	Показать профиль GPU задач, которые занимали больше всего времени во время рендеринга кадров.
--gpu-validation	Включить слои валидации графического API validation layers для отладки.
--gpu-abort	Прекратить выполнение при ошибках GPU (обычно ошибки слоев валидации), что может помочь увидеть проблему, если ваша система зависает.
--generate-spirv-debug-info	Генерация отладочной информации SPIR-V. Это позволяет отлаживать шейдеры на уровне исходного кода с помощью RenderDoc.
--extra-gpu-memory-tracking	Включает дополнительное отслеживание памяти (см. справочник по классу RenderingDevice.get_driver_and_device_memory_report() и связанным методам). В настоящее время реализовано только для Vulkan. Включение этой функции может привести к сбоям в некоторых системах из-за ошибок в драйверах или загрузчике Vulkan. См. https://github.com/godotengine/godot/issues/95967
--accurate-breadcrumbs	Принудительно устанавливать барьеры между навигационными цепочками. Полезно для определения команды, вызывающей перезагрузку графического процессора. В настоящее время реализовано только для Vulkan.
--remote-debug <uri>	Удаленная отладка (<protocol>://<host/IP>[:<port>], например, tcp://127.0.0.1:6007).
--single-threaded-scene	Запустить дерево сцены в однопоточном режиме. Дочерние потоки отключены и будут запущенны в основном потоке.
--debug-collisions	Показывать формы столкновений при запуске сцены.
--debug-paths	Показывать линии пути при запуске сцены.
--debug-navigation	Показывать навигационные полигоны при запуске сцены.
--debug-avoidance	Показывать визуальные эффекты отладки избежания навигации при запуске сцены.
--debug-stringnames	Печать всех выделений StringName в stdout при завершении работы движка.
--debug-canvas-item-redraw	Отображать прямоугольник каждый раз, когда элемент холста запрашивает перерисовку (полезно для устранения неполадок в режиме низкой загрузки процессора).
--max-fps <fps>	Устанавливает максимальное количество отрисовываемых кадров в секунду (можно использовать для ограничения энергопотребления). Значение 0 означает неограниченную частоту кадров.
--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 <scale>	Масштаб времени силы (чем выше значение, тем быстрее, 1,0 — нормальная скорость).
--disable-vsync	Отключает вертикальную синхронизацию, даже если она включена в настройках проекта. Не работает, если вертикальная синхронизация принудительно включена на уровне драйвера.
--disable-render-loop	Отключить цикл рендеринга, чтобы рендеринг выполнялся только при явном вызове из скрипта.
--disable-crash-handler	Отключить обработчик сбоев, если это поддерживается кодом платформы.
--fixed-fps <fps>	Принудительно установить фиксированное количество кадров в секунду. Эта настройка отключает синхронизацию в реальном времени.
--delta-smoothing <включить>	Enable or disable frame delta smoothing ("enable", "disable").
--print-fps	Вывести количество кадров в секунду на стандартный вывод.
--editor-pseudolocalization	Включить псевдолокализацию для редактора и менеджера проекта.

Автономные инструменты

Command	Описание
-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	Запускает редактор, ждет импорта любых ресурсов, а затем завершает работу. Подразумевает использование параметров --editor и --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>	Подобно --export-release, но использует шаблон отладки. Подразумевает использование --import.
--export-pack <preset> <path>	Как --export-release, но экспортирует только игровой пакет для заданной предустановки. Расширение <path> определяет, будет ли он в формате PCK или ZIP. Подразумевает --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.
--install-android-build-template	Install the Android build template. Used in conjunction with --export-release or --export-debug.
--convert-3to4 [<макс_разм_файла_кб>] [<макс_разм_линии>]	Преобразует проект из Godot 3.x в Godot 4.x.
--validate-conversion-3to4 [<макс_разм_файла_кб>] [<макс_разм_линии>]	Показывает, какие элементы будут переименованы при преобразовании проекта из Godot 3.x в Godot 4.x.
--doctool [<путь>]	Вывести ссылку API движка на указанный <path> в формате XML, объединив, если будут найдены существующие файлы.
--no-docbase	Запретить выгрузку базовых типов (используется с --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 <путь>	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	Собрать решения для скриптов (например, для проектов на C#). Подразумевает использование --editor и требует наличия действительного проекта для редактирования.
--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 <путь>	Проверить файл API расширения, выгруженный (с использованием предыдущей опции) из предыдущей версии движка, чтобы обеспечить совместимость API. Если будут обнаружены несоответствия или ошибки, код возврата будет отличен от нуля.
--benchmark	Провести бенчмаркинг времени выполнения и вывести результаты в консоль.
--benchmark-file <путь>	Провести бенчмаркинг времени выполнения и сохранить результаты в заданный файл в формате JSON. Путь должен быть абсолютным.
--test [--help]	Run unit tests (requires compiling the engine with tests=yes). Use --test --help for more information.

Путь

Рекомендуется, чтобы ваш бинарный файл редактора Godot находился в переменной окружения PATH, чтобы его можно было легко выполнить из любого места, набрав godot. Вы можете сделать это на Linux, поместив бинарный файл Godot в /usr/local/bin и убедившись, что он называется godot.

Чтобы достичь этого на Windows или macOS, вы можете скачать Godot используя Scoop (на Windows) или Homebrew (на macOS). Это автоматически сделает копию Godot доступной в 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

Настройка пути проекта

В зависимости от того, где расположен ваш бинарный файл Godot и какая у вас рабочая директория, для корректной работы одной из следующих команд может понадобиться указать путь к вашему проекту.

При запуске редактора это можно сделать, указав путь к файлу project.godot вашего проекта в качестве первого аргумента, например:

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

Для всех команд это можно сделать с помощью аргумента --path:

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

Например, полная команда для экспорта вашей игры (описано ниже) может выглядеть следующим образом:

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

Когда вы запускаете из подпапки вашего проекта, используйте аргумент --upwards для Godot, чтобы автоматически найти файл project.godot путем рекурсивного поиска в родительских директориях.

Например, запуск сцены (как объясняется ниже), расположенной в подпапке, может выглядеть следующим образом, если ваш рабочий каталог находится в том же пути:

godot --upwards nested_scene.tscn

Создание проекта

Создать проект из командной строки можно, перейдя в оболочке в нужное место и создав файл project.godot.

mkdir newgame
cd newgame
touch project.godot

Теперь проект можно открыть с помощью Godot.

Запуск редактора

Запуск редактора осуществляется путем запуска Godot с флагом -e. Это должно быть сделано из каталога проекта или путем установки пути проекта, как описано выше, в противном случае команда игнорируется и появляется Менеджер Проектов.

godot -e

При передаче полного пути к файлу project.godot флаг -e можно опустить.

Если сцена была создана и сохранена, ее можно отредактировать позже, запустив тот же код с этой сценой в качестве аргумента.

godot -e scene.tscn

Удаление сцены

Godot дружит с вашей файловой системой и не будет создавать дополнительных файлов метаданных. Используйте rm для стирания файла сцены. Убедитесь, что на эту сцену ничего не ссылается. В противном случае при открытии проекта возникнет ошибка.

rm scene.tscn

Запуск игры

Чтобы запустить игру, запустите Godot в каталоге проекта или с путем проекта, как описано выше.

godot

Обратите внимание, что передача файла project.godot всегда запустит редактор, а не игру.

Если необходимо протестировать определенную сцену, передайте ее в командную строку.

godot scene.tscn

Отладка

Отлов ошибок в командной строке может быть сложной задачей, поскольку они быстро прокручиваются. Для этого предоставляется отладчик командной строки, добавляющий -d. Он работает как для запуска игры, так и для отдельной сцены.

godot -d

godot -d scene.tscn

Экспорт

Также поддерживается экспорт проекта из командной строки. Это особенно полезно для непрерывной интеграции.

Примечание

Использование аргумента командной строки --headless обязательно на платформах, не имеющих доступа к GPU (таких как системы непрерывной интеграции). На платформах с доступом к GPU аргумент --headless препятствует появлению окна во время экспорта проекта.

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

Имя предустановки должно совпадать с именем предустановки экспорта, определенной в файле проекта export_presets.cfg. Если имя предустановки содержит пробелы или специальные символы (например, «Рабочий стол Windows»), оно должно быть заключено в кавычки.

Чтобы экспортировать отладочную версию игры, используйте ключ --export-debug вместо --export-release. Их параметры и использование одинаковы.

Чтобы экспортировать только файл PCK, используйте опцию --export-pack, за которой следует предустановленное имя и выходной путь с расширением файла, вместо --export-release или --export-debug. Расширение выходного пути определяет формат пакета: PCK или ZIP.

Предупреждение

При указании относительного пути в качестве пути для --export-release, --export-debug или --export-pack путь будет относительным к каталогу, содержащему файл project.godot, а не относительно текущего рабочего каталога.

Запуск скрипта

Можно запустить скрипт .gd из командной строки. Эта функция особенно полезна в больших проектах, например, для пакетного преобразования активов или пользовательского импорта/экспорта.

Скрипт должен наследоваться от SceneTree или MainLoop.

Вот пример sayhello.gd, показывающий, как это работает:

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

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

И как запустить его:

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

Если файл project.godot не существует в пути, то текущий путь считается текущим рабочим каталогом (если не указано --path).

Путь к скрипту будет интерпретироваться как путь к ресурсу относительно проекта, здесь res://sayhello.gd. Вместо этого вы также можете использовать абсолютный путь к файловой системе, что полезно, если скрипт находится вне каталога проекта.

Первая строка sayhello.gd отсылается к так называемому шебангу. По правилам этой инструкции, если бинарный исполняемый файл Godot указан в переменной окружения PATH как godot, вы сможете запускать скрипт в современных дистрибутивах Linux, а также в macOS:

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

Если вышеперечисленное не работает в вашей текущей версии Linux или macOS, вы всегда можете заставить шебанг запускать Godot прямо с того места, где он находится, следующим образом:

#!/usr/bin/godot -s