Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

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

float

time_scale

1.0

方法

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_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()

The maximum number of frames that can be rendered every second (FPS). A value of 0 means the framerate is uncapped.

Limiting the FPS can be useful to reduce the host machine's power consumption, which reduces heat, noise emissions, and improves battery life.

If ProjectSettings.display/window/vsync/vsync_mode is Enabled or Adaptive, the setting takes precedence and the max FPS number cannot exceed the monitor's refresh rate.

If ProjectSettings.display/window/vsync/vsync_mode is Enabled, on monitors with variable refresh rate enabled (G-Sync/FreeSync), using an FPS limit a few frames lower than the monitor's refresh rate will reduce input lag while avoiding tearing.

See also physics_ticks_per_second and ProjectSettings.application/run/max_fps.

Note: The actual number of frames per second may still be below this value if the CPU or GPU cannot keep up with the project's logic and rendering.

Note: If ProjectSettings.display/window/vsync/vsync_mode is Disabled, limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios.


int max_physics_steps_per_frame = 8 🔗

  • void set_max_physics_steps_per_frame(value: int)

  • int get_max_physics_steps_per_frame()

每个渲染帧所能模拟的最大物理迭代数。

注意:调整默认值是为了防止昂贵的物理模拟无限期地触发更昂贵的模拟。然而,如果渲染 FPS 小于 physics_ticks_per_second1 / max_physics_steps_per_frame,游戏看上去会是降速的。即便在物理计算中始终使用 delta 也一样会发生。要避免这种情况,如果已经增大了 physics_ticks_per_second,而且远大于其默认值,那么建议将 max_physics_steps_per_frame 也调大。


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 的执行频率。因为 Godot 不会进行物理步骤的插值,所以通常应该总是将其设成大于等于 60 的值。因此,如果值小于 60 就会看起来卡顿。提高该值可以让输入变得更加灵敏、也可以绕过碰撞隧道问题,但请记得这么做也会提升 CPU 的占用率。另请参阅 max_fpsProjectSettings.physics/common/physics_ticks_per_second

注意:每个渲染帧最多只能模拟 max_physics_steps_per_frame 个物理周期。如果为了追赶渲染,需要在每个渲染帧中模拟更多物理周期,游戏看上去会是降速的(即便在物理计算中始终使用 delta)。因此,如果增大了 physics_ticks_per_second,而且远大于默认值,那么建议将 max_physics_steps_per_frame 也调大。


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 脚本中,这也会影响编辑器本身。在确保错误消息被启用(默认情况下)之前,要报告错误。


float time_scale = 1.0 🔗

  • void set_time_scale(value: float)

  • float get_time_scale()

游戏内部时钟更新的速度乘数,相对于真实时间。例如设置为 2.0 就会让游戏以二倍速运行,设置为 0.5 就会让游戏以一半的速度运行。

这个值会影响 TimerSceneTreeTimer 以及其他使用 delta 时间进行的仿真(例如 Node._processNode._physics_process)。

注意:建议让这个属性保持大于 0.0,否则可能导致游戏产生意外的行为。

注意:这个属性不会影响音频的播放。请使用 AudioServer.playback_speed_scale 来调整音频播放的速度,配合 time_scale

注意:这个属性不会自动调整 physics_ticks_per_second。大于 1.0 时可能导致物理仿真精度的下降,因为每个物理周期都会被拉伸到覆盖引擎中的一大段时间。修改 time_scale 大幅加速仿真速度时,请考虑同时增大 physics_ticks_per_second,让仿真更可靠。


方法说明

String get_architecture_name() const 🔗

返回构建 Godot 二进制文件所针对的 CPU 架构的名称。可能的返回值有 "x86_64""x86_32""arm64""arm32""rv64""riscv""ppc64""ppc""wasm64""wasm32"

要检测当前构建是否为 64 位,可以利用所有 64 位架构名称中都包含 64

if "64" in Engine.get_architecture_name():
    print("正在运行 64 位 Godot。")
else:
    print("正在运行 32 位 Godot。")

