Up to date

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

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	quit_on_go_back	`true`
Window	root

方法¶

void	call_group ( StringName group, StringName method, ... ) vararg
void	call_group_flags ( int flags, StringName group, StringName method, ... ) vararg
Error	change_scene_to_file ( String path )
Error	change_scene_to_packed ( PackedScene packed_scene )
SceneTreeTimer	create_timer ( float time_sec, bool process_always=true, bool process_in_physics=false, bool ignore_time_scale=false )
Tween	create_tween ( )
Node	get_first_node_in_group ( StringName group )
int	get_frame ( ) const
MultiplayerAPI	get_multiplayer ( NodePath for_path=NodePath("") ) const
int	get_node_count ( ) const
Node[]	get_nodes_in_group ( StringName group )
Tween[]	get_processed_tweens ( )
bool	has_group ( StringName name ) const
void	notify_group ( StringName group, int notification )
void	notify_group_flags ( int call_flags, StringName group, int notification )
void	queue_delete ( Object obj )
void	quit ( int exit_code=0 )
Error	reload_current_scene ( )
void	set_group ( StringName group, String property, Variant value )
void	set_group_flags ( int call_flags, StringName group, String property, Variant value )
void	set_multiplayer ( MultiplayerAPI multiplayer, NodePath root_path=NodePath("") )
void	unload_current_scene ( )

信号¶

node_added ( Node node )

当将节点添加到 SceneTree 时发出。

node_configuration_warning_changed ( Node node )

当节点的配置更改时发出。仅在 tool 模式下发射。

node_removed ( Node node )

当从 SceneTree 中移除节点时发出。

node_renamed ( Node node )

当节点重命名时发出。

physics_frame ( )

在 SceneTree 中的每个节点上调用 Node._physics_process 之前立即发出。

process_frame ( )

在对 SceneTree 中的每个节点调用 Node._process 之前立即发出。

tree_changed ( )

当 SceneTree 层次结构发生变化（移动或重命名子项等）时发出。

tree_process_mode_changed ( )

该信号仅在编辑器中发出，允许编辑器更新被禁用节点的可见性。任何节点的 Node.process_mode 更改时发出。

枚举¶

enum GroupCallFlags:

GroupCallFlags GROUP_CALL_DEFAULT = 0

对分组进行调用时，不使用标志（默认）。

GroupCallFlags GROUP_CALL_REVERSE = 1

对分组进行调用时，使用逆场景序。

GroupCallFlags GROUP_CALL_DEFERRED = 2

在当前帧的末尾对分组进行调用（处理帧或物理帧）。

GroupCallFlags GROUP_CALL_UNIQUE = 4

即便执行了多次调用，也只对分组进行一次调用。

注意：确定调用是否唯一时不考虑参数。因此，如果使用不同的参数调用了同一个方法，那么只会执行第一个调用。

属性说明¶

bool auto_accept_quit = true

void set_auto_accept_quit ( bool value )
bool is_auto_accept_quit ( )

如果为 true，则应用程序会自动接受退出请求。

移动平台见 quit_on_go_back。

Node current_scene

void set_current_scene ( Node value )
Node get_current_scene ( )

返回当前运行场景的根节点，无视其结构。

警告：直接设置这个属性可能无法达到预期效果，不会为场景树添加或移除任何节点，请考虑改用 change_scene_to_file 或 change_scene_to_packed。

bool debug_collisions_hint = false

void set_debug_collisions_hint ( bool value )
bool is_debugging_collisions_hint ( )

如果为 true，从编辑器中运行游戏时会显示碰撞形状，方便调试。

注意：这个属性不应在运行时更改。在运行项目时更改 debug_collisions_hint 的值不会有想要的效果。

bool debug_navigation_hint = false

void set_debug_navigation_hint ( bool value )
bool is_debugging_navigation_hint ( )

如果为 true，从编辑器中运行游戏时会显示导航多边形，方便调试。

注意：这个属性不应在运行时更改。在运行项目时更改 debug_navigation_hint 的值不会有想要的效果。

bool debug_paths_hint = false

void set_debug_paths_hint ( bool value )
bool is_debugging_paths_hint ( )

如果为 true，从编辑器中运行游戏时，来自 Path2D 和 Path3D 节点的曲线将可见以进行调试。

