Table of Contents

Class SceneTree

Namespace
Godot
Assembly
GodotSharp.dll

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.

public class SceneTree : MainLoop, IDisposable
Inheritance
SceneTree
Implements
Inherited Members

Constructors

SceneTree() 

public SceneTree()

Properties

AutoAcceptQuit

If true, the application automatically accepts quitting requests.

For mobile platforms, see QuitOnGoBack.

public bool AutoAcceptQuit { get; set; }

Property Value

bool

CurrentScene

The root node of the currently loaded main scene, usually as a direct child of Root. See also ChangeSceneToFile(string), ChangeSceneToPacked(PackedScene), and ReloadCurrentScene().

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

public Node CurrentScene { get; set; }

Property Value

Node

DebugCollisionsHint

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 DebugCollisionsHint while the project is running will not have the desired effect.

public bool DebugCollisionsHint { get; set; }

Property Value

bool

DebugNavigationHint

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 DebugNavigationHint while the project is running will not have the desired effect.

public bool DebugNavigationHint { get; set; }

Property Value

bool

DebugPathsHint

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 DebugPathsHint while the project is running will not have the desired effect.

public bool DebugPathsHint { get; set; }

Property Value

bool

EditedSceneRoot

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.

public Node EditedSceneRoot { get; set; }

Property Value

Node

MultiplayerPoll

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

If false, you need to manually call 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.

public bool MultiplayerPoll { get; set; }

Property Value

bool

Paused

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 ProcessMode, their _Process(double), _PhysicsProcess(double) and _Input(InputEvent) callback methods may not called anymore.

public bool Paused { get; set; }

Property Value

bool

PhysicsInterpolation

If true, the renderer will interpolate the transforms of physics objects 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.

public bool PhysicsInterpolation { get; set; }

Property Value

bool

QuitOnGoBack

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

public bool QuitOnGoBack { get; set; }

Property Value

bool

Root

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 CurrentScene, 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.

public Window Root { get; }

Property Value

Window

Methods

CallGroup(StringName, StringName, params Variant[])

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 SetGroup(StringName, string, Variant) and NotifyGroup(StringName, int).

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.

public void CallGroup(StringName group, StringName method, params Variant[] args)

Parameters

group StringName
method StringName
args Variant[]

CallGroupFlags(long, StringName, StringName, params Variant[])

Calls the given method on each node inside this tree added to the given group. Use flags to customize this method's behavior (see SceneTree.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.

public void CallGroupFlags(long flags, StringName group, StringName method, params Variant[] args)

Parameters

flags long
group StringName
method StringName
args Variant[]

ChangeSceneToFile(string)

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, CantOpen if the path cannot be loaded into a PackedScene, or CantCreate if that scene cannot be instantiated.

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

public Error ChangeSceneToFile(string path)

Parameters

path string

Returns

Error

ChangeSceneToPacked(PackedScene)

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

Returns Ok on success, CantCreate if the scene cannot be instantiated, or InvalidParameter if the scene is invalid.

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

1. The current scene node is immediately removed from the tree. From that point, GetTree() called on the current (outgoing) scene will return null. CurrentScene 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 will be instantiated and added to the tree. GetTree() and CurrentScene 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 QueueFree().

public Error ChangeSceneToPacked(PackedScene packedScene)

Parameters

packedScene PackedScene

Returns

Error

CreateTimer(double, bool, bool, bool)

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

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

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

If ignoreTimeScale is true, the timer will ignore TimeScale and update with the real, elapsed time.

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

public async Task SomeFunction()
  {
      GD.Print("start");
      await ToSignal(GetTree().CreateTimer(1.0f), SceneTreeTimer.SignalName.Timeout);
      GD.Print("end");
  }

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

public SceneTreeTimer CreateTimer(double timeSec, bool processAlways = true, bool processInPhysics = false, bool ignoreTimeScale = false)

Parameters

timeSec double
processAlways bool
processInPhysics bool
ignoreTimeScale bool

Returns

SceneTreeTimer

CreateTween()

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 CreateTween() or BindNode(Node).

public Tween CreateTween()

Returns

Tween

GetFirstNodeInGroup(StringName)

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 GetNodesInGroup(StringName).

public Node GetFirstNodeInGroup(StringName group)

Parameters

group StringName

Returns

Node

GetFrame()

Returns how many frames have been processed, since the application started. This is not a measurement of elapsed time.

