Engine

Наследует: Object

Предоставляет доступ к свойствам движка.

Описание

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

Свойства

int	max_fps	`0`
int	max_physics_steps_per_frame	`8`
float	physics_jitter_fix	`0.5`
int	physics_ticks_per_second	`60`
bool	print_error_messages	`true`
bool	print_to_stdout	`true`
float	time_scale	`1.0`

Методы

Array[ScriptBacktrace]	capture_script_backtraces(include_variables: bool = false) const
String	get_architecture_name() const
Dictionary	get_author_info() const
Array[Dictionary]	get_copyright_info() const
Dictionary	get_donor_info() const
int	get_frames_drawn()
float	get_frames_per_second() const
Dictionary	get_license_info() const
String	get_license_text() const
MainLoop	get_main_loop() const
int	get_physics_frames() const
float	get_physics_interpolation_fraction() const
int	get_process_frames() const
ScriptLanguage	get_script_language(index: int) const
int	get_script_language_count()
Object	get_singleton(name: StringName) const
PackedStringArray	get_singleton_list() const
Dictionary	get_version_info() const
String	get_write_movie_path() const
bool	has_singleton(name: StringName) const
bool	is_editor_hint() const
bool	is_embedded_in_editor() const
bool	is_in_physics_frame() const
Error	register_script_language(language: ScriptLanguage)
void	register_singleton(name: StringName, instance: Object)
Error	unregister_script_language(language: ScriptLanguage)
void	unregister_singleton(name: StringName)

Описания свойств

int max_fps = 0 🔗

void set_max_fps(value: int)
int get_max_fps()

Максимальное количество кадров, которые могут быть отрисованы в секунду (FPS). Значение 0 означает, что частота кадров не ограничена.

Ограничение FPS может быть полезно для снижения энергопотребления хост-машины, что уменьшает нагрев, уровень шума и продлевает срок службы батареи.

Если ProjectSettings.display/window/vsync/vsync_mode имеет значение Enabled или Adaptive, то этот параметр имеет приоритет, и максимальное количество FPS не может превышать частоту обновления монитора. См. также DisplayServer.screen_get_refresh_rate().

Если параметр ProjectSettings.display/window/vsync/vsync_mode включен, то на мониторах с включенной переменной частотой обновления (G-Sync/FreeSync) использование ограничения FPS на несколько кадров ниже частоты обновления монитора уменьшит задержку ввода, избегая при этом разрывов изображения. При более высоких частотах обновления разницу между ограничением FPS и частотой обновления монитора следует увеличить, чтобы обеспечить учет кадров при неточностях синхронизации. Оптимальная формула для значения ограничения FPS в этом сценарии: r - (r * r) / 3600.0, где r — частота обновления монитора.

Примечание: Фактическое количество кадров в секунду может быть ниже этого значения, если ЦП или ГП не справляются с логикой и рендерингом проекта.

Примечание: Фактическое количество кадров в секунду может быть ниже этого значения, если ЦП или ГП не успевают за логикой и рендерингом проекта.

Примечание: Если параметр ProjectSettings.display/window/vsync/vsync_mode отключен, ограничение частоты кадров до высокого значения, которое может стабильно достигаться системой, может уменьшить задержку ввода по сравнению с неограниченной частотой кадров. Поскольку это работает за счет обеспечения загрузки графического процессора ниже 100%, это снижение задержки эффективно только в сценариях, где узким местом является графический процессор, а не центральный процессор.

int max_physics_steps_per_frame = 8 🔗

void set_max_physics_steps_per_frame(value: int)
int get_max_physics_steps_per_frame()

Максимальное количество шагов физики, которые могут быть смоделированы в каждом отрендеренном кадре.

Примечание: Значение по умолчанию настроено так, чтобы не допустить, чтобы дорогостоящие физические симуляции бесконечно запускали еще более дорогостоящие симуляции. Однако игра будет выглядеть замедленной, если FPS рендеринга меньше, чем 1 / max_physics_steps_per_frame от physics_ticks_per_second. Это происходит, даже если delta постоянно используется в физических расчетах. Чтобы избежать этого, увеличьте max_physics_steps_per_frame, если вы увеличили physics_ticks_per_second значительно выше его значения по умолчанию.

