Engine

继承： Object

提供对引擎属性的访问。

描述

Engine 单例使你可以查询和修改项目的运行时参数，例如每秒帧数，时间缩放等。它还存储有关 Godot 当前构建的信息，例如当前版本。

属性

方法

属性说明

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

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 位，可以利用所有 64 位架构名称中都包含 64：

GDScriptC#

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

if (Engine.GetArchitectureName().Contains("64"))
    GD.Print("正在运行 64 位 Godot。");
else
    GD.Print("正在运行 32 位 Godot。");

注意：该方法不返回系统 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。

Array[Dictionary] get_copyright_info() const 🔗

返回包含 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 的情况下，减少运行昂贵的逻辑的次数：

GDScriptC#

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。

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

GDScriptC#

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

public override void _Process(double delta)
{
    base._Process(delta);
    if (Engine.GetProcessFrames() % 2 == 0)
    {
        // 此处每 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，打印出来就是它的十进制表示，没有特别的意义。使用十六进制文字从代码中快速比较版本：

GDScriptC#

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 🔗

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

GDScriptC#

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

GD.Print(Engine.HasSingleton("OS"));          // 输出 true
GD.Print(Engine.HasSingleton("Engine"));      // 输出 true
GD.Print(Engine.HasSingleton("AudioServer")); // 输出 true
GD.Print(Engine.HasSingleton("Unknown"));     // 输出 false

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

bool is_editor_hint() const 🔗

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

GDScriptC#

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

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

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

注意：要检测脚本是否在编辑器构建上运行（例如，当按 F5 时），请改用 OS.has_feature 和 "editor" 参数。OS.has_feature("editor") 将在编辑器中运行脚本和从编辑器运行项目时，被评估为 true；但当从导出的项目运行时，它将被评估为 false。

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 使用。

返回：

• @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) 🔗

从 ScriptServer 注销该 ScriptLanguage 实例。

返回：

• @GlobalScope.OK 表示成功；

• @GlobalScope.ERR_DOES_NOT_EXIST 表示该语言尚未在 ScriptServer 中注册。

void unregister_singleton(name: StringName) 🔗

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