From e5f2c442c7bebed100e4fb305deefb31af0c94ce Mon Sep 17 00:00:00 2001
From: Juan Linietsky <reduzio@gmail.com>
Date: Fri, 6 Jan 2023 16:08:36 +0100
Subject: Add SceneTree.unload_current_scene()

Provides an obvious way to unload the currently loaded scene (which is nowhere to be found in the docs).
The SceneTree.change_scene_to() method must now always provide a valid PackedScene.

Fixes #63565.
---
 doc/classes/SceneTree.xml | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

(limited to 'doc')

diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml
index bd5b656e1a..bf19ebc23a 100644
--- a/doc/classes/SceneTree.xml
+++ b/doc/classes/SceneTree.xml
@@ -42,15 +42,15 @@
 			<description>
 				Changes the running scene to the one at the given [param path], after loading it into a [PackedScene] and creating a new instance.
 				Returns [constant OK] on success, [constant ERR_CANT_OPEN] if the [param path] cannot be loaded into a [PackedScene], or [constant ERR_CANT_CREATE] if that scene cannot be instantiated.
-				[b]Note:[/b] The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the [method change_scene_to_file] call.
+				[b]Note:[/b] The scene change is deferred, which means that the new scene node is added on the next idle frame. This ensures that both scenes are never loaded at the same time, which can exhaust system resources if the scenes are too large or if running in a memory constrained environment. As such, you won't be able to access the loaded scene immediately after the [method change_scene_to_file] call.
 			</description>
 		</method>
 		<method name="change_scene_to_packed">
 			<return type="int" enum="Error" />
 			<param index="0" name="packed_scene" type="PackedScene" />
 			<description>
-				Changes the running scene to a new instance of the given [PackedScene].
-				Returns [constant OK] on success or [constant ERR_CANT_CREATE] if the scene cannot be instantiated.
+				Changes the running scene to a new instance of the given [PackedScene] (which must be valid).
+				Returns [constant OK] on success, [constant ERR_CANT_CREATE] if the scene cannot be instantiated, or [constant ERR_INVALID_PARAMETER] if the scene is invalid.
 				[b]Note:[/b] The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the [method change_scene_to_packed] call.
 			</description>
 		</method>
@@ -209,6 +209,12 @@
 				Sets a custom [MultiplayerAPI] with the given [param root_path] (controlling also the relative subpaths), or override the default one if [param root_path] is empty.
 			</description>
 		</method>
+		<method name="unload_current_scene">
+			<return type="void" />
+			<description>
+				If a current scene is loaded, calling this method will unload it.
+			</description>
+		</method>
 	</methods>
 	<members>
 		<member name="auto_accept_quit" type="bool" setter="set_auto_accept_quit" getter="is_auto_accept_quit" default="true">
-- 
cgit v1.2.3