Index · Object → MainLoop → SceneTree

SceneTree

Manages the game loop via a hierarchy of nodes.

Class Description

As one of the most important classes, the SceneTree manages the hierarchy of nodes in a scene, as well as scenes themselves. Nodes can be added, fetched and removed. The whole scene tree (and thus the current scene) can be paused. Scenes can be loaded, switched and reloaded.

You can also use the SceneTree to organize your nodes into groups: every node can be added to as many groups as you want to create, e.g. an "enemy" group. You can then iterate these groups or even call methods and set properties on all the nodes belonging to any given group.

SceneTree is the default MainLoop implementation used by the engine, and is thus in charge of the game loop.

Properties

var auto_accept_quit: bool = true

If true, the application automatically accepts quitting requests.

For mobile platforms, see quit_on_go_back.

var current_scene: Node

The root node of the currently loaded main scene, usually as a direct child of root. See also change_scene_to_file(), change_scene_to_packed(), and reload_current_scene().

Warning: Setting this property directly may not work as expected, as it does not add or remove any nodes from this tree.

var debug_collisions_hint: bool = false

If true, collision shapes will be visible when running the game from the editor for debugging purposes.

Note: This property is not designed to be changed at run-time. Changing the value of debug_collisions_hint while the project is running will not have the desired effect.

var debug_navigation_hint: bool = false

If true, navigation polygons will be visible when running the game from the editor for debugging purposes.

Note: This property is not designed to be changed at run-time. Changing the value of debug_navigation_hint while the project is running will not have the desired effect.

var debug_paths_hint: bool = false

If true, curves from Path2D and Path3D nodes will be visible when running the game from the editor for debugging purposes.

Note: This property is not designed to be changed at run-time. Changing the value of debug_paths_hint while the project is running will not have the desired effect.

var edited_scene_root: Node

The root of the scene currently being edited in the editor. This is usually a direct child of root.

Note: This property does nothing in release builds.

var multiplayer_poll: bool = true

If true (default value), enables automatic polling of the MultiplayerAPI for this SceneTree during process_frame.

If false, you need to manually call MultiplayerAPI.poll() to process network packets and deliver RPCs. This allows running RPCs in a different loop (e.g. physics, thread, specific time step) and for manual Mutex protection when accessing the MultiplayerAPI from threads.

var paused: bool = false

If true, the scene tree is considered paused. This causes the following behavior:

- 2D and 3D physics will be stopped, as well as collision detection and related signals.

- Depending on each node's Node.process_mode, their Node._process(), Node._physics_process() and Node._input() callback methods may not called anymore.

var physics_interpolation: bool = false

If true, the renderer will interpolate the transforms of objects (both physics and non-physics) between the last two transforms, so that smooth motion is seen even when physics ticks do not coincide with rendered frames.

The default value of this property is controlled by ProjectSettings.physics/common/physics_interpolation.

Note: Although this is a global setting, finer control of individual branches of the SceneTree is possible using Node.physics_interpolation_mode.

var quit_on_go_back: bool = true

If true, the application quits automatically when navigating back (e.g. using the system "Back" button on Android).

To handle 'Go Back' button when this option is disabled, use DisplayServer.WINDOW_EVENT_GO_BACK_REQUEST.

var root: Window

The tree's root Window. This is top-most Node of the scene tree, and is always present. An absolute NodePath always starts from this node. Children of the root node may include the loaded current_scene, as well as any AutoLoad configured in the Project Settings.

Warning: Do not delete this node. This will result in unstable behavior, followed by a crash.

Methods

func call_group(group: StringName, method: StringName) -> void

Calls method on each node inside this tree added to the given group. You can pass arguments to method by specifying them at the end of this method call. Nodes that cannot call method (either because the method doesn't exist or the arguments do not match) are ignored. See also set_group() and notify_group().

Note: This method acts immediately on all selected nodes at once, which may cause stuttering in some performance-intensive situations.

Note: In C#, method must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the MethodName class to avoid allocating a new StringName on each call.

func call_group_flags(flags: int, group: StringName, method: StringName) -> void

Calls the given method on each node inside this tree added to the given group. Use flags to customize this method's behavior (see GroupCallFlags). Additional arguments for method can be passed at the end of this method. Nodes that cannot call method (either because the method doesn't exist or the arguments do not match) are ignored.

