SceneTree

Inherits: MainLoop < Object

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

描述

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

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

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

教程

• 使用 SceneTree

• 多分辨率

属性

方法

信号

• connected_to_server ( )

当这个SceneTree的network_peer成功连接到一个服务器时发出。只在客户端发出。

• connection_failed ( )

每当此 SceneTree 的 network_peer 无法与服务器建立连接时发出。仅在客户端上发出。

• files_dropped ( PoolStringArray files, int screen )

当文件从操作系统的文件管理器中被拖到游戏窗口中时发出。参数是一个文件路径列表和拖动文件的屏幕标识符。

• global_menu_action ( Variant id, Variant meta )

每当单击全局菜单项时触发。

• idle_frame ( )

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

• network_peer_connected ( int id )

当这个SceneTree的network_peer与一个新的对等体连接时发出。ID是新对等体的对等体ID。当其他客户端连接到同一个服务器时，客户端会得到通知。当连接到一个服务器时，客户端也会收到该服务器的这个信号（ID为1）。

• network_peer_disconnected ( int id )

每当此 SceneTree 的 network_peer 与对等方断开连接时发出。当其他客户端与同一服务器断开连接时，客户端会收到通知。

• 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 之前立即发出。

• screen_resized ( )

当屏幕分辨率（全屏）或窗口大小（窗口化）改变时发出。

• server_disconnected ( )

当此 SceneTree 的 network_peer 与服务器断开连接时发出。仅在客户端上发出。

• tree_changed ( )

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

枚举

enum GroupCallFlags:

• GROUP_CALL_DEFAULT = 0 —- 调用没有标志的组（默认）。

• GROUP_CALL_REVERSE = 1 —- 以相反的场景顺序调用组。

• GROUP_CALL_REALTIME = 2 —- 立即调用一个组（调用通常在空闲时进行）。

• GROUP_CALL_UNIQUE = 4 —- 即使调用多次执行，也只调用一次组。

enum StretchMode:

• STRETCH_MODE_DISABLED = 0 —- 未拉伸。

• STRETCH_MODE_2D = 1 —- 以更高的分辨率渲染拉伸（插值）。

• STRETCH_MODE_VIEWPORT = 2 —- 保持指定的显示分辨率。没有插值。内容可能会出现像素化。

enum StretchAspect:

• STRETCH_ASPECT_IGNORE = 0 —- 用拉伸的内容填充窗口以覆盖过多的空间。内容可能会被拉伸。

• STRETCH_ASPECT_KEEP = 1 —- 在任意轴上用黑条填充来保持相同的长宽比。这可以防止失真。

• STRETCH_ASPECT_KEEP_WIDTH = 2 —- 垂直展开。如果窗口太宽，可能会出现左/右黑条。

• STRETCH_ASPECT_KEEP_HEIGHT = 3 —- 水平展开。如果窗口太高，可能会出现顶部/底部黑条。

• STRETCH_ASPECT_EXPAND = 4 —- 在两个方向上扩展，保持相同的纵横比。这可以防止失真，同时避免黑条。

属性说明

• Node current_scene

当前场景。

• bool debug_collisions_hint

如果 true，以调试为目的从编辑器运行游戏时，碰撞形状将是可见的。

• bool debug_navigation_hint

如果 true，以调试为目的从编辑器运行游戏时，导航多边形将是可见的。

• Node edited_scene_root

编辑场景的根。

• MultiplayerAPI multiplayer

此 SceneTree 的默认 MultiplayerAPI 实例。

• bool multiplayer_poll

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

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

• NetworkedMultiplayerPeer network_peer

处理 RPC 系统的对等对象（设置后有效地启用网络）。根据peer本身的不同，SceneTree将成为网络服务器（检查is_network_server）并将根节点的网络模式设置为master，或者它将成为根节点被设置为puppet的普通对等体。所有子节点默认设置为继承网络模式。与网络相关的事件（连接、断开连接、新客户端）的处理是通过连接到 SceneTree 的信号来完成的。

• bool paused

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

• 2D和3D物理将停止。这包括信号和碰撞检测。

• 节点不再调用Node._process、Node._physics_process和Node._input。

• bool refuse_new_network_connections

如果 true，则 SceneTree 的 network_peer 拒绝新的传入连接。

• Viewport root

SceneTree 的根 Viewport。

• bool use_font_oversampling

为 true 时启用字体过采样。这意味着根据视窗的缩放比例不同，DynamicFont 渲染的大小会比配置大小更高或更低。例如，如果视窗的缩放系数为 1.5，那么配置为 14 号大小的字体将会按照 21 号大小渲染（14 * 1.5）。

注意：字体过采样仅在视窗拉伸模式为 STRETCH_MODE_VIEWPORT 且拉伸比例模式不是 STRETCH_ASPECT_IGNORE 时有效。

