Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

Change scenes manually¶

Sometimes it helps to have more control over how one swaps scenes around. As mentioned above, a Viewport's child nodes will render to the image it generates. This holds true even for nodes outside of the "current" scene. Autoloads fall into this category, but so do scenes which one instances and adds to the tree at runtime:

var simultaneous_scene = preload("res://levels/level2.tscn").instantiate()

func _add_a_scene_manually():
    # This is like autoloading the scene, only
    # it happens after already loading the main scene.
    get_tree().root.add_child(simultaneous_scene)

public Node simultaneousScene;

public MyClass()
{
    simultaneousScene = ResourceLoader.Load<PackedScene>("res://levels/level2.tscn").Instantiate();
}

public void _AddASceneManually()
{
    // This is like autoloading the scene, only
    // it happens after already loading the main scene.
    GetTree().Root.AddChild(simultaneousScene);
}

To complete the cycle and swap out the new scene with the old one, developers have a choice to make. Many strategies exist for removing a scene from view of the Viewport. The tradeoffs involve balancing operation speed and memory consumption as well as balancing data access and integrity.

We can delete the existing scene. SceneTree.change_scene_to_file() and SceneTree.change_scene_to_packed() will delete the current scene immediately. Developers can also delete the main scene though. Assuming the root node's name is "Main", one could do get_node("/root/Main").free() to delete the whole scene.
- Unloads memory.
  Pro: RAM is no longer dragging the dead weight.
  
  Con: Returning to that scene is now more expensive since it must be loaded back into memory again (takes time AND memory). Not a problem if returning soon is unnecessary.
  
  Con: No longer have access to that scene's data. Not a problem if using that data soon is unnecessary.
  
  Note: It can be useful to preserve the data in a soon-to-be-deleted scene by re-attaching one or more of its nodes to a different scene, or even directly to the SceneTree.
- Processing stops.
  Pro: No nodes means no process, physics process, or input handling. The CPU is available to work on the new scene's contents.
  
  Con: Those nodes' processing and input handling no longer operate. Not a problem if using the updated data is unnecessary.
We can hide the existing scene. By changing the visibility or collision detection of the nodes, we can hide the entire node sub-tree from the player's perspective.
- Memory still exists.
  Pro: One can still access the data if need be.
  
  Pro: There's no need to move any more nodes around to save data.
  
  Con: More data is being kept in memory which will be become a problem on memory-sensitive platforms like web or mobile.
- Processing continues.
  Pro: Data continues to receive processing updates, so the scene will keep updated any data within it that relies on delta time or frame data.
  
  Pro: Nodes are still members of groups (since groups belong to the SceneTree).
  
  Con: The CPU's attention is now divided between both scenes.