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`

方法

Array[ScriptBacktrace]	capture_script_backtraces(include_variables: bool = false) const
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 數不能超過顯示器的刷新率。另見 DisplayServer.screen_get_refresh_rate()。

如果 ProjectSettings.display/window/vsync/vsync_mode 為 Enabled，在啟用了可變刷新率（G-Sync/FreeSync）的顯示器上，使用比顯示器刷新率低幾影格的 FPS 限制，將減少輸入延遲，同時可以避免撕裂。在較高的刷新率下，應增大影格率限制與顯示器刷新率之間的差值，以確保有足夠的影格數來彌補計時誤差。在這種情況下，影格率限制值的最佳公式為 r - (r * r) / 3600.0，其中 r 是顯示器的刷新率。

注意：如果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() 的執行頻率。

CPU 使用率大致與物理週期頻率成正比。然而，在週期頻率非常低（通常低於 30）的情況下，物理行為可能會出現異常。在低週期頻率下，輸入響應也會變得遲鈍，因為輸入被注冊到系統和系統在下一個物理週期做出響應之間會存在延遲。較高的週期頻率可以提供更精確的物理模擬，尤其對於快速移動的物體而言。例如，賽車遊戲可以通過將週期頻率提高到高於預設的 60 來獲得更好的效果。

另見 max_fps 和 ProjectSettings.physics/common/physics_ticks_per_second。

注意：每個渲染影格最多只能模擬 max_physics_steps_per_frame 個物理週期。如果為了追趕渲染，需要在每個渲染影格中模擬更多物理週期，遊戲看上去會是降速的（即便在物理計算中始終使用 delta）。因此，如果增大了 physics_ticks_per_second，而且遠大於預設值，那麼建議將 max_physics_steps_per_frame 也調大。

注意：如果你將 physics_ticks_per_second 的值更改為不是 60 的倍數的值，請考慮啟用物理插值。使用物理插值可以避免顯示器刷新率和物理更新速率不完全匹配時出現的畫面抖動。

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

方法說明

Array[ScriptBacktrace] capture_script_backtraces(include_variables: bool = false) const 🔗

捕獲並回傳所有注冊腳本語言的追蹤資訊。

預設情況下，回傳的 ScriptBacktrace 僅在編輯器建置和除錯建置中包含堆疊影格。要在發佈建置中也啟用，就需要啟用 ProjectSettings.debug/settings/gdscript/always_track_call_stacks。

如果 include_variables 為 true，則追蹤資訊中還包括捕獲時的所有全域變數（例如自動載入的單例）的名稱和值，以及各個堆疊影格中的區域變數和類成員變數。不過這個參數只有在執行遊戲時附加了除錯器的情況下才會生效，例如從編輯器執行遊戲。要在匯出建置中也啟用此功能，就需要啟用 ProjectSettings.debug/settings/gdscript/always_track_local_variables。

警告：當 include_variables 為 true 時，捕獲的變數可能是變數中的實際值（例如 GDScript 的追蹤資訊），包含物件參照。這意味著儲存這樣的 ScriptBacktrace 會阻止這些物件的釋放，因此通常不建議這麼做。

String get_architecture_name() const 🔗

回傳建置 Godot 二進位檔案所針對的 CPU 架構的名稱。可能的回傳值有 "x86_64"、"x86_32"、"arm64"、"arm32"、"rv64"、"ppc64"、"loongarch64"、"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。

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 的情況下，減少執行昂貴的邏輯的次數：

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

此方法可用於在不依賴 Timer 的情況下，減少執行昂貴的邏輯的次數：

func _process(_delta):
    if Engine.get_process_frames() % 5 == 0:
        pass # 此處每 5 個處理（渲染）影格僅執行一次昂貴的邏輯。

public override void _Process(double delta)
{
    base._Process(delta);

    if (Engine.GetProcessFrames() % 5 == 0)
    {
        // 此處每 5 個處理（渲染）影格僅執行一次昂貴的邏輯。
    }
}

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

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

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 腳本很有用，可以有條件地繪製編輯器助手，或者防止在編輯器中意外執行會影響場景狀態的“遊戲”程式碼：

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

回傳：

@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() 注冊的使用者定義的單例。