注意：项目启动时会为活动的 SceneTree 自动设置该属性，取值为 ProjectSettings 的 rendering/quality/dynamic_fonts/use_oversampling。不过运行时可以根据需要对该属性进行覆盖。

方法说明

• Variant call_group ( String group, String method, … ) vararg

对给定组的每个成员调用 method。您可以通过在方法调用结束时指定参数来将参数传递给 method。此方法等效于使用 GROUP_CALL_DEFAULT 标志调用 call_group_flags。

注： method最多只能有5个参数（总共7个参数传递给这个方法）。

注意： 由于设计限制，如果参数之一为 null，call_group 将静默失败。

注意： call_group 将始终调用具有一帧延迟的方法，其方式类似于 Object.call_deferred。要立即调用方法，请将 call_group_flags 与 GROUP_CALL_REALTIME 标志一起使用。

• Variant call_group_flags ( int flags, String group, String method, … ) vararg

对给定组的每个成员调用 method，遵从给定的 GroupCallFlags。您可以通过在方法调用结束时指定参数来将参数传递给 method。

注： method最多只能有5个参数（总共8个参数传递给这个方法）。

注意： 由于设计限制，如果参数之一为 null，call_group_flags 将静默失败。

# 立即以相反的顺序调用该方法。
get_tree().call_group_flags(SceneTree.GROUP_CALL_REALTIME | SceneTree.GROUP_CALL_REVERSE, "bases", "destroy")

• Error change_scene ( String path )

将正在运行的场景改变为指定的path中的场景，在将其加载到PackedScene中并创建一个新的实例。

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

注意：场景改变有延迟，即新的场景节点是在下一个空闲帧中添加。在change_scene调用之后，你不能立即访问它。

• Error change_scene_to ( PackedScene packed_scene )

将正在运行的场景改变为给定的PackedScene的新实例。

成功时返回@GlobalScope.OK，如果场景不能被实例化，则返回@GlobalScope.ERR_CANT_CREATE。

注意： 场景的改变是延迟的，新的场景节点是在下一个空闲帧中添加。在调用change_scene_to之后，你不能立即访问它。

• SceneTreeTimer create_timer ( float time_sec, bool pause_mode_process=true )

返回一个 SceneTreeTimer，在这个 SceneTree 中经过给定的时间（秒）后，将发出 SceneTreeTimer.timeout 信号。如果 pause_mode_process 被设置为 false，暂停 SceneTree 也将暂停该定时器。

常用于创建一次性的延迟定时器，如下面的例子:

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

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

• int get_frame ( ) const

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

• PoolIntArray get_network_connected_peers ( ) const

返回此 SceneTree 的 network_peer 的所有连接对等方的对等 ID。

• int get_network_unique_id ( ) const

返回此 SceneTree 的 network_peer 的唯一对等 ID。

• int get_node_count ( ) const

返回此SceneTree中的节点数。

• Array get_nodes_in_group ( String group )

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

• int get_rpc_sender_id ( ) const

返回最近收到的RPC调用的发送者的对等ID。

• bool has_group ( String name ) const

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

• bool has_network_peer ( ) const

如果有一个network_peer设置，返回true。

• bool is_input_handled ( )

如果最近的 InputEvent 被使用 set_input_as_handled 设置为已处理，返回 true。

• bool is_network_server ( ) const

如果此 SceneTree 的 network_peer 处于服务器模式（侦听连接），则返回 true。

• void notify_group ( String group, int notification )

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

• void notify_group_flags ( int call_flags, String group, int notification )

将给定的通知发送给 group 的所有成员，遵从给定的 GroupCallFlags。

• void queue_delete ( Object obj )

将给定的对象排队准备删除，即在当前帧之后调用 Object.free 。

• void quit ( int exit_code=-1 )

在当前迭代结束时退出应用程序。进程的 exit_code 可以选择性地作为参数传递。如果这个参数大于等于 0，它将覆盖在退出应用程序之前定义的 OS.exit_code。

注意：这个方法在 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_auto_accept_quit ( bool enabled )

为 true 时应用程序将自动接受退出。默认启用。

对于移动平台，请参阅 set_quit_on_go_back。

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

在给定组的所有成员上将给定的属性 property 设置为 value。

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

将给定的 property 设置为给定组的所有成员的 value，尊重给定的 GroupCallFlags。

• void set_input_as_handled ( )

将最新的 InputEvent 标记为已处理。

• void set_quit_on_go_back ( bool enabled )

为 true 时应用程序将在返回时自动退出（例如在 Android 上）。默认启用。

要在这个选项被禁用时处理“返回”按钮，请使用 MainLoop.NOTIFICATION_WM_GO_BACK_REQUEST。

• void set_screen_stretch ( StretchMode mode, StretchAspect aspect, Vector2 minsize, float scale=1 )

将屏幕拉伸配置为给定的 StretchMode、StretchAspect、最小尺寸和 scale。