float physics_jitter_fix = 0.5 🔗

void set_physics_jitter_fix(value: float)
float get_physics_jitter_fix()

Насколько физические тики синхронизированы с реальным временем. Если 0 или меньше, тики полностью синхронизированы. Более высокие значения заставляют игровые часы больше отклоняться от реальных часов, но они сглаживают колебания частоты кадров.

Примечание: Значение по умолчанию 0.5 должно быть достаточно хорошим для большинства случаев; значения выше 2 могут привести к тому, что игра будет реагировать на пропущенные кадры с заметной задержкой и не рекомендуются.

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

int physics_ticks_per_second = 60 🔗

void set_physics_ticks_per_second(value: int)
int get_physics_ticks_per_second()

Количество фиксированных итераций в секунду. Этот параметр определяет, как часто запускаются моделирование физики и метод Node._physics_process().

Использование ЦП приблизительно зависит от частоты обновления физики. Однако при очень низкой частоте обновления (обычно ниже 30) поведение физики может нарушаться. При низкой частоте обновления ввод также может стать менее отзывчивым, поскольку может возникнуть разрыв между регистрацией ввода и ответом на следующий такт обновления физики. Высокая частота обновления обеспечивает более точное моделирование физики, особенно для быстро движущихся объектов. Например, в гоночных играх может быть полезно увеличить частоту обновления выше значения по умолчанию (60).

См. также max_fps и ProjectSettings.physics/common/physics_ticks_per_second.

Примечание: За один отрендеренный кадр может быть смоделировано максимум max_physics_steps_per_frame тактов физики. Если для обеспечения корректной работы рендеринга требуется больше физических тиков на каждый отрендеренный кадр, проект будет казаться замедленным (даже если delta постоянно используется в физических расчетах). Поэтому рекомендуется также увеличить max_physics_steps_per_frame, если physics_ticks_per_second значительно превышает значение по умолчанию.

Примечание: Рекомендуется включить интерполяцию физики, если вы изменяете physics_ticks_per_second на значение, не кратное 60. Использование интерполяции физики позволит избежать дрожания изображения, когда частота обновления монитора и частота обновления физики не совпадают точно.

bool print_error_messages = true 🔗

void set_print_error_messages(value: bool)
bool is_printing_error_messages()

Если false, прекращается вывод сообщений об ошибках и предупреждений на консоль и в журнал вывода редактора. Это можно использовать для скрытия сообщений об ошибках и предупреждений во время выполнения набора модульных тестов. Это свойство эквивалентно настройке проекта ProjectSettings.application/run/disable_stderr.

Примечание: Это свойство не влияет на вкладку «Ошибки» редактора при запуске проекта из редактора.

Предупреждение: Если установлено значение false в любом месте проекта, важные сообщения об ошибках могут быть скрыты, даже если они выдаются другими скриптами. В скрипте @tool это также повлияет на сам редактор. Не сообщайте об ошибках, не убедившись, что сообщения об ошибках включены (как по умолчанию).

bool print_to_stdout = true 🔗

void set_print_to_stdout(value: bool)
bool is_printing_to_stdout()

Если false, прекращает вывод сообщений (например, с помощью @GlobalScope.print()) на консоль, в файлы журнала и в журнал вывода редактора. Это свойство эквивалентно настройке проекта ProjectSettings.application/run/disable_stdout.

Примечание: Это не прекращает вывод ошибок или предупреждений, создаваемых скриптами, на консоль или в файлы журнала, для получения более подробной информации см. print_error_messages.

float time_scale = 1.0 🔗

void set_time_scale(value: float)
float get_time_scale()

Множитель скорости, с которым обновляются игровые часы, по сравнению с реальным временем. Например, если установлено значение 2.0, игра будет работать в два раза быстрее, а если установлено значение 0.5, игра будет работать в два раза быстрее.

Это значение влияет на Timer, SceneTreeTimer и все другие симуляции, которые используют delta время (например, Node._process() и Node._physics_process()).

