📖 docs: v3.8.0

Author: maktoobgar

CHANGELOG.rst

@@ -4,7 +4,11 @@ CHANGELOG
 UNRELEASED
 ----------
 
-* 🎉 feat: added ability to load scenes interactive
+3.8.0 (2023-11-22)
+------------------
+
+* feat: added ability to load scenes interactive and have a loading phase like world generation or any loading in general
+* fix: fixed a bug on when couldn't reload the current scenes when we used loading screen to get to them
 
 3.7.0 (2023-11-03)
 ------------------

README.md

@@ -8,19 +8,15 @@ A tool to manage transition between different scenes.\
 Scene Manager v1.X.X and v2.X.X is compatible with Godot 3.\
 Scene Manager v3.X.X is compatible with Godot 4.
 
+**Note**: Scene Manager v2.X.X and v1.X.X has heavily less features.
+
 ## Features
 
 **Recently Added**:
 
-* [X] Possibility to specify path scenes.db via Project/Settings (Just Godot4)
-* [X] 5 new signals added:
-    - scene_changed
-    - fade_in_started
-    - fade_out_started
-    - fade_in_finished
-    - fade_out_finished
-* [X] added a feature to navigate to the scene path in filesystem on godot when clicked on scene address in Scene Manager tool
-* [X] added a feature to open a desired scene from Scene Manager tab
+* [X] Added a feature to navigate to the scene path in filesystem on godot when clicked on scene address in Scene Manager tool
+* [X] Added a feature to open a desired scene from Scene Manager tab
+* [X] Users now can have some time to load their scene in the background with the new changing scene functionality
 
 **All**:
 
@@ -48,7 +44,13 @@ Scene Manager v3.X.X is compatible with Godot 4.
 * [X] sublist in lists of scene manager UI is now possible (Just Godot4)
 * [X] `no_effect_change_scene` function added (Just Godot4)
 * [X] Node can be added to `change_scene` and `no_effect_change_scene` functions (Just Godot4)
-
+* [X] Possibility to specify path scenes.db via Project/Settings (Just Godot4)
+* [X] 5 new signals added:
+  * scene_changed
+  * fade_in_started
+  * fade_out_started
+  * fade_in_finished
+  * fade_out_finished
 
 ## How To Use?
 
@@ -69,15 +71,15 @@ This is the tool that you will see on your right side of the godot editor after
 <img src="images/tool.png"/>
 </p>
 
-### Double key checker:
+### Double key checker
 
 If editing of a scene key causes at least two keys of another scene match, both of them will get red color and you have to fix the duplication, otherwise the plugin does not work properly as you expect it to work.
 
 <p align="center">
 <img src="images/tool_double_key.png"/>
 </p>
 
-### Ignore Folder:
+### Ignore Folder
 
 Every folder that is added inside this section will be ignored and scenes inside them will not get included inside scenes categories section(the section above this section).
 
@@ -107,15 +109,15 @@ As it is visible on previous pictures, it is possible to add sublists in lists a
 
 All you have to do is drag scenes by their buttons on the left and drop them on other sublists.
 
-## Demo
+# Demo
 
 Just a simple demo to show some abilities of this addon:
 
 <p align="center">
 <img src="./images/demo.gif"/>
 </p>
 
-### Demo Description
+## Demo Description
 
 1. Scene \<number\>: this button calls `change_scene` function and goes to next scene.
 2. Reset: after pressing this button, you don't go back to the previous seen scenes by pressing back button but if you do, you actually restart your scene.
@@ -124,11 +126,11 @@ Just a simple demo to show some abilities of this addon:
 5. Nothing: just shows a transition but actually does nothing.
 6. Exit: after fading out of the screen, quits the game.
 
-### Demo Code
+## Demo Code
 
 **Note**: You can use `SceneManager` node in your game after you activated `scene_manager` plugin.
 
