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

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

Примечание

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

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

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

Легенда

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

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

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

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

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

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>	Путь к проекту (<directory> должен содержать файл 'project.godot').
scene <path>	Путь или UID сцены в проекте, которую следует запустить.
-u, --upwards	Просканировать папки вверх на предмет файла «project.godot».
--main-pack <file>	Путь к файлу пакета (.pck) для загрузки.
--render-thread <mode>	Режим потока рендеринга ('unsafe', 'safe', 'separate'). Подробнее см. Модель потока.
--remote-fs <address>	Удаленная файловая система (адрес <host/IP>[:<port>]).
--remote-fs-password <пароль>	Пароль для удаленного доступа к файловой системе.
--audio-driver <driver>	Аудио драйвер. Сначала используйте --help, чтобы отобразить список доступных драйверов.
--display-driver <драйвер>	Драйвер дисплея (и драйвер рендеринга). Сначала используйте --help, чтобы отобразить список доступных драйверов.
--audio-output-latency <ms>	Переопределить задержку аудиовывода в миллисекундах (по умолчанию 15 мс). Более низкие значения делают воспроизведение звука более быстрым, но увеличивают нагрузку на процессор и могут привести к прерыванию звука, если процессор не справляется
--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	Записывать выходные данные/журнал ошибок по указанному пути вместо расположения по умолчанию, определенного проектом. <file> путь должен быть абсолютным или относительным к каталогу проекта.
--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 <режим>	Выберите режим XR ('по умолчанию', 'выключен', 'включен').
--wid <window_id>	Запрос привязан к окну.
--accessibility <mode>	Выберите режим доступности ['auto' (по умолчанию, когда запущена программа чтения с экрана), '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>	Имитировать высокую нагрузку на процессор (задерживать каждый кадр на <мс> миллисекунд). Не используйте его для ограничения FPS; вместо этого лучше подойдёт --max-fps.
--time-scale <scale>	Масштаб времени силы (чем выше значение, тем быстрее, 1,0 — нормальная скорость).
--disable-vsync	Отключает вертикальную синхронизацию, даже если она включена в настройках проекта. Не работает, если вертикальная синхронизация принудительно включена на уровне драйвера.
--disable-render-loop	Отключить цикл рендеринга, чтобы рендеринг выполнялся только при явном вызове из скрипта.
--disable-crash-handler	Отключить обработчик сбоев, если это поддерживается кодом платформы.
--fixed-fps <fps>	Принудительно установить фиксированное количество кадров в секунду. Эта настройка отключает синхронизацию в реальном времени.
--delta-smoothing <включить>	Включает или выключает размытие кадра ('enable' (включить), 'disable' (выключить)).
--print-fps	Вывести количество кадров в секунду на стандартный вывод.
--editor-pseudolocalization	Включить псевдолокализацию для редактора и менеджера проекта.

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

Command	Описание
-s, --script <script>	Запустить скрипт. <script> должен быть путем к ресурсу относительно проекта (myscript.gd будет интерпретироваться как res://myscript.gd) или абсолютным путем к файловой системе (например, в Windows C:/tmp/myscript.gd)
--main-loop <main_loop_name>	Запустить MainLoop, заданный именем его глобального класса.
--check-only	Только анализировать на наличие ошибок и выходить (использовать с --script).
--import	Запускает редактор, ждет импорта любых ресурсов, а затем завершает работу. Подразумевает использование параметров --editor и --quit.
--export-release <preset> <path>	Экспортирует проект с использованием заданного пресета и соответствующего шаблона релиза. Имя пресета должно совпадать с одним из определенных в файле 'export_presets.cfg'. <path> должен быть либо абсолютным, либо относительным по отношению к каталогу проекта и включать имя файла для бинарной версии (например, 'builds/game.exe'). Целевой каталог должен существовать.
--export-debug <preset> <path>	Подобно --export-release, но использует шаблон отладки. Подразумевает использование --import.
--export-pack <preset> <path>	Как --export-release, но экспортирует только игровой пакет для заданной предустановки. Расширение <path> определяет, будет ли он в формате PCK или ZIP. Подразумевает --import.
--export-patch <preset> <path>	Экспортировать пакет только с изменёнными файлами. См. описание параметра --export-pack для получения дополнительной информации.
--patches <paths>	Список патчей для использования с --export-patch. Список разделён запятыми.
--install-android-build-template	Установить шаблон сборки Android. Используется вместе с --export-release или --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).
--gdscript-docs <путь>	Вместо выгрузки API движка, генерировать справочную документацию API из встроенной документации в файлах GDScript, найденных в <path> (используется с --doctool).
--build-solutions	Собрать решения для скриптов (например, для проектов на C#). Подразумевает использование --editor и требует наличия действительного проекта для редактирования.
--dump-gdextension-interface	Сгенерировать файл заголовка GDExtension 'gdnative_interface.h' в текущей папке. Этот файл является базовым для реализации GDExtension.
--dump-extension-api	Сгенерировать JSON-выгрузку API Godot для привязок GDExtension с именем „extension_api.json“ в текущей папке.
--validate-extension-api <путь>	Проверить файл API расширения, выгруженный (с использованием предыдущей опции) из предыдущей версии движка, чтобы обеспечить совместимость API. Если будут обнаружены несоответствия или ошибки, код возврата будет отличен от нуля.
--benchmark	Провести бенчмаркинг времени выполнения и вывести результаты в консоль.
--benchmark-file <путь>	Провести бенчмаркинг времени выполнения и сохранить результаты в заданный файл в формате JSON. Путь должен быть абсолютным.
--test [--help]	Запустите модульные тесты. Для получения дополнительной информации используйте --test --help.

Путь

Рекомендуется, чтобы ваш бинарный файл редактора 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