Примечание: Рекомендуется сохранять это свойство выше 0.0, так как в противном случае игра может вести себя непредсказуемо.

Примечание: Это не влияет на скорость воспроизведения звука. Используйте AudioServer.playback_speed_scale для регулировки скорости воспроизведения звука независимо от time_scale.

Примечание: Это не изменяет автоматически physics_ticks_per_second. При значениях выше 1.0 физическая симуляция может стать менее точной, так как каждый физический тик будет растягиваться на больший период времени двигателя. Если вы изменяете time_scale для ускорения симуляции в большой степени, рассмотрите также увеличение physics_ticks_per_second, чтобы сделать симуляцию более надежной.

Описания метода

Array[ScriptBacktrace] capture_script_backtraces(include_variables: bool = false) const 🔗

Захватывает и возвращает обратные трассировки из всех зарегистрированных языков скриптов.

По умолчанию возвращаемый ScriptBacktrace будет содержать только кадры стека в сборках редактора и отладочных сборках. Чтобы включить их также для сборок выпуска, вам необходимо включить ProjectSettings.debug/settings/gdscript/always_track_call_stacks.

Если include_variables имеет значение true, обратная трассировка также будет включать имена и значения любых глобальных переменных (например, автозагрузочных синглтонов) в точке захвата, а также локальных переменных и переменных-членов класса в каждом кадре стека. Однако это будет учитываться только при запуске игры с подключенным отладчиком, например, при запуске игры из редактора. Чтобы включить его также для экспортных сборок, вам необходимо включить ProjectSettings.debug/settings/gdscript/always_track_local_variables.

Предупреждение: Когда include_variables равен true, любые захваченные переменные могут потенциально (например, с обратными трассировками GDScript) быть их фактическими значениями, включая любые ссылки на объекты. Это означает, что сохранение такого ScriptBacktrace предотвратит освобождение этих объектов, поэтому обычно рекомендуется этого не делать.

String get_architecture_name() const 🔗

Возвращает имя архитектуры ЦП, для которой был собран двоичный файл Godot. Возможные возвращаемые значения включают "x86_64", "x86_32", "arm64", "arm32", "rv64", "ppc64", "loongarch64", "wasm64" и "wasm32".

Чтобы определить, является ли текущая сборка 64-разрядной, или тип архитектуры, не используйте имя архитектуры. Вместо этого используйте OS.has_feature() для проверки тега функции "64" или тегов, таких как "x86" или "arm". Более подробную информацию см. в документации Теги функций.

Примечание: Этот метод не возвращает имя архитектуры ЦП системы (как OS.get_processor_name()). Например, при запуске двоичного файла Godot x86_32 в системе x86_64 возвращаемое значение по-прежнему будет "x86_32".

Dictionary get_author_info() const 🔗

Возвращает информацию об авторе движка в виде Dictionary, где каждая запись представляет собой Array строк с именами известных участников движка Godot: lead_developers, founders, project_managers и developers.

Array[Dictionary] get_copyright_info() const 🔗

Возвращает Array словарей с информацией об авторских правах для каждого компонента исходного кода Godot.

Каждый Dictionary содержит идентификатор name и массив parts словарей. Он подробно описывает компонент с помощью следующих записей:

files - Array путей к файлам из исходного кода, затронутого этим компонентом;
copyright - Array владельцев этого компонента;
license - Лицензия, применяемая к этому компоненту (например, "Expat" или "CC-BY-4.0").

Dictionary get_donor_info() const 🔗

Возвращает Словарь категоризированных имен доноров. Каждая запись — это Array строк:

{platinum_sponsors, gold_sponsors, silver_sponsors, bronze_sponsors, mini_sponsors, gold_donors, silver_donors, bronze_donors}

int get_frames_drawn() 🔗

Возвращает общее количество кадров, отрисованных с момента запуска движка.

Примечание: На платформах headless или если рендеринг отключен с помощью --disable-render-loop через командную строку, этот метод всегда возвращает 0. См. также get_process_frames().

float get_frames_per_second() const 🔗

Возвращает среднее количество кадров, отображаемых каждую секунду (FPS), также известное как частота кадров.

Dictionary get_license_info() const 🔗