# Calls "hide" to all nodes of the "enemies" group, at the end of the frame and in reverse tree order.
get_tree().call_group_flags(
		SceneTree.GROUP_CALL_DEFERRED | SceneTree.GROUP_CALL_REVERSE,
		"enemies", "hide")

Note: In C#, method must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the MethodName class to avoid allocating a new StringName on each call.

func change_scene_to_file(path: String) -> Error

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

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

Note: See change_scene_to_node() for details on the order of operations.

func change_scene_to_node(node: Node) -> Error

Changes the running scene to the provided Node. Useful when you want to set up the new scene before changing.

Returns OK on success, ERR_INVALID_PARAMETER if the node is null, or ERR_UNCONFIGURED if the node is already inside the scene tree.

Note: Operations happen in the following order when change_scene_to_node() is called:

1. 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.

2. 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 node will be 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().

If you want to reliably access the new scene, await the scene_changed signal.

Warning: After using this method, the SceneTree will take ownership of the node and will free it automatically when changing scene again. Any references you had to that node will become invalid.

func change_scene_to_packed(packed_scene: PackedScene) -> Error

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

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

Note: See change_scene_to_node() for details on the order of operations.

func create_timer(time_sec: float, process_always: bool = true, process_in_physics: bool = false, ignore_time_scale: bool = false) -> SceneTreeTimer

Returns a new SceneTreeTimer. After time_sec in seconds have passed, the timer will emit SceneTreeTimer.timeout and will be automatically freed.

If process_always is false, the timer will be paused when setting paused to true.

If process_in_physics is true, the timer will update at the end of the physics frame, instead of the process frame.

If ignore_time_scale is true, the timer will ignore Engine.time_scale and update with the real, elapsed time.

This method is commonly used to create a one-shot delay timer, as in the following example:

func some_function():
	print("start")
	await get_tree().create_timer(1.0).timeout
	print("end")

Note: The timer is always updated after all of the nodes in the tree. A node's Node._process() method would be called before the timer updates (or Node._physics_process() if process_in_physics is set to true).

func create_tween() -> Tween

Creates and returns a new Tween processed in this tree. The Tween will start automatically on the next process frame or physics frame (depending on its Tween.TweenProcessMode).

Note: A Tween created using this method is not bound to any Node. It may keep working until there is nothing left to animate. If you want the Tween to be automatically killed when the Node is freed, use Node.create_tween() or Tween.bind_node().

func get_first_node_in_group(group: StringName) -> Node

Returns the first Node found inside the tree, that has been added to the given group, in scene hierarchy order. Returns null if no match is found. See also get_nodes_in_group().

func get_frame() -> int

Returns how many physics process steps have been processed, since the application started. This is not a measurement of elapsed time. See also physics_frame. For the number of frames rendered, see Engine.get_process_frames().

func get_multiplayer(for_path: NodePath = NodePath("")) -> MultiplayerAPI

Searches for the MultiplayerAPI configured for the given path, if one does not exist it searches the parent paths until one is found. If the path is empty, or none is found, the default one is returned. See set_multiplayer().

func get_node_count() -> int

Returns the number of nodes inside this tree.

func get_node_count_in_group(group: StringName) -> int

Returns the number of nodes assigned to the given group.

func get_nodes_in_group(group: StringName) -> Node[]

Returns an Array containing all nodes inside this tree, that have been added to the given group, in scene hierarchy order.

func get_processed_tweens() -> Tween[]

Returns an Array of currently existing Tweens in the tree, including paused tweens.

func has_group(name: StringName) -> bool

Returns true if a node added to the given group name exists in the tree.

func is_accessibility_enabled() -> bool

Returns true if accessibility features are enabled, and accessibility information updates are actively processed.

func is_accessibility_supported() -> bool

Returns true if accessibility features are supported by the OS and enabled in project settings.

func notify_group(group: StringName, notification: int) -> void

Calls Object.notification() with the given notification to all nodes inside this tree added to the group. See also Godot notifications and call_group() and set_group().

Note: This method acts immediately on all selected nodes at once, which may cause stuttering in some performance-intensive situations.

func notify_group_flags(call_flags: int, group: StringName, notification: int) -> void

Calls Object.notification() with the given notification to all nodes inside this tree added to the group. Use call_flags to customize this method's behavior (see GroupCallFlags).

