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/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="."]