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.

SceneTree

繼承: MainLoop < Object

通過節點層次結構管理遊戲迴圈。

說明

作為最重要的類之一,SceneTree 管理著場景中節點的層次結構以及場景本身。節點可以進行新增、取得、移除等操作。整個場景樹都可以暫停(因此目前場景也可以暫停)。場景可以載入、切換、重新載入。

你還可以使用 SceneTree 將節點分組管理:你想要建立多少分組都可以,每個節點都可以新增到若干個組中,例如“敵人”組。然後你可以遍歷這些分組,甚至可以對指定分組中的所有節點執行呼叫方法、設定屬性等操作。

SceneTree 是引擎所使用的預設 MainLoop 實作,因此負責遊戲循環。

教學

屬性

bool

auto_accept_quit

true

Node

current_scene

bool

debug_collisions_hint

false

bool

debug_navigation_hint

false

bool

debug_paths_hint

false

Node

edited_scene_root

bool

multiplayer_poll

true

bool

paused

false

bool

physics_interpolation

false

bool

quit_on_go_back

true

Window

root

方法

void

call_group(group: StringName, method: StringName, ...) vararg

void

call_group_flags(flags: int, group: StringName, method: StringName, ...) vararg

Error

change_scene_to_file(path: String)

Error

change_scene_to_node(node: Node)

Error

change_scene_to_packed(packed_scene: PackedScene)

SceneTreeTimer

create_timer(time_sec: float, process_always: bool = true, process_in_physics: bool = false, ignore_time_scale: bool = false)

Tween

create_tween()

Node

get_first_node_in_group(group: StringName)

int

get_frame() const

MultiplayerAPI

get_multiplayer(for_path: NodePath = NodePath("")) const

int

get_node_count() const

int

get_node_count_in_group(group: StringName) const

Array[Node]

get_nodes_in_group(group: StringName)

Array[Tween]

get_processed_tweens()

bool

has_group(name: StringName) const

bool

is_accessibility_enabled() const

bool

is_accessibility_supported() const

void

notify_group(group: StringName, notification: int)

void

notify_group_flags(call_flags: int, group: StringName, notification: int)

void

queue_delete(obj: Object)

void

quit(exit_code: int = 0)

Error

reload_current_scene()

void

set_group(group: StringName, property: String, value: Variant)

void

set_group_flags(call_flags: int, group: StringName, property: String, value: Variant)

void

set_multiplayer(multiplayer: MultiplayerAPI, root_path: NodePath = NodePath(""))

void

unload_current_scene()


訊號

node_added(node: Node) 🔗

當 node 進入該樹時發出。


node_configuration_warning_changed(node: Node) 🔗

當 node 的 Node.update_configuration_warnings() 被呼叫時發出。僅在編輯器中發出。


node_removed(node: Node) 🔗

當 node 退出該樹時發出。


node_renamed(node: Node) 🔗

當 node 的 Node.name 被更改時發出。


physics_frame() 🔗

在該樹中的每個節點上呼叫 Node._physics_process() 之前立即發出。


process_frame() 🔗

在該樹中的每個節點上呼叫 Node._process() 之前立即發出。


scene_changed() 🔗

新場景新增到場景樹中並完成初始化後發出。切換場景時可以用這個訊號來穩定地存取 current_scene。

# 這段程式碼應當寫在自動載入里。
get_tree().change_scene_to_file(other_scene_path)
await get_tree().scene_changed
print(get_tree().current_scene) # 輸出新場景。

tree_changed() 🔗

每當該樹的層次結構發生變化(節點被移動、重新命名等)時發出。


tree_process_mode_changed() 🔗

當樹內任意節點的 Node.process_mode 更改時觸發。僅在編輯器中觸發,以更新停用節點的可見性。


列舉

enum GroupCallFlags: 🔗

GroupCallFlags GROUP_CALL_DEFAULT = 0

沒有特殊行為地呼叫組內的節點(預設)。

GroupCallFlags GROUP_CALL_REVERSE = 1

按相反的樹層次結構順序呼叫組內的節點(所有巢狀子節點都在其各自的父節點之前呼叫)。

GroupCallFlags GROUP_CALL_DEFERRED = 2

在目前影格(可以是處理影格或物理影格)末尾呼叫組內的節點,類似於 Object.call_deferred()。

GroupCallFlags GROUP_CALL_UNIQUE = 4

即使在同一影格中執行多次,也僅呼叫組內的節點一次。必須與 GROUP_CALL_DEFERRED 結合使用才能工作。

注意:不考慮不同的參數。因此,當使用不同的參數執行相同的呼叫時,只會執行第一個呼叫。


屬性說明

bool auto_accept_quit = true 🔗

  • void set_auto_accept_quit(value: bool)

  • bool is_auto_accept_quit()