注意：该属性没有被设计为在运行时更改。在项目运行时更改 debug_paths_hint 的值不会产生预期的效果。

Node edited_scene_root

void set_edited_scene_root ( Node value )
Node get_edited_scene_root ( )

编辑场景的根。

bool multiplayer_poll = true

void set_multiplayer_poll_enabled ( bool value )
bool is_multiplayer_poll_enabled ( )

如果为 true（默认值），则在 process_frame 期间为该 SceneTree 启用 MultiplayerAPI 的自动轮询。

如果为 false，则需要手动调用 MultiplayerAPI.poll 以处理网络数据包并下发 RPC。这允许在一个不同的循环（例如物理、线程、特定时间步长）中运行 RPC，并在从线程访问 MultiplayerAPI 时进行手动 Mutex 保护。

bool paused = false

void set_pause ( bool value )
bool is_paused ( )

如果为 true，SceneTree 会暂停。这样做会有以下行为：

2D 和 3D 物理将停止，包括信号和碰撞检测。
节点不再调用 Node._process、Node._physics_process 和 Node._input。

bool quit_on_go_back = true

void set_quit_on_go_back ( bool value )
bool is_quit_on_go_back ( )

如果为 true，则该应用程序会在导航返回时自动退出（例如在 Android 上使用系统“返回”键）。

禁用这个选项时，如果要处理“返回”按钮，请使用 DisplayServer.WINDOW_EVENT_GO_BACK_REQUEST。

Window root

Window get_root ( )

SceneTree 的根 Window。

方法说明¶

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

对给定分组的每个成员调用 method。调用方法时在末尾指定的参数会传递给 method。如果节点没有给定的方法或参数列表不匹配（无论是数量还是类型），那么就会跳过这个节点。

注意：call_group 将立即对所有成员调用一次方法，如果对大量成员调用昂贵的方法，这可能会导致卡顿。

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

调用给定分组中每个成员的 method 方法，遵循给定的 GroupCallFlags。你可以在方法调用末尾指定要传递给 method 的参数。如果某个节点没有给定的方法，或者方法的参数列表不匹配（无论是数量还是类型不匹配），则会跳过这个节点。

# 使用延迟方式逆序调用该方法。
get_tree().call_group_flags(SceneTree.GROUP_CALL_DEFERRED | SceneTree.GROUP_CALL_REVERSE)

注意：分组调用标志可用于控制方法调用的行为。默认情况下方法是立即调用的，与 call_group 类似。但是如果在 flags 中存在 GROUP_CALL_DEFERRED 标志，则方法会在该帧末尾调用，与 Object.set_deferred 类似。

Error change_scene_to_file ( String path )

Changes the running scene to the one at the given path, after loading it into a PackedScene and creating a new instance.

Returns @GlobalScope.OK on success, @GlobalScope.ERR_CANT_OPEN if the path cannot be loaded into a PackedScene, or @GlobalScope.ERR_CANT_CREATE if that scene cannot be instantiated.

Note: See change_scene_to_packed for details on the order of operations.

Error change_scene_to_packed ( PackedScene packed_scene )

Changes the running scene to a new instance of the given PackedScene (which must be valid).

Returns @GlobalScope.OK on success, @GlobalScope.ERR_CANT_CREATE if the scene cannot be instantiated, or @GlobalScope.ERR_INVALID_PARAMETER if the scene is invalid.

Note: Operations happen in the following order when change_scene_to_packed is called:

The current scene node is immediately removed from the tree. From that point, Node.get_tree called on the current (outgoing) scene will return null. current_scene will be null, too, because the new scene is not available yet.
At the end of the frame, the formerly current scene, already removed from the tree, will be deleted (freed from memory) and then the new scene will be instantiated and added to the tree. Node.get_tree and current_scene will be back to working as usual.

This ensures that both scenes aren't running at the same time, while still freeing the previous scene in a safe way similar to Node.queue_free.

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

返回一个 SceneTreeTimer，会在 SceneTree 中经过给定秒数后发出 SceneTreeTimer.timeout 信号。

如果 process_always 为 false，则暂停 SceneTree 也会暂停计时器。

如果 process_in_physics 为 true，则将在物理帧而不是处理帧期间更新 SceneTreeTimer（固定帧率处理）。

