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...
SceneTree
通過節點層次結構管理遊戲迴圈。
說明
作為最重要的類之一,SceneTree 管理著場景中節點的層次結構以及場景本身。節點可以進行新增、取得、移除等操作。整個場景樹都可以暫停(因此目前場景也可以暫停)。場景可以載入、切換、重新載入。
你還可以使用 SceneTree 將節點分組管理:你想要建立多少分組都可以,每個節點都可以新增到若干個組中,例如“敵人”組。然後你可以遍歷這些分組,甚至可以對指定分組中的所有節點執行呼叫方法、設定屬性等操作。
SceneTree 是引擎所使用的預設 MainLoop 實作,因此負責遊戲循環。
教學
屬性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
方法
訊號
當 node 進入該樹時發出。
node_configuration_warning_changed(node: Node) 🔗
當 node 的 Node.update_configuration_warnings() 被呼叫時發出。僅在編輯器中發出。
當 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 🔗
如果為 true,則套用程式會自動接受退出請求。
移動平臺見 quit_on_go_back。
目前載入的主場景的根節點,通常是 root 的直接子節點。另見 change_scene_to_file()、change_scene_to_packed()、reload_current_scene()。
警告:直接設定該屬性可能無法正常工作,因為這樣不會在場景樹中新增刪除節點。
bool debug_collisions_hint = false 🔗
If true, collision shapes will be visible when running the game from the editor for debugging purposes.
如果為 true,從編輯器中運作遊戲時會顯示導覽多邊形,方便除錯。
注意:這個屬性不應在運作時更改。在運作專案時更改 debug_navigation_hint 的值不會有想要的效果。
bool debug_paths_hint = false 🔗
如果為 true,從編輯器中運作遊戲時,來自 Path2D 和 Path3D 節點的曲線將可見以進行除錯。
注意:該屬性沒有被設計為在運作時更改。在專案運作時更改 debug_paths_hint 的值不會產生預期的效果。
編輯器中目前正在編輯場景的根節點。通常是 root 的直接子節點。
注意:該屬性在發佈版本中不起任何作用。
bool multiplayer_poll = true 🔗
如果為 true(預設值),則在 process_frame 期間為該 SceneTree 啟用 MultiplayerAPI 的自動輪詢。
如果為 false,則需要手動呼叫 MultiplayerAPI.poll() 以處理網路封包並下發 RPC。這允許在一個不同的迴圈(例如物理、執行緒、特定時間步長)中運作 RPC,並在從執行緒存取 MultiplayerAPI 時進行手動 Mutex 保護。
如果為 true,則會將場景樹視為已暫停,會導致下列行為:
停止 2D 和 3D 物理,包括碰撞檢測和相關訊號。
可能不再呼叫每個節點的 Node._process()、Node._physics_process()、Node._input() 等回呼方法,具體由各節點的 Node.process_mode 決定。
bool physics_interpolation = false 🔗
如果為 true,則渲染器將在最後兩個變換之間插入物件的變換(無論該物件為物理物件還是非物理物件),這樣即使物理刻度與渲染影格不一致,也能看到平滑的運動。
該屬性的預設值由 ProjectSettings.physics/common/physics_interpolation 控制。
注意:儘管這是全域設定,仍可使用 Node.physics_interpolation_mode 對 SceneTree 中的分支進行精細的控制。
如果為 true,則該套用程式會在導覽返回時自動退出(例如在 Android 上使用系統“返回”鍵)。
停用這個選項時,如果要處理“返回”按鈕,請使用 DisplayServer.WINDOW_EVENT_GO_BACK_REQUEST。
Window get_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() 被呼叫時,操作按以下順序發生:
目前場景節點被立即從樹中移除。從那時起,在目前(即將退出)場景上呼叫的 Node.get_tree() 將返回
null。current_scene 也將變為null,因為新場景尚不可用。在影格末尾時,已從樹中移除的、之前的目前場景將被刪除(從記憶體中釋放),然後新場景節點將被新增到樹中。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("結束")
public async Task SomeFunction()
{
GD.Print("開始");
await ToSignal(GetTree().CreateTimer(1.0f), SceneTreeTimer.SignalName.Timeout);
GD.Print("結束");
}
注意:該計時器總是在樹中的所有節點之後更新。在該計時器更新之前,將呼叫節點的 Node._process() 方法(如果 process_in_physics 被設定為 true,則呼叫 Node._physics_process())。
建立並回傳在該樹中處理的新的 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()。
回傳程式開始執行之後已經處理了多少個物理處理步驟。測量的不是經過的時間。另見 physics_frame。已渲染的影格數見 Engine.get_process_frames()。
MultiplayerAPI get_multiplayer(for_path: NodePath = NodePath("")) const 🔗
搜尋為給定路徑配置的 MultiplayerAPI,如果不存在,則搜尋父路徑,直到找到一個。如果路徑為空,或沒有找到,則傳回預設值。請請參閱set_multiplayer()。
回傳該樹中的節點數。
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() 🔗
如果目前場景已載入,呼叫此方法將進行解除安裝。