注意:该方法不返回系统 CPU 架构的名称(如 OS.get_processor_name)。例如在 x86_64 系统上运行 x86_32 Godot 二进制文件时,返回值仍为 "x86_32"


Dictionary get_author_info() const 🔗

Dictionary 形式返回引擎作者信息,其中每个条目都是一个字符串 Array,其中包含 Godot 引擎著名贡献者的姓名:lead_developersfoundersproject_managersdevelopers


返回包含 Godot 源码组件版权信息的字典的 Array

每个 Dictionary 中都包含了名称标识符 name 以及另一个字典数组 parts。后者详细描述了对应的组件,包含的字段如下:

  • files - 受到该组件影响的源码文件路径 Array

  • copyright - 该组件的所有者 Array

  • license - 该组件适用的协议(例如 "Expat" 或 "CC-BY-4.0")。


Dictionary get_donor_info() const 🔗

返回分类捐赠者姓名的 Dictionary。每个条目都是一个字符串 Array

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


int get_frames_drawn() 🔗

返回自引擎启动以来绘制的帧的总数。

注意:在无头平台上,或者如果通过命令行使用 --disable-render-loop 禁用渲染,则该方法始终返回 0。请参阅 get_process_frames


float get_frames_per_second() const 🔗

返回每秒渲染的平均帧数(FPS),也被称为帧速率。


Dictionary get_license_info() const 🔗

返回 Godot 和包含的第三方组件使用的许可证的 Dictionary。每个条目都是一个许可证名称(例如 "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 个物理帧仅运行一次昂贵的逻辑。

float get_physics_interpolation_fraction() const 🔗

返回渲染帧时当前物理周期中的分数。可用于实现固定的时间步插值。


int get_process_frames() const 🔗

返回自引擎启动以来经过的总帧数,无论渲染循环是否启用,每个处理帧都会增加该数字。另见 get_frames_drawnget_physics_frames

get_process_frames 可用于在不依赖 Timer 的情况下,减少运行昂贵的逻辑的次数:

func _process(_delta):
    if Engine.get_process_frames() % 2 == 0:
        pass # 此处每 2 个处理(渲染)帧仅运行一次昂贵的逻辑。

ScriptLanguage get_script_language(index: int) const 🔗

返回给定索引 index 处的 ScriptLanguage 实例。


int get_script_language_count() 🔗

返回可用脚本语言的数量。请配合 get_script_language 使用。


Object get_singleton(name: StringName) const 🔗

返回具有给定 name 的全局单例,如果不存在则返回 null。常用于插件。另见 has_singleton and get_singleton_list

注意:全局单例与自动加载的节点不同,后者可以在项目设置中进行配置。


PackedStringArray get_singleton_list() const 🔗

返回所有可用全局单例的名称列表。另见 get_singleton


Dictionary get_version_info() const 🔗

以包含以下条目的 Dictionary 形式返回当前引擎版本信息:

  • major - 主要版本号为一个 int;

  • minor - 次要版本号为一个 int;

  • patch - 补丁版本号为一个 int;

  • hex - 完整版本被编码为一个十六进制 int,每个数字一个字节(2 个十六进制数字)(参见下面的示例);

  • status - 状态(例如“beta”、“rc1”、“rc2”、“stable” 等)为一串字符串;

  • build - 构建名称(例如 “custom_build”)为一串字符串;

  • hash - 完整的 Git 提交哈希为一串字符串;

  • timestamp - 以秒为单位,以 int 形式保存 Git 提交日期 UNIX 时间戳,如果不可用,则保存为 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 之前版本的操作。

String get_write_movie_path() const 🔗

返回 MovieWriter 的输出文件的路径,如果引擎未在 Movie Maker 模式下启动,则返回一个空字符串。该默认路径可以在 ProjectSettings.editor/movie_writer/movie_file 中更改。


bool has_singleton(name: StringName) const 🔗

如果全局范围内存在具有给定 name 的单例,则返回 true。另见 get_singleton

print(<