func queue_delete(obj: Object) -> void

Queues the given obj to be deleted, calling its Object.free() at the end of the current frame. This method is similar to Node.queue_free().

func quit(exit_code: int = 0) -> void

Quits the application at the end of the current iteration, with the given exit_code.

By convention, an exit code of 0 indicates success, whereas any other exit code indicates an error. For portability reasons, it should be between 0 and 125 (inclusive).

Note: On iOS this method doesn't work. Instead, as recommended by the iOS Human Interface Guidelines, the user is expected to close apps via the Home button.

func reload_current_scene() -> Error

Reloads the currently active scene, replacing current_scene with a new instance of its original PackedScene.

Returns OK on success, ERR_UNCONFIGURED if no current_scene is defined, ERR_CANT_OPEN if current_scene cannot be loaded into a PackedScene, or ERR_CANT_CREATE if the scene cannot be instantiated.

func set_group(group: StringName, property: String, value: Variant) -> void

Sets the given property to value on all nodes inside this tree added to the given group. Nodes that do not have the property are ignored. See also call_group() and notify_group().

Note: This method acts immediately on all selected nodes at once, which may cause stuttering in some performance-intensive situations.

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

func set_group_flags(call_flags: int, group: StringName, property: String, value: Variant) -> void

Sets the given property to value on all nodes inside this tree added to the given group. Nodes that do not have the property are ignored. Use call_flags to customize this method's behavior (see GroupCallFlags).

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

func set_multiplayer(multiplayer: MultiplayerAPI, root_path: NodePath = NodePath("")) -> void

Sets a custom MultiplayerAPI with the given root_path (controlling also the relative subpaths), or override the default one if root_path is empty.

Note: No MultiplayerAPI must be configured for the subpath containing root_path, nested custom multiplayers are not allowed. I.e. if one is configured for "/root/Foo" setting one for "/root/Foo/Bar" will cause an error.

Note: set_multiplayer() should be called before the child nodes are ready at the given root_path. If multiplayer nodes like MultiplayerSpawner or MultiplayerSynchronizer are added to the tree before the custom multiplayer API is set, they will not work.

func unload_current_scene() -> void

If a current scene is loaded, calling this method will unload it.

Inherited from MainLoop (4)
func _finalize() -> void
func _initialize() -> void
func _physics_process(delta: float) -> bool
func _process(delta: float) -> bool
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

signal node_added(node: Node)

Emitted when the node enters this tree.

signal node_configuration_warning_changed(node: Node)

Emitted when the node's Node.update_configuration_warnings() is called. Only emitted in the editor.

signal node_removed(node: Node)

Emitted when the node exits this tree.

signal node_renamed(node: Node)

Emitted when the node's Node.name is changed.

signal physics_frame()

Emitted immediately before Node._physics_process() is called on every node in this tree.

signal process_frame()

Emitted immediately before Node._process() is called on every node in this tree.

signal scene_changed()

Emitted after the new scene is added to scene tree and initialized. Can be used to reliably access current_scene when changing scenes.

# This code should be inside an autoload.
get_tree().change_scene_to_file(other_scene_path)
await get_tree().scene_changed
print(get_tree().current_scene) # Prints the new scene.
signal tree_changed()

Emitted any time the tree's hierarchy changes (nodes being moved, renamed, etc.).

signal tree_process_mode_changed()

Emitted when the Node.process_mode of any node inside the tree is changed. Only emitted in the editor, to update the visibility of disabled nodes.

Inherited from MainLoop (1)
signal on_request_permissions_result(permission: String, granted: bool)
Inherited from Object (2)

Enums & Constants

enum GroupCallFlags
GROUP_CALL_DEFAULT = 0

Call nodes within a group with no special behavior (default).

GROUP_CALL_REVERSE = 1

Call nodes within a group in reverse tree hierarchy order (all nested children are called before their respective parent nodes).

GROUP_CALL_DEFERRED = 2

Call nodes within a group at the end of the current frame (can be either process or physics frame), similar to Object.call_deferred().

GROUP_CALL_UNIQUE = 4

Call nodes within a group only once, even if the call is executed many times in the same frame. Must be combined with GROUP_CALL_DEFERRED to work.

Note: Different arguments are not taken into account. Therefore, when the same call is executed with different arguments, only the first call will be performed.