如果為 true,則套用程式會自動接受退出請求。

移動平臺見 quit_on_go_back。


Node current_scene 🔗

  • void set_current_scene(value: Node)

  • Node get_current_scene()

目前載入的主場景的根節點,通常是 root 的直接子節點。另見 change_scene_to_file()、change_scene_to_packed()、reload_current_scene()。

警告:直接設定該屬性可能無法正常工作,因為這樣不會在場景樹中新增刪除節點。


bool debug_collisions_hint = false 🔗

  • void set_debug_collisions_hint(value: bool)

  • bool is_debugging_collisions_hint()

If true, collision shapes will be visible when running the game from the editor for debugging purposes.


bool debug_navigation_hint = false 🔗

  • void set_debug_navigation_hint(value: bool)

  • bool is_debugging_navigation_hint()

如果為 true,從編輯器中運作遊戲時會顯示導覽多邊形,方便除錯。

注意:這個屬性不應在運作時更改。在運作專案時更改 debug_navigation_hint 的值不會有想要的效果。


bool debug_paths_hint = false 🔗

  • void set_debug_paths_hint(value: bool)

  • bool is_debugging_paths_hint()

如果為 true,從編輯器中運作遊戲時,來自 Path2D 和 Path3D 節點的曲線將可見以進行除錯。

注意:該屬性沒有被設計為在運作時更改。在專案運作時更改 debug_paths_hint 的值不會產生預期的效果。


Node edited_scene_root 🔗

  • void set_edited_scene_root(value: Node)

  • Node get_edited_scene_root()

編輯器中目前正在編輯場景的根節點。通常是 root 的直接子節點。

注意:該屬性在發佈版本中不起任何作用。


bool multiplayer_poll = true 🔗

  • void set_multiplayer_poll_enabled(value: bool)

  • bool is_multiplayer_poll_enabled()

如果為 true(預設值),則在 process_frame 期間為該 SceneTree 啟用 MultiplayerAPI 的自動輪詢。

如果為 false,則需要手動呼叫 MultiplayerAPI.poll() 以處理網路封包並下發 RPC。這允許在一個不同的迴圈(例如物理、執行緒、特定時間步長)中運作 RPC,並在從執行緒存取 MultiplayerAPI 時進行手動 Mutex 保護。


bool paused = false 🔗

  • void set_pause(value: bool)

  • bool is_paused()

如果為 true,則會將場景樹視為已暫停,會導致下列行為:


bool physics_interpolation = false 🔗

  • void set_physics_interpolation_enabled(value: bool)

  • bool is_physics_interpolation_enabled()

如果為 true,則渲染器將在最後兩個變換之間插入物件的變換(無論該物件為物理物件還是非物理物件),這樣即使物理刻度與渲染影格不一致,也能看到平滑的運動。

該屬性的預設值由 ProjectSettings.physics/common/physics_interpolation 控制。

注意:儘管這是全域設定,仍可使用 Node.physics_interpolation_mode 對 SceneTree 中的分支進行精細的控制。


bool quit_on_go_back = true 🔗

  • void set_quit_on_go_back(value: bool)

  • bool is_quit_on_go_back()

如果為 true,則該套用程式會在導覽返回時自動退出(例如在 Android 上使用系統“返回”鍵)。

停用這個選項時,如果要處理“返回”按鈕,請使用 DisplayServer.WINDOW_EVENT_GO_BACK_REQUEST。


Window root 🔗

場景樹的根 Window。這是場景樹的最頂層 Node,始終存在。絕對 NodePath 始終從這個節點開始。載入的 current_scene 以及“專案設定”中設定的自動載入可能也是根節點的子節點。

警告:請勿刪除該節點。刪除會導致不穩定的行為並引起崩潰。


方法說明

void call_group(group: StringName, method: StringName, ...) vararg 🔗

在該樹內新增到給定 group的每個節點上呼叫 method。你可以通過在該方法呼叫末尾指定參數來將參數傳遞給 method。無法呼叫 method 的節點(因為該方法不存在或參數不匹配)將被忽略。另見 set_group() 和 notify_group()。

注意:該方法立即作用於所有選定的節點,這可能會在某些效能密集型情況下導致卡頓。

注意:在 C# 中,當參照內建的 Godot 方法時,method 必須使用 snake_case。最好使用 MethodName 類中公開的名稱,以避免在每次呼叫時分配新的 StringName。


void call_group_flags(flags: int, group: StringName, method: StringName, ...) vararg 🔗

在樹內新增到給定 group 的每個節點上呼叫給定的 method。使用 flags 自訂該方法的行為(請參閱 GroupCallFlags)。method 的附加參數可以在該方法的末尾傳遞。無法呼叫 method 的節點(因為該方法不存在或參數不匹配)將被忽略。

