feat: This enables user-defined transition and uses a tween to animate the transitions (#405)

* feat: This enables user-defined transition and uses a tween to animate the transitions

fixes #344

* docs: Automatic update of API docs

* docs: Automatic update of API docs

Co-authored-by: Dennis Ploeger <develop@dieploegers.de>
Co-authored-by: dploeger <dploeger@users.noreply.github.com>

addons/escoria-core/game/core-scripts/esc/commands/change_scene.gd

@@ -63,7 +63,10 @@ func run(command_params: Array) -> int:
 	escoria.event_manager.interrupt_running_event()
 	
 	if !command_params[1]:
-		escoria.main.scene_transition.transition_out()
+		escoria.main.scene_transition.transition(
+			"", 
+			ESCTransitionPlayer.TRANSITION_MODE.OUT
+		)
 		yield(escoria.main.scene_transition, "transition_done")
 	
 	escoria.inputs_manager.clear_stack()
@@ -109,7 +112,7 @@ func run(command_params: Array) -> int:
 					return rc[0]
 			
 			if !command_params[1]:
-				escoria.main.scene_transition.transition_in()
+				escoria.main.scene_transition.transition()
 				yield(escoria.main.scene_transition, "transition_done")
 		
 			if script.events.has("ready"):
@@ -122,7 +125,7 @@ func run(command_params: Array) -> int:
 				
 		else:
 			if !command_params[1]:
-				escoria.main.scene_transition.transition_in()
+				escoria.main.scene_transition.transition()
 				yield(escoria.main.scene_transition, "transition_done")
 				
 		# Clear queued resources

addons/escoria-core/game/core-scripts/esc/commands/transition.gd

@@ -1,7 +1,13 @@
-# `transition transition_name in|out`
+# `transition transition_name in|out [delay]`
 #
 # Performs a transition in our out manually.
 # 
+# Parameters:
+# - transition_name: Name of the transition shader from one of the transition
+#   directories
+# - in|out: Wether to play the transition in IN- or OUT-mode
+# - delay: Delay for the transition to take. Defaults to 1 second
+# 
 # @ESC
 extends ESCBaseCommand
 class_name TransitionCommand
@@ -11,8 +17,8 @@ class_name TransitionCommand
 func configure() -> ESCCommandArgumentDescriptor:
 	return ESCCommandArgumentDescriptor.new(
 		2, 
-		[TYPE_STRING, TYPE_STRING],
-		[null, null]
+		[TYPE_STRING, TYPE_STRING, TYPE_REAL],
+		[null, null, 1.0]
 	)
 	
 	
@@ -39,7 +45,14 @@ func validate(arguments: Array):
 
 # Run the command
 func run(command_params: Array) -> int:
-	var transition_player = escoria.main.scene_transition
-	transition_player.call("transition_%s" % command_params[1], command_params[0])
-	var animation_finished = yield(transition_player, "transition_done")
+	escoria.main.scene_transition.transition(
+		command_params[0],
+		ESCTransitionPlayer.TRANSITION_MODE.OUT if command_params[1] == "out" \
+				else ESCTransitionPlayer.TRANSITION_MODE.IN,
+		command_params[2]
+	)
+	yield(
+		escoria.main.scene_transition, 
+		"transition_done"
+	)
 	return ESCExecution.RC_OK

addons/escoria-core/game/main.gd

@@ -18,11 +18,13 @@ var current_scene: Node
 var wait_level
 
 # Reference to the scene transition node
-onready var scene_transition = $layers/curtain/scene_transition
+onready var scene_transition: ESCTransitionPlayer
 
 
 # Connect the wait timer event
 func _ready() -> void:
+	scene_transition = ESCTransitionPlayer.new()
+	$layers/curtain.add_child(scene_transition)
 	$layers/wait_timer.connect("timeout", self, "_on_wait_finished")
 
 

addons/escoria-core/game/main.tscn

@@ -1,9 +1,8 @@
-[gd_scene load_steps=7 format=2]
+[gd_scene load_steps=6 format=2]
 
 [ext_resource path="res://addons/escoria-core/game/main.gd" type="Script" id=1]
 [ext_resource path="res://addons/escoria-core/game/scenes/esc_prompt/esc_prompt_popup.tscn" type="PackedScene" id=2]
 [ext_resource path="res://addons/escoria-core/game/scenes/sound/esc_music_player.tscn" type="PackedScene" id=3]
-[ext_resource path="res://addons/escoria-core/game/scenes/transitions/transition.tscn" type="PackedScene" id=4]
 [ext_resource path="res://addons/escoria-core/game/scenes/sound/esc_sound_player.tscn" type="PackedScene" id=5]
 [ext_resource path="res://addons/escoria-core/game/scenes/sound/esc_speech_player.tscn" type="PackedScene" id=6]
 
@@ -15,8 +14,6 @@ script = ExtResource( 1 )
 [node name="curtain" type="CanvasLayer" parent="layers"]
 layer = 20
 
-[node name="scene_transition" parent="layers/curtain" instance=ExtResource( 4 )]
-
 [node name="menu" type="CanvasLayer" parent="layers"]
 
 [node name="wait_timer" type="Timer" parent="layers"]

addons/escoria-core/game/scenes/transitions/esc_transition_player.gd

@@ -0,0 +1,117 @@
+# A transition player for scene changes
+extends ColorRect
+class_name ESCTransitionPlayer
+
+# Emitted when the transition was played
+signal transition_done
+
+
+# The valid transition modes
+enum TRANSITION_MODE {
+	IN,
+	OUT
+}
+
+
+# The tween instance to animate
+var _tween: Tween
+
+# If the current tween was canceled
+var _was_canceled: bool = false
+
+
+# Fade in when the scene is starting
+func _ready() -> void:
+	anchor_left = 0
+	anchor_top = 0
+	anchor_right = 1
+	anchor_bottom = 1
+	color = Color.white
+	mouse_filter = MOUSE_FILTER_IGNORE
+	_tween = Tween.new()
+	add_child(_tween)
+	_tween.connect("tween_all_completed", self, "_on_tween_completed")
+	
+	transition()
+
+
+# Play a transition animation
+#
+# ## Parameters
+# 
+# - transition_name: name of the transition to play (if empty string, uses
+# the default transition)
+# - mode: Mode to transition (in/out)
+# - duration: The duration the transition should take
+func transition(
+	transition_name: String = "", 
+	mode: int = TRANSITION_MODE.IN,
+	duration: float = 1.0
+) -> void:
+	if not has_transition(transition_name):
+		escoria.logger.report_errors(
+			"transition: Transition %s not found" % transition_name,
+			[]
+		)
+		
+	material = ResourceLoader.load(get_transition(transition_name))
+	
+	var start = 0
+	var end = 1
+	
+	if mode == TRANSITION_MODE.OUT:
+		start = 1
+		end = 0
+	
+	if _tween.is_active():
+		_was_canceled = true
+		_tween.stop_all()
+		_tween.remove_all()
+	
+	_tween.interpolate_property(
+		$".",
+		"material:shader_param/cutoff",
+		start,
+		end,
+		duration
+	)
+	_was_canceled = false
+	_tween.start()
+	
+
+
+# Returns the full path for a transition shader based on its name
+#
+# ## Parameters
+#
+# - name: The name of the transition to test
+#
+# *Returns* the full path to the shader or an empty string, if it can't be found
+func get_transition(name: String) -> String:
+	if name.empty():
+		name = ProjectSettings.get_setting(
+			"escoria/ui/default_transition"
+		)
+	for directory in ProjectSettings.get_setting("escoria/ui/transition_paths"):
+		if ResourceLoader.exists(directory.plus_file("%s.material" % name)):
+			return directory.plus_file("%s.material" % name)
+	return ""
+
+
+# Returns true whether the transition scene has a transition corresponding 
+# to name provided.
+#
+# ## Parameters
+#
+# - name: The name of the transition to test
+#
+# *Returns* true if a transition exists with given name.
+func has_transition(name: String) -> bool:
+	return not get_transition(name) == ""
+	
+
+func _on_tween_completed():
+	if not _was_canceled:
+		emit_signal("transition_done")
+		_tween.stop_all()
+		_tween.remove_all()

addons/escoria-core/game/scenes/transitions/transition.gd

@@ -1,68 +0,0 @@
-# A transition player for scene changes
-extends ColorRect
-
-# Emitted when the transition was played
-signal transition_done
-
-
-# The name of the default transition to play
-export(
-	String, 
-	"fade_black", 
-	"fade_white", 
-	"curtain"
-) var transition_name: String
-
-
-
-# Reference to the _AnimationPlayer_ node
-onready var _anim_player := $AnimationPlayer
-
-
-# Fade in when the scene is starting
-func _ready() -> void:
-	transition_in()
-
-
-# Transition out 
-#
-# ## Parameters
-# 
-# - p_transition_name: name of the transition to play (if empty string, uses
-# the default transition)
-func transition_out(p_transition_name: String = "") -> void:
-	if p_transition_name.empty():
-		_anim_player.play_backwards(transition_name)
-	else:
-		_anim_player.play_backwards(p_transition_name)
-	yield(_anim_player, "animation_finished")
-	emit_signal("transition_done")
-	_anim_player.seek(0.0)
-
-	
-# Transition in
-#
-# ## Parameters
-# 
-# - p_transition_name: name of the transition to play (if empty string, uses
-# the default transition)
-func transition_in(p_transition_name: String = "") -> void:
-	if p_transition_name.empty():
-		_anim_player.play(transition_name)
-	else:
-		_anim_player.play(p_transition_name)
-	yield(_anim_player, "animation_finished")
-	emit_signal("transition_done")
-	_anim_player.seek(0.0)
-
-
-# Returns true whether the transition scene has a transition corresponding 
-# to name provided.
-#
-# ## Parameters
-#
-# - p_name: The name of the transition to test
-#
-# *Returns* true if a transition exists with given name.
-func has_transition(p_name: String) -> bool:
-	return _anim_player.has_animation(p_name)

addons/escoria-core/game/scenes/transitions/transition.tscn

@@ -1,124 +1,7 @@
-[gd_scene load_steps=6 format=2]
+[gd_scene load_steps=3 format=2]
 
-[ext_resource path="res://addons/escoria-core/game/scenes/transitions/transition.gd" type="Script" id=1]
-[ext_resource path="res://addons/escoria-core/game/scenes/transitions/shaders/transition.material" type="Material" id=2]
-
-[sub_resource type="Animation" id=1]
-resource_name = "curtain"
-tracks/0/type = "value"
-tracks/0/path = NodePath(".:material:shader_param/cutoff")
-tracks/0/interp = 1
-tracks/0/loop_wrap = true
-tracks/0/imported = false
-tracks/0/enabled = true
-tracks/0/keys = {
-"times": PoolRealArray( 0, 1 ),
-"transitions": PoolRealArray( 1, 1 ),
-"update": 0,
-"values": [ 0.0, 1.0 ]
-}
-tracks/1/type = "value"
-tracks/1/path = NodePath(".:material:shader_param/color")
-tracks/1/interp = 1
-tracks/1/loop_wrap = true
-tracks/1/imported = false
-tracks/1/enabled = true
-tracks/1/keys = {
-"times": PoolRealArray( 0 ),
-"transitions": PoolRealArray( 1 ),
-"update": 0,
-"values": [ Color( 0, 0, 0, 1 ) ]
-}
-tracks/2/type = "value"
-tracks/2/path = NodePath(".:modulate")
-tracks/2/interp = 1
-tracks/2/loop_wrap = true
-tracks/2/imported = false
-tracks/2/enabled = true
-tracks/2/keys = {
-"times": PoolRealArray( 0 ),
-"transitions": PoolRealArray( 1 ),
-"update": 0,
-"values": [ Color( 1, 1, 1, 1 ) ]
-}
-
-[sub_resource type="Animation" id=2]
-length = 0.5
-tracks/0/type = "value"
-tracks/0/path = NodePath(".:modulate")
-tracks/0/interp = 1
-tracks/0/loop_wrap = true
-tracks/0/imported = false
-tracks/0/enabled = true
-tracks/0/keys = {
-"times": PoolRealArray( 0, 0.5 ),
-"transitions": PoolRealArray( 1, 1 ),
-"update": 0,
-"values": [ Color( 0, 0, 0, 0 ), Color( 0, 0, 0, 1 ) ]
-}
-tracks/1/type = "value"
-tracks/1/path = NodePath(".:material:shader_param/cutoff")
-tracks/1/interp = 1
-tracks/1/loop_wrap = true
-tracks/1/imported = false
-tracks/1/enabled = true
-tracks/1/keys = {
-"times": PoolRealArray( 0 ),
-"transitions": PoolRealArray( 1 ),
-"update": 0,
-"values": [ 0.0 ]
-}
-tracks/2/type = "value"
-tracks/2/path = NodePath(".:material:shader_param/color")
-tracks/2/interp = 1
-tracks/2/loop_wrap = true
-tracks/2/imported = false
-tracks/2/enabled = true
-tracks/2/keys = {
-"times": PoolRealArray( 0 ),
-"transitions": PoolRealArray( 1 ),
-"update": 0,
-"values": [ Color( 0, 0, 0, 1 ) ]
-}
-
-[sub_resource type="Animation" id=3]
-length = 0.5
-tracks/0/type = "value"
-tracks/0/path = NodePath(".:modulate")
-tracks/0/interp = 1
-tracks/0/loop_wrap = true
-tracks/0/imported = false
-tracks/0/enabled = true
-tracks/0/keys = {
-"times": PoolRealArray( 0, 0.5 ),
-"transitions": PoolRealArray( 1, 1 ),
-"update": 0,
-"values": [ Color( 1, 1, 1, 0 ), Color( 1, 1, 1, 1 ) ]
-}
-tracks/1/type = "value"
-tracks/1/path = NodePath(".:material:shader_param/cutoff")
-tracks/1/interp = 1
-tracks/1/loop_wrap = true
-tracks/1/imported = false
-tracks/1/enabled = true
-tracks/1/keys = {
-"times": PoolRealArray( 0 ),
-"transitions": PoolRealArray( 1 ),
-"update": 0,
-"values": [ 0.0 ]
-}
-tracks/2/type = "value"
-tracks/2/path = NodePath(".:material:shader_param/color")
-tracks/2/interp = 1
-tracks/2/loop_wrap = true
-tracks/2/imported = false
-tracks/2/enabled = true
-tracks/2/keys = {
-"times": PoolRealArray( 0 ),
-"transitions": PoolRealArray( 1 ),
-"update": 0,
-"values": [ Color( 1, 1, 1, 1 ) ]
-}
+[ext_resource path="res://addons/escoria-core/game/scenes/transitions/esc_transition_player.gd" type="Script" id=1]
+[ext_resource path="res://addons/escoria-core/game/scenes/transitions/shaders/curtain.material" type="Material" id=2]
 
 [node name="scene_transition" type="ColorRect"]
 material = ExtResource( 2 )
@@ -129,9 +12,5 @@ script = ExtResource( 1 )
 __meta__ = {
 "_edit_use_anchors_": false
 }
-transition_name = "curtain"
 
-[node name="AnimationPlayer" type="AnimationPlayer" parent="."]
-anims/curtain = SubResource( 1 )
-anims/fade_black = SubResource( 2 )
-anims/fade_white = SubResource( 3 )
+[node name="Tween" type="Tween" parent="."]

addons/escoria-core/plugin.gd

@@ -92,6 +92,29 @@ func set_escoria_ui_settings():
 		}
 		ProjectSettings.add_property_info(game_scene_property_info)
 	
+	if !ProjectSettings.has_setting("escoria/ui/default_transition"):
+		ProjectSettings.set_setting(
+			"escoria/ui/default_transition",
+			"curtain"
+		)
+		ProjectSettings.add_property_info({
+			"name": "escoria/ui/default_transition",
+			"type": TYPE_STRING
+		})
+		
+	if !ProjectSettings.has_setting("escoria/ui/transition_paths"):
+		ProjectSettings.set_setting(
+			"escoria/ui/transition_paths",
+			[
+				"res://addons/escoria-core/game/scenes/transitions/shaders/"
+			]
+		)
+		ProjectSettings.add_property_info({
+			"name": "escoria/ui/transition_paths",
+			"type": TYPE_STRING_ARRAY,
+			"hint": PROPERTY_HINT_DIR
+		})
+	
 
 # Prepare the settings in the Escoria main category
 func set_escoria_main_settings():