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_filechange_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,从编辑器中运行游戏时,来自 Path2DPath3D 节点的曲线将可见以进行调试。

注意:该属性没有被设计为在运行时更改。在项目运行时更改 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 ( )

如果为 trueSceneTree 会暂停。这样做会有以下行为:


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

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 将返回 nullcurrent_scene 也将变为 null,因为新场景尚不可用。

  2. 在帧末尾时,已从树中移除的、之前的当前场景将被删除(从内存中释放),然后新场景将被实例化并添加到树中。Node.get_treecurrent_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_alwaysfalse,则暂停 SceneTree 也会暂停计时器。

如果 process_in_physicstrue,则将在物理帧而不是处理帧期间更新 SceneTreeTimer(固定帧率处理)。

如果 ignore_time_scaletrue,则将忽略 Engine.time_scale 并使用实际帧增量来更新 SceneTreeTimer

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

func some_function():
    print("开始")
    await get_tree().create_timer(1.0).timeout
    print("结束")

计时器将在其时间结束后被自动释放。

注意:计时器是在当前帧所有节点之后处理的,即节点的 Node._process 方法比计时器先调用(process_in_physicstrue 时为 Node._physics_process)。


Tween create_tween ( )

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

注意:使用这个方法创建 Tween 时,Tween 不会与调用的 Node 绑定。即便在该 Node 释放后也仍然会继续进行动画,但是在已经没有任何可以动画的东西时会自动结束。如果你想要让 Tween 在该 Node 释放时自动销毁,请使用 Node.create_tweenTween.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 ( )

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