# 在影格末尾以相反的樹順序,在 “enemies” 組的所有節點上呼叫 “hide”。
get_tree().call_group_flags(
        SceneTree.GROUP_CALL_DEFERRED | SceneTree.GROUP_CALL_REVERSE,
        "enemies", "hide")

注意:在 C# 中,當參照內建的 Godot 方法時,method 必須使用 snake_case。最好使用 MethodName 類中公開的名稱,以避免在每次呼叫時分配新的 StringName。


Error change_scene_to_file(path: String) 🔗

將位於給定路徑 path 的場景載入為一個 PackedScene 並建立新實例,然後將正在執行的場景修改為這個場景。

成功時回傳 @GlobalScope.OK;如果 path 不能被載入為一個 PackedScene ,則回傳 @GlobalScope.ERR_CANT_OPEN;如果該場景無法被實例化,則回傳 @GlobalScope.ERR_CANT_CREATE。

注意:有關操作順序的詳細資訊,請參閱 change_scene_to_node()。


Error change_scene_to_node(node: Node) 🔗

將正在執行的場景切換為給定的 Node。當你希望在切換前設定新場景時非常有用。

成功時返回 @GlobalScope.OK,node 為 null 時返回 @GlobalScope.ERR_INVALID_PARAMETER,node 已經在場景樹中時返回 @GlobalScope.ERR_UNCONFIGURED。

注意:當 change_scene_to_node() 被呼叫時,操作按以下順序發生:

  1. 目前場景節點被立即從樹中移除。從那時起,在目前(即將退出)場景上呼叫的 Node.get_tree() 將返回 null。current_scene 也將變為 null,因為新場景尚不可用。

  2. 在影格末尾時,已從樹中移除的、之前的目前場景將被刪除(從記憶體中釋放),然後新場景節點將被新增到樹中。Node.get_tree() 和 current_scene 將恢復正常工作。

這確保了兩個場景不會同時執行,並且仍然會以類似於 Node.queue_free() 的安全方式釋放之前的場景。

如果你想要穩定地存取新場景,請等待 scene_changed 訊號。

警告: 使用此方法之後,SceneTree 將獲得該節點的所有權,並在再次切換場景時自動釋放它。你對該節點的一切參照都將失效。


Error change_scene_to_packed(packed_scene: PackedScene) 🔗

將正在執行的場景切換為指定 PackedScene (必須有效)的一個新實例。

成功時回傳 @GlobalScope.OK;如果該場景無法被實例化,則回傳 @GlobalScope.ERR_CANT_CREATE。如果場景無效,則回傳 @GlobalScope.ERR_INVALID_PARAMETER。

注意:有關操作順序的詳細資訊,請參閱 change_scene_to_node()。


SceneTreeTimer create_timer(time_sec: float, process_always: bool = true, process_in_physics: bool = false, ignore_time_scale: bool = false) 🔗

回傳一個新的 SceneTreeTimer。在以秒為單位的 time_sec 過去後,該計時器將發出 SceneTreeTimer.timeout 並自動釋放。

如果 process_always 為 false,則當將 paused 設定為 true 時,該計時器將被暫停。

如果 process_in_physics 為 true,則該計時器將在物理影格結束時,而不是在過程影格結束時更新。

如果 ignore_time_scale 為 true,則該計時器將忽略 Engine.time_scale 並使用實際的、經過的時間更新。

該方法通常用於建立一次性的延遲計時器,如下例所示:

func some_function():
    print("開始")
    await get_tree().create_timer(1.0).timeout
    print("結束")

注意:該計時器總是在樹中的所有節點之後更新。在該計時器更新之前,將呼叫節點的 Node._process() 方法(如果 process_in_physics 被設定為 true,則呼叫 Node._physics_process())。


Tween create_tween() 🔗

建立並回傳在該樹中處理的新的 Tween。該 Tween 將在下一個處理影格或物理影格中自動開始(取決於其 TweenProcessMode)。

注意:使用該方法建立的 Tween 不會被綁定到任何 Node。它可能會繼續工作,直到沒有任何東西可以進行動畫。如果希望在 Node 被釋放時自動終結該 Tween,請使用 Node.create_tween() 或 Tween.bind_node()。


Node get_first_node_in_group(group: StringName) 🔗

回傳樹中找到的第一個加入了 group 分組的 Node,尋找時按照場景層次結構順序。如果沒有找到匹配的節點則回傳 null。另見 get_nodes_in_group()。


int get_frame() const 🔗

回傳程式開始執行之後已經處理了多少個物理處理步驟。測量的不是經過的時間。另見 physics_frame。已渲染的影格數見 Engine.get_process_frames()。


