Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Engine

继承: Object

提供对引擎属性的访问。

描述

Engine 单例使你可以查询和修改项目的运行时参数,例如每秒帧数,时间范围等。

属性

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

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 ( int index ) const

int

get_script_language_count ( )

Object

get_singleton ( StringName name ) const

PackedStringArray

get_singleton_list ( ) const

Dictionary

get_version_info ( ) const

String

get_write_movie_path ( ) const

bool

has_singleton ( StringName name ) const

bool

is_editor_hint ( ) const

bool

is_in_physics_frame ( ) const

Error

register_script_language ( ScriptLanguage language )

void

register_singleton ( StringName name, Object instance )

Error

unregister_script_language ( ScriptLanguage language )

void

unregister_singleton ( StringName name )


属性说明

int max_fps = 0

  • void set_max_fps ( int value )

  • int get_max_fps ( )

每秒可渲染的最大帧数。值为 0 表示“无限制”。如果 CPU 或 GPU 跟不上项目逻辑和渲染的速度,实际的每秒帧数仍可能低于这个值。

限制 FPS 会对降低系统功耗很有帮助,可以减少热量和噪音排放(并延长移动设备的电池寿命)。

如果 ProjectSettings.display/window/vsync/vsync_modeEnabledAdaptive ,则该设置将被优先考虑,并且强制的 FPS 数不能超过显示器的刷新率。

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

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

另见 physics_ticks_per_secondProjectSettings.application/run/max_fps


int max_physics_steps_per_frame = 8

  • void set_max_physics_steps_per_frame ( int value )

  • 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 ( float value )

  • float get_physics_jitter_fix ( )

控制物理周期与实际时间的同步程度。如果小于等于 0,则周期是同步的。这样的值建议用于网络游戏,因为时钟的同步性很重要。较高的值会导致游戏中的时钟和真实时钟之间的偏差较大,但可以平滑帧速率的抖动。默认值 0.5 对于大多数人来说应该足够好了;超过 2 的值可能导致游戏对掉帧的反应有明显的延迟,因此不推荐使用。

注意:为了获得最佳效果,当使用自定义物理插值这种解决方案时,应通过将 physics_jitter_fix 设置为 0 来禁用物理抖动修复。


int physics_ticks_per_second = 60

  • void set_physics_ticks_per_second ( int value )

  • 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 ( bool value )

  • bool is_printing_error_messages ( )

如果为 false,则停止向控制台和编辑器输出日志打印错误和警告消息。这可用于在单元测试套件运行期间隐藏错误和警告消息。该属性等效于 ProjectSettings.application/run/disable_stderr 项目设置。

警告:如果在项目的任何地方将该项设置为 false,重要的错误消息可能会被隐藏,即使它们是从其他脚本发出的。如果在 @tool 脚本中将该项设置为 false,这也会影响编辑器本身。在确保错误消息被启用(默认情况下)之前,报告错误。

注意:从编辑器运行项目时,该属性不会影响编辑器的“错误”选项卡。


float time_scale = 1.0

  • void set_time_scale ( float value )

  • float get_time_scale ( )

控制游戏中的时钟与现实生活中的时钟的快慢。默认值为 1.0。值为 2.0 意味着游戏的移动速度是现实生活的两倍,而值为 0.5 意味着游戏的移动速度是常规速度的一半。TimerSceneTreeTimer 也会受到影响(如何控制见 SceneTree.create_timer)。


方法说明

String get_architecture_name ( ) const

返回构建 Godot 二进制文件所针对的 CPU 架构的名称。可能的返回值有 x86_64x86_32arm64arm32rv64riscvppc64ppcwasm64wasm32

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

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

注意:get_architecture_name 返回的不是主机 CPU 架构的名称。例如,如果在 x86_64 系统上运行 x86_32 的 Godot 二进制文件,那么返回值将是 x86_32


Dictionary get_author_info ( ) const

返回一个字典中的引擎作者信息。

lead_developers - 字符串的数组,主要开发者的名字

founders - 创始人姓名的字符串数组

project_managers - 项目经理姓名的字符串数组

developers - 开发者名称的字符串数组


返回一个版权信息字典数组。

name - 字符串,组件名称。

partic - 描述组件子部分的字典数组 {files, copyright, license}


Dictionary get_donor_info ( ) const

返回捐赠者姓名数组的字典。

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


int get_frames_drawn ( )

返回绘制的总帧数。在无头平台上,或者如果通过命令行使用 --disable-render-loop 禁用渲染循环,get_frames_drawn 总是返回 0。请参阅 get_process_frames


float get_frames_per_second ( ) const

返回运行游戏的每秒帧数。


Dictionary get_license_info ( ) const

返回 Godot 所使用的许可证的 Dictionary 字典列表,其中包括第三方组件。


String get_license_text ( ) const

返回Godot许可证文本。


MainLoop get_main_loop ( ) const

返回主循环对象(请参阅MainLoopSceneTree)。


int get_physics_frames ( ) const

返回自引擎初始化以来通过的总帧数,该帧数在每个物理帧上行进。参阅 get_process_frames

get_physics_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 ( int index ) const

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


int get_script_language_count ( )

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


Object get_singleton ( StringName name ) const

返回具有给定名称 name 的全局单例。常用于插件,例如 GodotPayments。


PackedStringArray get_singleton_list ( ) const

返回可用全局单例的列表。


Dictionary get_version_info ( ) const

以字典形式返回当前引擎版本信息。

major - 将主要版本号保存为一个 int

minor - 将次要版本号保存为一个 int

patch - 将补丁版本号保存为一个 int

hex - 保存编码为十六进制整数的完整版本号,每个数字一个字节(2 位)(参见下面的示例)

status - 将状态(例如“beta”、“rc1”、“rc2”、...“stable”)保存为字符串

build - 将构建名称(例如“custom_build”)保存为字符串

hash - 将完整的 Git 提交哈希保存为字符串

year - 将版本发布的年份保存为 int

string - 将 major + minor + patch + status + build 保存在单个字符串中

hex 值的编码方式如下,从左到右:主版本对应一字节,次版本对应一字节,补丁版本对应一字节。例如,“3.1.12”将是 0x03010C注意:它内部还是一个 int,打印出来就是它的十进制表示,没有特别的意义。使用十六进制文字从代码中轻松比较版本:

if Engine.get_version_info().hex >= 0x030200:
    # 执行特定于版本 3.2 或更高版本的操作
else:
    # 执行特定于 3.2 之前版本的操作

String get_write_movie_path ( ) const

返回 MovieWriter 的输出文件的路径,如果引擎未在 Movie Maker 模式下启动,则返回一个空字符串。该路径可以是绝对路径或相对路径,具体取决于用户指定它的方式。


bool has_singleton ( StringName name ) const

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


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_in_physics_frame ( ) const

如果游戏在游戏循环的固定过程和物理阶段内,返回 true


Error register_script_language ( ScriptLanguage language )

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

返回:


void register_singleton ( StringName name, Object instance )

将给定的对象注册为单例,名称 name 全局可用。


Error unregister_script_language ( ScriptLanguage language )

ScriptServer 注销该 ScriptLanguage 实例。

返回:


void unregister_singleton ( StringName name )

将名称为 name 的单例解除注册。该单例对象不会被释放。仅能够对通过 register_singleton 创建的用户定义单例使用。