Возвращает Dictionary лицензий, используемых Godot, и включенных сторонних компонентов. Каждая запись представляет собой имя лицензии (например, "Expat") и связанный с ней текст.

String get_license_text() const 🔗

Возвращает полный текст лицензии Godot.

MainLoop get_main_loop() const 🔗

Возвращает экземпляр MainLoop. Обычно это основной SceneTree и он такой же, как Node.get_tree().

Примечание: Тип, созданный как основной цикл, может быть изменен с помощью ProjectSettings.application/run/main_loop_type.

int get_physics_frames() const 🔗

Возвращает общее количество кадров, пройденных с момента запуска движка. Это число увеличивается каждый физический кадр. См. также get_process_frames().

Этот метод можно использовать для более редкого запуска дорогостоящей логики без использования Timer:

func _physics_process(_delta):
    if Engine.get_physics_frames() % 2 == 0:
        pass # Здесь дорогостоящая логика выполняется только один раз каждые 2 физических кадра.

public override void _PhysicsProcess(double delta)
{
    base._PhysicsProcess(delta);

    if (Engine.GetPhysicsFrames() % 2 == 0)
    {
        // Здесь дорогостоящая логика выполняется только один раз каждые 2 физических кадра.
    }
}

float get_physics_interpolation_fraction() const 🔗

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

int get_process_frames() const 🔗

Возвращает общее количество кадров, пройденных с момента запуска движка. Это число увеличивается каждый кадр процесса, независимо от того, включен ли цикл рендеринга. См. также get_frames_drawn() и get_physics_frames().

Этот метод можно использовать для менее частого запуска дорогостоящей логики без использования Timer:

func _process(_delta):
    if Engine.get_process_frames() % 5 == 0:
        pass # Здесь дорогостоящая логика выполняется только один раз за каждые 5 кадров обработки (рендеринга).

public override void _Process(double delta)
{
    base._Process(delta);

    if (Engine.GetProcessFrames() % 5 == 0)
    {
        // Здесь дорогостоящая логика выполняется только один раз за каждые 5 кадров обработки (рендеринга).
    }
}

ScriptLanguage get_script_language(index: int) const 🔗

Возвращает экземпляр ScriptLanguage с заданным index.

int get_script_language_count() 🔗

Возвращает количество доступных языков для скриптов. Используйте с get_script_language().

Object get_singleton(name: StringName) const 🔗

Возвращает глобальный синглтон с заданным name или null, если он не существует. Часто используется для плагинов. См. также has_singleton() и get_singleton_list().

Примечание: Глобальные синглтоны — это не то же самое, что автоматически загружаемые узлы, которые настраиваются в настройках проекта.

PackedStringArray get_singleton_list() const 🔗

Возвращает список имен всех доступных глобальных синглтонов. См. также get_singleton().

Dictionary get_version_info() const 🔗

Возвращает информацию о текущей версии движка в виде Dictionary, содержащего следующие записи:

major - номер основной версии в виде целого числа;
minor - номер дополнительной версии в виде целого числа;
patch - номер версии исправления в виде целого числа;
hex - полная версия, закодированная в виде шестнадцатеричного целого числа с одним байтом (2 шестнадцатеричные цифры) на число (см. пример ниже);
status - статус (например, "beta", "rc1", "rc2", "stable" и т. д.) в виде строки;
build - имя сборки (например, "custom_build") в виде строки;
hash - полный хэш коммита Git в виде строки;
timestamp - Содержит дату коммита Git UNIX timestamp в секундах как int или 0, если недоступно;
string - major, minor, patch, status и build в одной строке.

Значение hex кодируется следующим образом, слева направо: один байт для основной версии, один байт для второстепенной, один байт для версии патча. Например, "3.1.12" будет 0x03010C.

Примечание: Значение hex по-прежнему является int внутренне, и его вывод даст вам его десятичное представление, которое не имеет особого смысла. Используйте шестнадцатеричные литералы для быстрого сравнения версий из кода:

if Engine.get_version_info().hex >= 0x040100:
    pass # Выполните действия, характерные для версии 4.1 или более поздней.