MultiplayerAPI get_multiplayer(for_path: NodePath = NodePath("")) const 🔗

搜尋為給定路徑配置的 MultiplayerAPI,如果不存在,則搜尋父路徑,直到找到一個。如果路徑為空,或沒有找到,則傳回預設值。請請參閱set_multiplayer()。


int get_node_count() const 🔗

回傳該樹中的節點數。


int get_node_count_in_group(group: StringName) const 🔗

回傳分配給給定組的節點數。


Array[Node] get_nodes_in_group(group: StringName) 🔗

回傳一個 Array,其中包含的是樹中所有加入了 group 分組的節點,按照場景層次結構排序。


Array[Tween] get_processed_tweens() 🔗

回傳樹中目前存在的 Tween 的 Array,包括暫停的補間。


bool has_group(name: StringName) const 🔗

如果樹中存在新增到給定組 name 的節點,則回傳 true。


bool is_accessibility_enabled() const 🔗

如果啟用了無障礙特性則回傳 true,此時會主動處理無障礙資訊的更新。


bool is_accessibility_supported() const 🔗

如果作業系統支援無障礙特性且在專案設定中進行了啟用,則回傳 true。


void notify_group(group: StringName, notification: int) 🔗

在樹內新增到該 group 的所有節點上,使用給定 notification 呼叫 Object.notification()。另見 Godot 通知、call_group() 和 set_group()。

注意:該方法立即作用於所有選定的節點,這可能會在某些效能密集型情況下導致卡頓。


void notify_group_flags(call_flags: int, group: StringName, notification: int) 🔗

使用給定的 notification 對新增到 group 的該樹內的所有節點呼叫 Object.notification() 。使用 call_flags 自訂該方法的行為(見 GroupCallFlags)。


void queue_delete(obj: Object) 🔗

將要刪除的給定 obj 排隊,在目前影格末尾呼叫其 Object.free()。該方法與 Node.queue_free() 類似。


void quit(exit_code: int = 0) 🔗

在目前迭代結束時使用退出程式碼 exit_code 退出應用程式。

按照慣例,退出程式碼 0 表示成功,其他退出程式碼均表示出錯。出於可移植性考慮,退出程式碼應該在 0 和 125(含)之間。

注意:這個方法在 iOS 上不起作用。根據 《iOS 人機介面指南》 中的建議,使用者應通過 Home 按鈕關閉應用程式。


Error reload_current_scene() 🔗

重新載入目前活動的場景,將 current_scene 替換為其原始 PackedScene 的新實例。

成功時回傳 @GlobalScope.OK,如果尚未定義 current_scene,則回傳 @GlobalScope.ERR_UNCONFIGURED,如果 current_scene 無法載入到 PackedScene 中,則回傳 @GlobalScope.ERR_CANT_OPEN,如果場景無法實例化,則回傳 @GlobalScope.ERR_CANT_CREATE。


void set_group(group: StringName, property: String, value: Variant) 🔗

將該樹內被新增到給定 group 的所有節點上的給定 property 設定為 value。沒有 property 的節點將被忽略。另見 call_group() 和 notify_group()。

注意:該方法立即作用於所有選定的節點上,這可能會在某些效能密集型的情況下導致卡頓。

注意:在 C# 中,在參照 Godot 內建屬性時,property 必須是 snake_case。最好使用 PropertyName 類中公開的名稱,以避免在每次呼叫時分配一個新的 StringName。


void set_group_flags(call_flags: int, group: StringName, property: String, value: Variant) 🔗

將該樹內被新增到給定 group 的所有節點上的給定 property 設定為 value。沒有 property 的節點將被忽略。使用 call_flags 自訂該方法的行為(請參閱 GroupCallFlags)。

注意:在 C# 中,在參照 Godot 內建方法時,property 必須是 snake_case。最好使用 SignalName 類中公開的名稱,以避免在每次呼叫時分配一個新的 StringName。


void set_multiplayer(multiplayer: MultiplayerAPI, root_path: NodePath = NodePath("")) 🔗

用給定的 root_path 設定自訂的 MultiplayerAPI(同時控制相對的子路徑),如果 root_path 為空,則會覆蓋預設值。

注意:MultiplayerAPI 不能為包含 root_path 的子路徑設定,巢狀的自訂多人遊戲是不被允許的。例如,如果為 "/root/Foo" 設定了一項,則為 "/root/Foo/Bar" 設定一項將導致錯誤。

注意:set_multiplayer() 應該在根路徑 root_path 下的子節點就緒之前呼叫。如果在自訂多人 API 設定之前將 MultiplayerSpawner、MultiplayerSynchronizer 這樣的多人節點新增到樹中,這些節點將無法正常工作。


void unload_current_scene() 🔗

如果目前場景已載入,呼叫此方法將進行解除安裝。