public long GetFrame()

Returns

long

GetMultiplayer(NodePath)

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 SetMultiplayer(MultiplayerApi, NodePath).

public MultiplayerApi GetMultiplayer(NodePath forPath = null)

Parameters

forPath NodePath

Returns

MultiplayerApi

GetNodeCount()

Returns the number of nodes inside this tree.

public int GetNodeCount()

Returns

int

GetNodeCountInGroup(StringName)

Returns the number of nodes assigned to the given group.

public int GetNodeCountInGroup(StringName group)

Parameters

group StringName

Returns

int

GetNodesInGroup(StringName)

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

public Array<Node> GetNodesInGroup(StringName group)

Parameters

group StringName

Returns

Array<Node>

GetProcessedTweens()

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

public Array<Tween> GetProcessedTweens()

Returns

Array<Tween>

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

HasGroup(StringName)

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

public bool HasGroup(StringName name)

Parameters

name StringName

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

NotifyGroup(StringName, int)

Calls Notification(int, bool) with the given notification to all nodes inside this tree added to the group. See also Godot notifications and CallGroup(StringName, StringName, params Variant[]) and SetGroup(StringName, string, Variant).

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

public void NotifyGroup(StringName group, int notification)

Parameters

group StringName
notification int

NotifyGroupFlags(uint, StringName, int)

Calls Notification(int, bool) with the given notification to all nodes inside this tree added to the group. Use callFlags to customize this method's behavior (see SceneTree.GroupCallFlags).

public void NotifyGroupFlags(uint callFlags, StringName group, int notification)

Parameters

callFlags uint
group StringName
notification int

QueueDelete(GodotObject)

Queues the given obj to be deleted, calling its Free() at the end of the current frame. This method is similar to QueueFree().

public void QueueDelete(GodotObject obj)

Parameters

obj GodotObject

Quit(int)

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

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.

public void Quit(int exitCode = 0)

Parameters

exitCode int

ReloadCurrentScene()

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

Returns Ok on success, Unconfigured if no CurrentScene is defined, CantOpen if CurrentScene cannot be loaded into a PackedScene, or CantCreate if the scene cannot be instantiated.

public Error ReloadCurrentScene()

Returns

Error

SetGroup(StringName, string, Variant)

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 CallGroup(StringName, StringName, params Variant[]) and NotifyGroup(StringName, int).

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.

public void SetGroup(StringName group, string property, Variant value)

Parameters

group StringName
property string
value Variant

SetGroupFlags(uint, StringName, string, Variant)

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 callFlags to customize this method's behavior (see SceneTree.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.

public void SetGroupFlags(uint callFlags, StringName group, string property, Variant value)

Parameters

callFlags uint
group StringName
property string
value Variant

SetMultiplayer(MultiplayerApi, NodePath)

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

Note: No MultiplayerApi must be configured for the subpath containing rootPath, 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.

public void SetMultiplayer(MultiplayerApi multiplayer, NodePath rootPath = null)

Parameters

multiplayer MultiplayerApi
rootPath NodePath

UnloadCurrentScene()

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

public void UnloadCurrentScene()

Events

NodeAdded

Emitted when the node enters this tree.

public event SceneTree.NodeAddedEventHandler NodeAdded

Event Type

SceneTree.NodeAddedEventHandler

NodeConfigurationWarningChanged

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

public event SceneTree.NodeConfigurationWarningChangedEventHandler NodeConfigurationWarningChanged

Event Type

SceneTree.NodeConfigurationWarningChangedEventHandler

NodeRemoved

Emitted when the node exits this tree.

public event SceneTree.NodeRemovedEventHandler NodeRemoved

Event Type

SceneTree.NodeRemovedEventHandler

NodeRenamed

Emitted when the node's Name is changed.

public event SceneTree.NodeRenamedEventHandler NodeRenamed

Event Type

SceneTree.NodeRenamedEventHandler

PhysicsFrame

Emitted immediately before _PhysicsProcess(double) is called on every node in this tree.

public event Action PhysicsFrame

Event Type

Action

ProcessFrame

Emitted immediately before _Process(double) is called on every node in this tree.

public event Action ProcessFrame

Event Type

Action

TreeChanged

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

public event Action TreeChanged

Event Type

Action

TreeProcessModeChanged

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

public event Action TreeProcessModeChanged

Event Type

Action
Edit this page