else:
    pass # Выполните действия, характерные для версий до 4.1.

if ((int)Engine.GetVersionInfo()["hex"] >= 0x040100)
{
    // Выполните действия, характерные для версии 4.1 или более поздней.
}
else
{
    // Выполните действия, характерные для версий до 4.1.
}

String get_write_movie_path() const 🔗

Возвращает путь к выходному файлу MovieWriter или пустую строку, если движок не был запущен в режиме Movie Maker. Путь по умолчанию можно изменить в ProjectSettings.editor/movie_writer/movie_file.

bool has_singleton(name: StringName) const 🔗

Возвращает true, если синглтон с указанным name существует в глобальной области видимости. См. также get_singleton().

print(Engine.has_singleton("OS"))          # Prints true
print(Engine.has_singleton("Engine"))      # Prints true
print(Engine.has_singleton("AudioServer")) # Prints true
print(Engine.has_singleton("Unknown"))     # Prints false

GD.Print(Engine.HasSingleton("OS"));          // Prints True
GD.Print(Engine.HasSingleton("Engine"));      // Prints True
GD.Print(Engine.HasSingleton("AudioServer")); // Prints True
GD.Print(Engine.HasSingleton("Unknown"));     // Prints False

Примечание: Глобальные синглтоны — это не то же самое, что автоматически загружаемые узлы, которые настраиваются в настройках проекта.

bool is_editor_hint() const 🔗

Возвращает true, если скрипт в данный момент выполняется внутри редактора, в противном случае возвращает false. Это полезно для скриптов @tool для условной отрисовки помощников редактора или предотвращения случайного запуска «игрового» кода, который может повлиять на состояние сцены в редакторе:

if Engine.is_editor_hint():
    draw_gizmos()
else:
    simulate_physics()

if (Engine.IsEditorHint())
    DrawGizmos();
else
    SimulatePhysics();

См. Запуск кода в редакторе в документации для получения дополнительной информации.

Примечание: Чтобы определить, запущен ли скрипт в редакторе build (например, при нажатии F5), вместо этого используйте OS.has_feature() с аргументом "editor". OS.has_feature("editor") оценивается как true как при запуске скрипта в редакторе, так и при запуске проекта из редактора, но возвращает false при запуске из экспортированного проекта.

bool is_embedded_in_editor() const 🔗

Возвращает true, если движок запущен встроенным в редактор. Это полезно для предотвращения попыток обновления режима окна или флагов окна, которые не поддерживаются при запуске проекта, встроенного в редактор.

bool is_in_physics_frame() const 🔗

Возвращает true, если движок находится внутри фиксированного шага физического процесса основного цикла.

func _enter_tree():
    # В зависимости от того, когда узел добавляется в дерево,
    # печатает либо "true" или "false".
    print(Engine.is_in_physics_frame())

func _process(delta):
    print(Engine.is_in_physics_frame()) # Prints false

func _physics_process(delta):
    print(Engine.is_in_physics_frame()) # Prints true

Error register_script_language(language: ScriptLanguage) 🔗

Регистрирует экземпляр ScriptLanguage, который будет доступен с ScriptServer.

Возвращает:

@GlobalScope.OK об успехе;
@GlobalScope.ERR_UNAVAILABLE если ScriptServer достиг лимита и не может зарегистрировать ни одного нового языка;
@GlobalScope.ERR_ALREADY_EXISTS если ScriptServer уже содержит язык с похожим расширением/названием/типом.

void register_singleton(name: StringName, instance: Object) 🔗

Регистрирует заданный Object instance как синглтон, доступный глобально под name. Полезно для плагинов.

Error unregister_script_language(language: ScriptLanguage) 🔗

Отменяет регистрацию экземпляра ScriptLanguage из ScriptServer.

Возвращает:

@GlobalScope.OK при успешном выполнении;
@GlobalScope.ERR_DOES_NOT_EXIST, если язык не зарегистрирован в ScriptServer.

void unregister_singleton(name: StringName) 🔗

Удаляет синглтон, зарегистрированный под name. Объект синглтон не освобожден. Работает только с определенными пользователем синглтонами, зарегистрированными с помощью register_singleton().