-Example:
+### Simple Example Without any Loading Screen
 
 ```gdscript
 extends Button
@@ -152,27 +154,31 @@ extends Button
 @onready var general_options = SceneManager.create_general_options(color, timeout, clickable, add_to_back)
 
 func _ready() -> void:
-	var fade_in_first_scene_options = SceneManager.create_options(1, "fade")
-	var first_scene_general_options = SceneManager.create_general_options(Color(0, 0, 0), 1, false)
-	SceneManager.show_first_scene(fade_in_first_scene_options, first_scene_general_options)
-	# code breaks if scene is not recognizable
-	SceneManager.validate_scene(scene)
-	# code breaks if pattern is not recognizable
-	SceneManager.validate_pattern(fade_out_pattern)
-	SceneManager.validate_pattern(fade_in_pattern)
+ var fade_in_first_scene_options = SceneManager.create_options(1, "fade")
+ var first_scene_general_options = SceneManager.create_general_options(Color(0, 0, 0), 1, false)
+ SceneManager.show_first_scene(fade_in_first_scene_options, first_scene_general_options)
+ # code breaks if scene is not recognizable
+SceneManager.validate_scene(scene)
+ # code breaks if pattern is not recognizable
+ SceneManager.validate_pattern(fade_out_pattern)
+ SceneManager.validate_pattern(fade_in_pattern)
 
 func _on_button_button_up():
-	SceneManager.change_scene(scene, fade_out_options, fade_in_options, general_options)
+ SceneManager.change_scene(scene, fade_out_options, fade_in_options, general_options)
 
 func _on_reset_button_up():
-	SceneManager.reset_scene_manager()
+ SceneManager.reset_scene_manager()
 
 func _on_loading_scene_button_up():
-	SceneManager.set_recorded_scene(scene)
-	SceneManager.change_scene("loading", fade_out_options, fade_in_options, general_options)
+ SceneManager.set_recorded_scene(scene)
+ SceneManager.change_scene("loading", fade_out_options, fade_in_options, general_options)
+
+func _on_loading_scene_initialization_button_up():
+ SceneManager.set_recorded_scene(scene)
+ SceneManager.change_scene("loading_with_initialization", fade_out_options, fade_in_options, general_options)
 ```
 
-Loading Scene Code Example:
+### Simple Example With Loading Screen
 
 ```gdscript
 extends Control
@@ -183,27 +189,105 @@ extends Control
 @onready var next: Button = find_child("Next")
 
 func _ready():
-	SceneManager.load_percent_changed.connect(Callable(self, "percent_changed"))
-	SceneManager.load_finished.connect(Callable(self, "loading_finished"))
-	SceneManager.load_scene_interactive(SceneManager.get_recorded_scene())
+ SceneManager.load_percent_changed.connect(percent_changed)
+ SceneManager.load_finished.connect(loading_finished)
+ SceneManager.load_scene_interactive(SceneManager.get_recorded_scene())
 
 func percent_changed(number: int) -> void:
-	progress.value = number
+ progress.value = number
 
 func loading_finished() -> void:
-	loading.visible = false
-	next.visible = true
+ loading.visible = false
+ next.visible = true
 
 func _on_next_button_up():
-	var fade_out_options = SceneManager.create_options(1.0, "scribbles", 0.2, true)
-	var fade_in_options = SceneManager.create_options(1.0, "crooked_tiles", 0.2, true)
-	var general_options = SceneManager.create_general_options(Color(0, 0, 0), 0, false, true)
-	SceneManager.change_scene_to_loaded_scene(fade_out_options, fade_in_options, general_options)
+ var fade_out_options = SceneManager.create_options(1.0, "scribbles", 0.2, true)
+ var fade_in_options = SceneManager.create_options(1.0, "crooked_tiles", 0.2, true)
+ var general_options = SceneManager.create_general_options(Color(0, 0, 0), 0, false, true)
+ SceneManager.change_scene_to_loaded_scene(fade_out_options, fade_in_options, general_options)
+```
+
+### More Complex Example With Loading Screen for Scenarios That Scenes Need Some Time in Background
+
+#### First Part
+
+**Note**: This example is for someone who needs to generate a world in the background and then show the scene to the user or someone who generally needs to load some data in the background and then show the new scene to the user/player.
+
+```gdscript
+extends Control
+
+# Nodes
+@onready var progress: ProgressBar = find_child("Progress")
+@onready var loading: AnimatedSprite2D = find_child("Loading")
+@onready var next: Button = find_child("Next")
+@onready var label: Label = find_child("Label")
+
+var gap = 30
+
+func _ready():
+ SceneManager.load_percent_changed.connect(percent_changed)
+ SceneManager.load_finished.connect(loading_finished)
+ SceneManager.load_scene_interactive(SceneManager.get_recorded_scene())
+
+func percent_changed(number: int) -> void:
+ # the last `gap%` is for the loaded scene itself to load its own data or initialize or world generate or ...
+ progress.value = max(number - gap, 0)
+ if progress.value >= 90:
+  label.text = "World Generation . . ."
+
+func loading_finished() -> void:
+ # All loading processes are finished now
+ if progress.value == 100:
+  loading.visible = false
+  next.visible = true
+  label.text = ""
+ # Loading finishes and world initialization or world generation or whatever you wanna call it will start
+ elif progress.value == 70:
+  SceneManager.add_loaded_scene_to_scene_tree()
+  gap = 0
+  label.text = "Scene Initialization . . ."
+
+func _on_next_button_up():
+ var fade_out_options = SceneManager.create_options(1.0, "scribbles", 0.2, true)
+ var fade_in_options = SceneManager.create_options(1.0, "crooked_tiles", 0.2, true)
+ var general_options = SceneManager.create_general_options(Color(0, 0, 0), 0, false, true)
+ SceneManager.change_scene_to_existing_scene_in_scene_tree(fade_out_options, fade_in_options, general_options)
+```
+
+#### Second Part
+
+Assume this part is in the new scene which needs some time in the background:
+
+**Note**: This part emits the signal of `load_percent_changed` of SceneManager to inform the loading screen to change the percentage to inform user that something is happening.
+**Note**: After the loading process is finished, `load_finished` will be called to inform the loading screen which everything is ready to change to the new scene.
+
+```gdscript
+extends Control
+
+var t = Timer.new()
+var count = 0
+
+func _ready():
+ self.add_child(t)
+ t.timeout.connect(_on_timeout)
+ t.start(1)
+
+func _on_timeout():
+ count += 1
+ if count == 1:
+  SceneManager.load_percent_changed.emit(80 + randi_range(0, 9))
+ elif count == 2:
+  SceneManager.load_percent_changed.emit(90 + randi_range(0, 9))
+ if count == 3:
+  SceneManager.load_percent_changed.emit(100)
+  SceneManager.load_finished.emit()
+  t.timeout.disconnect(_on_timeout)
+ t.start(count + 1)
 ```
 
 ## SceneManager
 
