SceneTree

继承： MainLoop < Object

通过节点层次结构管理应用循环。

描述

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

您还可以使用SceneTree将您的节点组织成组：每个节点都可以添加到您想要创建的任意数量的组中，例如“敌人”组。然后，您可以迭代这些组，甚至调用方法并在属于任何给定组的所有节点上设置属性。

SceneTree是引擎使用的默认MainLoop实现，因此负责应用循环。

属性

bool

auto_accept_quit

true

Item

current_scene

bool

debug_collisions_hint

false

bool

debug_navigation_hint

false

bool

debug_paths_hint

false

Item

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

Item

get_first_node_in_group(group: StringName)

int

get_frame() const

MultiplayerAPI

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

int

get_node_count() const

int

get_node_count_in_group(group: StringName) const

Array[Item]

get_nodes_in_group(group: StringName)

Array[Tween]

get_processed_tweens()

bool

has_group(name: StringName) 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: ItemPath = ItemPath(""))

void

unload_current_scene()

信号

node_added(node: Item) 🔗

node进入此树时发出。

node_configuration_warning_changed(node: Item) 🔗

调用node的Item.update_configuration_warnings()时发出。仅在编辑器中发出。

node_removed(node: Item) 🔗

node退出此树时发出。

node_renamed(node: Item) 🔗

当node的Item.name改变时发出。

physics_frame() 🔗

在此树中的每个节点上调用Item.FxiedUpdate()之前立即发出。

process_frame() 🔗

在此树中的每个节点上调用Item.Update()之前立即发出。

tree_changed() 🔗

每当树的层次结构发生变化（节点被移动、重命名等）时发出。

tree_process_mode_changed() 🔗

当树内任何节点的Item.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。

Item current_scene 🔗

  • void set_current_scene(value: Item)

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

如果true，则在从编辑器运行应用以进行调试时，冲突形状将可见。

注意：此属性不设计为在运行时更改。在项目运行时更改debug_collisions_hint的值不会产生预期的效果。

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和Route节点的曲线将可见。

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

Item edited_scene_root 🔗

  • void set_edited_scene_root(value: Item)

  • Item 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，则认为场景树已暂停。这会导致以下行为：

-2D和3D物理将停止，以及冲突检测和相关信号。

-根据每个节点的Item.process_mode，它们的Item.Update()、Item.FixedUpdate()和Item.OnInput()回调方法可能不再被调用。

bool physics_interpolation = false 🔗

  • void set_physics_interpolation_enabled(value: bool)

  • bool is_physics_interpolation_enabled()

如果true，渲染器将在最后两个变换之间插入物理对象的变换，以便即使物理刻度与渲染帧不一致，也能看到平滑的运动。

此属性的默认值由ProjectSettings.physics/common/physics_interpolation控制。

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。这是场景树的最顶层Item，并且始终存在。绝对ItemPath总是从该节点开始。根节点的子节点可能包括加载的current_scene，以及在项目设置中配置的任何AutoLoad。

警告：不要删除此节点。这将导致行为不稳定，然后崩溃。

方法说明

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

调用此树中添加到给定group的每个节点上的method。您可以通过在此方法调用结束时指定参数来将参数传递给method。不能调用method的节点（因为该方法不存在或参数不匹配）将被忽略。另请参见set_group()和notify_group()。

注意：此方法一次立即作用于所有选定的节点，在某些performance-intensive情况下可能会导致卡顿。

注意：在C#中，当引用内置i3D方法时，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# 中，当引用内置i3D方法时，method 必须采用蛇形命名法。建议使用 MethodName 类中公开的名称，以避免每次调用时分配新的 StringName

Error change_scene_to_file(path: String) 🔗

将运行场景加载到PackedScene并创建新实例后，将其更改为给定path处的场景。

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

注：有关操作顺序的详细信息，请参见change_scene_to_packed()。

Error change_scene_to_packed(packed_scene: PackedScene) 🔗

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

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

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

1.当前场景节点立即从树中删除。从那时起，在当前（传出）场景中调用的Item.get_tree()将返回null。current_scene也将是null，因为新场景还不可用。

2.在框架结束时，已经从树中删除的以前的当前场景将被删除（从内存中释放），然后新场景将被实例化并添加到树中。Item.get_tree()和current_scene将恢复正常工作。

这确保了两个场景不会同时运行，同时仍然以类似于Item.queue_free()节点的安全方式释放前一个场景。

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("start")
    await get_tree().create_timer(1.0).timeout
    print("end")

注意： 计时器始终在树中所有节点之后更新。节点的 Item.Update() 方法会在计时器更新之前调用（如果 process_in_physics 设置为 true，则会调用 Item.FixedUpdate()）

Tween create_tween() 🔗

创建并返回在此树中处理的新Tween。吐温将在下一个进程框架或物理框架上自动启动（取决于它的TweenProcessMode）。

注意：使用此方法创建的Tween不绑定到任何Item。它可能会一直工作，直到没有剩余的动画。如果您希望Item被释放时Tween被自动杀死，请使用Item.create_tween()或Tween.bind_node()。

Item get_first_node_in_group(group: StringName) 🔗

按场景层次顺序返回在树中找到的第一个Item，该节点已添加到给定的group中。如果未找到匹配项，则返回null。另请参见get_nodes_in_group()。

int get_frame() const 🔗

返回自应用程序启动以来已处理的帧数。这是而不是对经过时间的测量。

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

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

int get_node_count() const 🔗

返回此树内的节点数。

int get_node_count_in_group(group: StringName) const 🔗

返回分配给给定组的节点数。

Array[Item] get_nodes_in_group(group: StringName) 🔗

按场景层次顺序返回一个Array，其中包含此树中已添加到给定group的所有节点。

Array[Tween] get_processed_tweens() 🔗

返回树中当前存在的Tween的Array，包括暂停的吐温。

bool has_group(name: StringName) const 🔗

如果树中存在添加到给定组name的节点，则返回true。

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

使用给定的notification向添加到group的该树内的所有节点调用Object.notification()。另请参见call_group()和set_group()。

注意：此方法一次立即作用于所有选定的节点，在某些performance-intensive情况下可能会导致卡顿。

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()，此方法类似于Item.queue_free()。

void quit(exit_code: int = 0) 🔗

使用给定的exit_code在当前迭代结束时退出应用程序。

按照惯例，0的退出代码表示成功，而任何其他退出代码表示错误。出于可移植性原因，它应该介于0和125（包括）之间。

注意：iOS此方法不起作用。相反，根据iOS人机界面指南的建议，用户应通过主页按钮关闭应用程序。

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

注意：此方法一次立即作用于所有选定的节点，在某些performance-intensive情况下可能会导致卡顿。

注意：在C#中，当引用内置i3D属性时，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#中，当引用内置i3D属性时，property必须在snake_case中。首选使用PropertyName类中公开的名称，以避免在每次调用时分配新的StringName。

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

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

注意：不必须为包含root_path的子路径配置MultiplayerAPI，不允许嵌套自定义多人应用。即如果为"/root/Foo"配置一个为"/root/Foo/Bar"设置一个将导致错误。

void unload_current_scene() 🔗

如果加载了当前场景，则调用此方法将卸载它。