如果 ignore_time_scale 为 true，则将忽略 Engine.time_scale 并使用实际帧增量来更新 SceneTreeTimer。

通常用于创建一次性的延迟定时器，如下例所示：

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

创建并返回新的 Tween。该 Tween 会在下一个处理帧或物理帧中自动开始（取决于 TweenProcessMode）。

注意：使用这个方法创建 Tween 时，Tween 不会与调用的 Node 绑定。即便在该 Node 释放后也仍然会继续进行动画，但是在已经没有任何可以动画的东西时会自动结束。如果你想要让 Tween 在该 Node 释放时自动销毁，请使用 Node.create_tween 或 Tween.bind_node。

Node get_first_node_in_group ( StringName group )

返回指定组中的第一个节点，如果组为空或不存在，则返回 null。

int get_frame ( ) const

返回当前的帧数，即自应用程序启动以来的总帧数。

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

搜索为给定路径配置的 MultiplayerAPI，如果不存在，则会搜索父路径，直到找到为止。如果路径为空，或者没有找到，则返回默认路径。参见 set_multiplayer。

int get_node_count ( ) const

返回此 SceneTree 中的节点数。

Node[] get_nodes_in_group ( StringName group )

返回一个分配给给定组的所有节点的列表。

Tween[] get_processed_tweens ( )

返回在 SceneTree 中当前存在的 Tween 的数组（包括正在运行的和已暂停的）。

bool has_group ( StringName name ) const

如果存在给定的分组，则返回 true。

场景中存在属于某个分组的 Node 时，该分组才存在（见 Node.add_to_group）。不含任何节点的分组会被自动移除。

void notify_group ( StringName group, int notification )

向 group 中的所有成员发送给定的通知。

注意：notify_group 会立即通知所有成员，如果向大量成员发送了通知，进而调用了开销很大的方法，则可能导致卡顿。

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

将给定的通知发送到 group 中的所有成员，同时遵循给定的 GroupCallFlags。

注意：分组调用标志用于控制通知发送的行为。默认情况下通知会立即发送，类似于 notify_group。但是，如果 call_flags 参数中包含 GROUP_CALL_DEFERRED 标志，则通知将在当前帧的末尾发送，类似于使用 Object.call_deferred("notification", ...)。

void queue_delete ( Object obj )

将给定的对象加入删除队列，将对 Object.free 的调用推迟到当前帧的末尾。

void quit ( int exit_code=0 )

在当前迭代结束时退出应用程序。可以选择给出参数 exit_code（默认为 0），以自定义退出状态代码。

按照惯例，退出代码 0 表示成功，而非零的退出代码表示错误。

出于可移植性的原因，退出代码应设置在 0 到 125（含）之间。

注意：这个方法在 iOS 上不起作用。根据《iOS 人机界面指南》中的建议，用户应该通过 Home 键来关闭应用程序。

Error reload_current_scene ( )

重新加载当前活动的场景。

成功时返回 @GlobalScope.OK，如果尚未定义 current_scene，则返回 @GlobalScope.ERR_UNCONFIGURED，如果 current_scene 无法加载到 PackedScene 中，则返回 @GlobalScope.ERR_CANT_OPEN，如果场景无法加载，则返回 @GlobalScope.ERR_CANT_CREATE。

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

将给定分组中所有成员的 property 设置为 value。

注意：set_group 会立即在所有成员上设置属性，如果对许多成员设置具有大量耗费的 setter 的属性，则可能会导致卡顿。

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

将给定分组中所有成员的 property 设置为 value，设置时会考虑给定的 GroupCallFlags。

注意：分组调用标志可用于控制属性设置的行为。默认情况下会立即设置属性，类似于 set_group。但是，如果在 call_flags 参数中存在 GROUP_CALL_DEFERRED 标志，则属性将在该帧的末尾再设置，类似于 Object.call_deferred。

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

用给定的 root_path 设置自定义的 MultiplayerAPI（同时控制相对的子路径），如果 root_path 为空，则会覆盖默认值。

注意：MultiplayerAPI 不能为包含 root_path 的子路径配置，嵌套的自定义多人游戏是不被允许的。例如，如果为 "/root/Foo" 配置了一项，则为 "/root/Foo/Bar" 设置一项将导致错误。

void unload_current_scene ( )

如果当前场景已加载，调用此方法将进行卸载。