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.

Checking the stable version of the documentation...

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

方法

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 数不能超过显示器的刷新率。

如果 ProjectSettings.display/window/vsync/vsync_mode 为 Enabled，在启用了可变刷新率（G-Sync/FreeSync）的显示器上，使用比显示器刷新率低几帧的 FPS 限制，将减少输入延迟，同时可以避免撕裂。

另见 physics_ticks_per_second 和 ProjectSettings.application/run/max_fps。

注意：如果CPU或GPU跟不上项目的逻辑和渲染，则每秒的实际帧数可能仍低于该值。

注意：如果 ProjectSettings.display/window/vsync/vsync_mode 为 Disabled，则与无上限的帧率相比，将 FPS 限制为可以在系统上持续达到的较高值，可以减少输入滞后。由于这是通过确保 GPU 负载低于 100% 来实现的，因此这种延迟减少仅在 GPU 瓶颈场景中有效，在 CPU 瓶颈场景中无效。

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_second 的 1 / 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_fps 和 ProjectSettings.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 脚本中，这也会影响编辑器本身。在确保错误消息被启用（默认情况下）之前，不要报告错误。

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，让仿真更可靠。

方法说明

String get_architecture_name() const 🔗

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

检测当前构建是否为 64 位或检测架构类型时请勿使用架构名称进行判断。请使用 OS.has_feature()，检测 "64" 特性标签，或者 "x86"、"arm" 等标签。详见《特性标签》文档。

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

Dictionary get_author_info() const 🔗

以 Dictionary 形式返回引擎作者信息，其中每个条目都是一个字符串 Array，其中包含 Godot 引擎著名贡献者的姓名：lead_developers、founders、project_managers 和 developers。

返回包含 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_drawn() 和 get_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(Engine.has_singleton("OS"))          # 输出 true
print(Engine.has_singleton("Engine"))      # 输出 true
print(Engine.has_singleton("AudioServer")) # 输出 true
print(Engine.has_singleton("Unknown"))     # 输出 false

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

bool is_editor_hint() const 🔗

如果脚本当前正在编辑器中运行，则返回 true，否则返回 false。这对于 @tool 脚本很有用，可以有条件地绘制编辑器助手，或者防止在编辑器中意外运行会影响场景状态的“游戏”代码：

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

有关详细信息，请参阅文档中的《在编辑器中运行代码》。

注意：要检测脚本是否在编辑器构建上运行（例如，当按 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()) # 输出 false

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

Error register_script_language(language: ScriptLanguage) 🔗

注册一个 ScriptLanguage 实例，供 ScriptServer 使用。

返回：

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

将给定的 Object instance 注册为单例，在名称 name 下全局可用。对于插件很有用。

Error unregister_script_language(language: ScriptLanguage) 🔗

从 ScriptServer 注销该 ScriptLanguage 实例。

返回：

void unregister_singleton(name: StringName) 🔗

移除在 name 下注册的单例。该单例对象不会被释放。仅适用于使用 register_singleton() 注册的用户定义的单例。