SceneTree

继承： MainLoop < Object

通过节点层次结构管理游戏循环。

描述

作为最重要的类之一，SceneTree 管理着场景中节点的层次结构以及场景本身。节点可以被添加、检索和删除。整个场景树可以被暂停，包括当前场景。场景可以被加载、切换和重新加载。

你也可以使用 SceneTree 将你的节点组织成组，每个节点都可以被分配到你想要创建的组，例如“敌人”组。然后你可以遍历这些组，甚至可以统一对所有组成员调用方法并设置属性。

SceneTree 是场景所使用的默认 MainLoop 实现，因此掌控着游戏循环。

教程

• SceneTree

• 多分辨率

属性

方法

信号

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 )

将位于给定路径 path 的场景加载进一个 PackedScene 并新建其实例，然后将正在运行的场景修改为这个场景。

成功时返回 @GlobalScope.OK；如果 path 不能被加载到一个 PackedScene 中，则返回 @GlobalScope.ERR_CANT_OPEN；如果该场景无法被实例化，则返回 @GlobalScope.ERR_CANT_CREATE。

注意：有关操作顺序的详细信息，请参阅 change_scene_to_packed。

Error change_scene_to_packed ( PackedScene packed_scene )

将正在运行的场景更改为给定 PackedScene 的新实例（新实例必须有效）。

成功时返回 @GlobalScope.OK，场景无法被实例化时返回 @GlobalScope.ERR_CANT_CREATE，场景无效时返回 @GlobalScope.ERR_INVALID_PARAMETER。

注意：当 change_scene_to_packed 被调用时，操作按以下顺序发生：

1. 当前场景节点被立即从树中移除。从那时起，在当前（传出）场景上调用的 Node.get_tree 将返回 null。current_scene 也将变为 null，因为新场景尚不可用。

2. 在帧末尾时，已从树中移除的、之前的当前场景将被删除（从内存中释放），然后新场景将被实例化并添加到树中。Node.get_tree 和 current_scene 将恢复正常工作。

这确保了两个场景不会同时运行，并且仍然会以类似于 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。

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

GDScriptC#

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

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

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.