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 单例使你可以查询和修改项目的运行时参数，例如每秒帧数，时间范围等。

属性¶

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_mode 为 Enabled 或 Adaptive ，则该设置将被优先考虑，并且强制的 FPS 数不能超过显示器的刷新率。

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

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

另见 physics_ticks_per_second 和 ProjectSettings.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_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 ( 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_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 ( 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 意味着游戏的移动速度是常规速度的一半。Timer 和 SceneTreeTimer 也会受到影响（如何控制见 SceneTree.create_timer）。

方法说明¶

String get_architecture_name ( ) const

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

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

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。");

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

Dictionary get_author_info ( ) const

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

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

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

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

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

Dictionary[] get_copyright_info ( ) const

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

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

返回主循环对象（请参阅MainLoop和SceneTree）。

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 个物理帧仅运行一次昂贵的逻辑。

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

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 ( 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 之前版本的操作

if ((int)Engine.GetVersionInfo()["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()

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

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

注意：要检测脚本是否从编辑器构建中运行（例如，当按 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 使用。

返回：

@GlobalScope.OK 成功
@GlobalScope.ERR_UNAVAILABLE 如果 ScriptServer 已达到限制，并且无法注册任何新语言
@GlobalScope.ERR_ALREADY_EXISTS 如果 ScriptServer 已经包含一个具有相似扩展名/名称/类型的语言

void register_singleton ( StringName name, Object instance )

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

Error unregister_script_language ( ScriptLanguage language )

从 ScriptServer 注销该 ScriptLanguage 实例。

返回：

@GlobalScope.OK 成功
@GlobalScope.ERR_DOES_NOT_EXIST 如果该语言尚未在 ScriptServer 中注册

void unregister_singleton ( StringName name )

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