-### Signals:
+### Signals
 
 1. load_finished => signal fires when interactively loading a scene finishes
 2. load_percent_changed(value: int) => signal fires when interactively loading a scene progress percentage updates
@@ -213,9 +297,10 @@ func _on_next_button_up():
 6. fade_in_finished => signal fires when fade in finishes
 7. fade_out_finished => signal fires when fade out finishes
 
-### Methods:
+### Methods
 
 This is the node you use inside your game code and it has these functions:
+
 1. `validate_scene`(**key**: String) -> void:
    * Checks and validates passed **key** in scenes keys. (breaks game if key doesn't exist in scenes keys)
 2. `validate_pattern`(**key**: String) -> void:
@@ -249,7 +334,7 @@ This is the node you use inside your game code and it has these functions:
    * **timeout** = between this scene and next scene, there would be a gap which can take much longer that usual(default is 0) by your choice by changing this option.
    * **clickable** = makes the scene behind the transition visuals clickable or not.
    * **add_to_back** = if true, you can go back to current scene after changing scene to next scene by going to "back" scene which means previous scene.
-9.  `show_first_scene`(**fade_in_options**: Options, **general_options**: GeneralOptions) -> void:
+9. `show_first_scene`(**fade_in_options**: Options, **general_options**: GeneralOptions) -> void:
     * Call this method inside `_ready` function of a node with a script which that node is inside the first scene that game jumps into it and this causes to have a smooth transition into the first game scene.
     * This function works just once at the beginning of the first game scene. After that, if you call this function again, nothing happens.
     * **fade_in_options** = creates it by calling `create_options` function.
@@ -261,9 +346,9 @@ This is the node you use inside your game code and it has these functions:
 12. `set_back_limit`(**input**: int) -> void:
     * Limits how much deep scene manager is allowed to record previous scenes which affects in changing scene to `back`(previous scene) functionality.
     * Allowed `input` values:
-      1.  input = -1 => unlimited (default)
-      2.  input =  0 => we can not go back to any previous scenes
-      3.  input >  0 => we can go back to `input` or less previous scenes
+      1. input = -1 => unlimited (default)
+      2. input =  0 => we can not go back to any previous scenes
+      3. input >  0 => we can go back to `input` or less previous scenes
 13. `get_scene`(**key**: String) -> PackedScene:
     * Returns PackedScene of passed scene key (blocking)
 14. `load_scene_interactive`(**key**: String) -> void:
@@ -287,3 +372,9 @@ This is the node you use inside your game code and it has these functions:
     * Records a scene key to be used for loading scenes to know where to go after getting loaded into loading scene or just for next scene to know where to go next.
 22. `get_recorded_scene`() -> String:
     * Returns recorded scene by `set_recorded_scene` function.
+23. `add_loaded_scene_to_scene_tree`() -> void:
+    * Imports loaded scene into the scene tree but doesn't change the current scene
+    * Maily used when your new loaded scene has a loading phase when added to scene tree
+    * So to use this, first has to call `load_scene_interactive` to load your scene and then have to listen on `load_finished` signal and after the signal emits, you call this function and this function adds the loaded scene to the scene tree but exactly behind the current scene so that you still can not see the new scene
+24. `change_scene_to_existing_scene_in_scene_tree`(**fade_out_options**: Options, **fade_in_options**: Options, **general_options**: GeneralOptions) -> void:
+    * when you added the loaded scene to the scene tree by `add_loaded_scene_to_scene_tree` function, you call this function after you are sure that the added scene to scene tree is completely ready and functional to change the active scene

addons/scene_manager/plugin.cfg

@@ -3,5 +3,5 @@
 name="scene_manager"
 description="A powerful scene transition manager for godot."
 author="Maktoobgar"
-version="3.7.0"
+version="3.8.0"
 script="plugin.gd"

addons/scene_manager/scene_manager.gd

@@ -370,7 +370,11 @@ func no_effect_change_scene(scene, hold_timeout: float = 0.0, add_to_back: bool
 		_set_out_transition()
 
 # imports loaded scene into the scene tree but doesn't change the scene
-# maily used when your new loaded scene has a loading phase too
+# maily used when your new loaded scene has a loading phase when added to scene tree
+# so to use this, first has to call `load_scene_interactive` to load your scene 
+# and then have to listen on `load_finished` signal and after the signal emits,
+# you call this function and this function adds the loaded scene to the scene
+# tree but exactly behind the current scene so that you still can not see the new scene
 func add_loaded_scene_to_scene_tree() -> void:
 	if _load_scene != "":
 		var scene_resource = ResourceLoader.load_threaded_get(_load_scene) as PackedScene
@@ -383,8 +387,8 @@ func add_loaded_scene_to_scene_tree() -> void:
 			_load_scene = ""
 
 # when you added the loaded scene to the scene tree by `add_loaded_scene_to_scene_tree`
-# function, you call this one after you are sure that the added scene to scene tree
-# is completely ready and functionaly to change the active scene
+# function, you call this function after you are sure that the added scene to scene tree
+# is completely ready and functional to change the active scene
 func change_scene_to_existing_scene_in_scene_tree(fade_out_options: Options, fade_in_options: Options, general_options: GeneralOptions) -> void:
 	_set_in_transition()
 	_set_clickable(general_options.clickable)

demo/loading.gd

@@ -6,8 +6,8 @@ extends Control
 @onready var next: Button = find_child("Next")
 
 func _ready():
-	SceneManager.load_percent_changed.connect(Callable(self, "percent_changed"))
-	SceneManager.load_finished.connect(Callable(self, "loading_finished"))
+	SceneManager.load_percent_changed.connect(percent_changed)
+	SceneManager.load_finished.connect(loading_finished)
 	SceneManager.load_scene_interactive(SceneManager.get_recorded_scene())
 
 func percent_changed(number: int) -> void:

demo/loading_phase_mechanic.gd

@@ -9,11 +9,13 @@ func _ready():
 	t.start(1)
 
 func _on_timeout():
-	if count == 2:
-		SceneManager.load_percent_changed.emit(130)
+	count += 1
+	if count == 1:
+		SceneManager.load_percent_changed.emit(80 + randi_range(0, 9))
+	elif count == 2:
+		SceneManager.load_percent_changed.emit(90 + randi_range(0, 9))
+	if count == 3:
+		SceneManager.load_percent_changed.emit(100)
 		SceneManager.load_finished.emit()
 		t.timeout.disconnect(_on_timeout)
-	else:
-		count += 1
-		SceneManager.load_percent_changed.emit(100 + (count * 10) + randi_range(0, 9))
-		t.start(count + 1)
+	t.start(count + 1)