feat: adds blocking versions of camera commands that can tween/transition.

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

@@ -0,0 +1,124 @@
+# `camera_push_block target [time] [type]`
+#
+# Pushes (moves) the camera so it points at a specific `target`. If the camera
+# was following a target (like the player) previously, it will no longer follow
+# this target. Blocks until the command completes.
+#
+# Make sure the target is reachable if camera limits have been configured.
+#
+# **Parameters**
+#
+# - *target*: Global ID of the `ESCItem` to push the camera to. `ESCItem`s have
+#   a "camera_node" property that can be set to point to a node (usually an
+#   `ESCLocation` node). If the "camera_node" property is empty, `camera_push`
+#   will point the camera at the `ESCItem`s location. If however, the `ESCItem`
+#   has its "camera_node" property set, the command will instead point the
+#   camera at the node referenced by the `ESCItem`s "camera_node" property.
+# - *time*: Number of seconds the transition should take (default: `1`)
+# - *type*: Transition type to use (default: `QUAD`)
+#
+# Supported transitions include the names of the values used
+# in the "TransitionType" enum of the "Tween" type (without the "TRANS_" prefix):
+#
+# See https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
+#
+# For more details see: https://docs.escoria-framework.org/camera
+#
+# @ESC
+extends ESCCameraBaseCommand
+class_name CameraPushBlockCommand
+
+
+# The list of supported transitions as per the link mentioned above
+const SUPPORTED_TRANSITIONS = ["LINEAR","SINE","QUINT","QUART","QUAD" ,"EXPO","ELASTIC","CUBIC",
+	"CIRC","BOUNCE","BACK"]
+
+
+# Tween for blocking
+var _camera_tween: Tween
+
+
+# Return the descriptor of the arguments of this command
+func configure() -> ESCCommandArgumentDescriptor:
+	return ESCCommandArgumentDescriptor.new(
+		1,
+		[TYPE_STRING, [TYPE_REAL, TYPE_INT], TYPE_STRING],
+		[null, 1, "QUAD"]
+	)
+
+
+# Validate whether the given arguments match the command descriptor
+func validate(arguments: Array):
+	if not .validate(arguments):
+		return false
+
+	if not escoria.object_manager.has(arguments[0]):
+		escoria.logger.error(
+			self,
+			"[%s]: invalid object. Object global id %s not found."
+					% [get_command_name(), arguments[0]]
+		)
+		return false
+
+	var target_pos = _get_target_pos(arguments[0])
+	var camera: ESCCamera = escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera
+
+	if not camera.check_point_is_inside_viewport_limits(target_pos):
+		generate_viewport_warning(target_pos, camera)
+		return false
+
+	if not arguments[2] in SUPPORTED_TRANSITIONS:
+		escoria.logger.error(
+			self,
+			(
+				"[{command_name}]: invalid transition type. Transition type {t_type} " +
+				"is not one of the accepted types : {allowed_types}"
+			).format(
+					{
+						"command_name":get_command_name(),
+						"t_type":arguments[2],
+						"allowed_types":SUPPORTED_TRANSITIONS
+					}
+				)
+		)
+		return false
+
+	_camera_tween = camera.get_tween()
+
+	return true
+
+
+# Run the command
+func run(command_params: Array) -> int:
+	(escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera)\
+		.push(
+			escoria.object_manager.get_object(command_params[0]).node,
+			command_params[1],
+			ClassDB.class_get_integer_constant("Tween", "TRANS_%s" % command_params[2])
+		)
+
+	if command_params[1] > 0.0:
+		yield(_camera_tween, "tween_completed")
+		print("------DONE-----------")
+
+	return ESCExecution.RC_OK
+
+
+# Function called when the command is interrupted.
+func interrupt():
+	escoria.logger.debug(
+		self,
+		"[%s] interrupt() function not implemented." % get_command_name()
+	)
+
+
+# Gets the appropriate target position from the `ESCItem`, as used by the camera.
+#
+# #### Parameters
+#
+# - target_global_id: The `global_id` of the `ESCItem` to check.
+#
+# **Returns** the item's position based on its camera node.
+func _get_target_pos(target_global_id: String) -> Vector2:
+	var target = escoria.object_manager.get_object(target_global_id).node as ESCItem
+	return target.get_camera_node().global_position

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

@@ -62,7 +62,7 @@ func run(command_params: Array) -> int:
 
 # Function called when the command is interrupted.
 func interrupt():
-	escoria.logger.warn(
+	escoria.logger.debug(
 		self,
 		"[%s] interrupt() function not implemented." % get_command_name()
 	)

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

@@ -0,0 +1,71 @@
+# `camera_set_target_block time object`
+#
+# Configures the camera to follow the specified target `object` as it moves
+# around the current room. The transition to focus on the `object` will happen
+# over a time period.  Blocks until the command completes.
+#
+# **Parameters**
+#
+# - *time*: Number of seconds the transition should take to move the camera
+#   to follow `object`
+# - *object*: Global ID of the target object
+#
+# For more details see: https://docs.escoria-framework.org/camera
+#
+# @ESC
+extends ESCCameraBaseCommand
+class_name CameraSetTargetBlockCommand
+
+
+# Tween for blocking
+var _camera_tween: Tween
+
+
+# Return the descriptor of the arguments of this command
+func configure() -> ESCCommandArgumentDescriptor:
+	return ESCCommandArgumentDescriptor.new(
+		2,
+		[[TYPE_REAL, TYPE_INT], TYPE_STRING],
+		[null, null]
+	)
+
+
+# Validate whether the given arguments match the command descriptor
+func validate(arguments: Array):
+	if not .validate(arguments):
+		return false
+
+	if not escoria.object_manager.has(arguments[1]):
+		escoria.logger.error(
+			self,
+			"[%s]: Invalid object: Object with global id %s not found."
+					% [get_command_name(), arguments[1]]
+		)
+		return false
+
+	var camera: ESCCamera = escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera
+	_camera_tween = camera.get_tween()
+
+	return true
+
+
+# Run the command
+func run(command_params: Array) -> int:
+	(escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera)\
+		.set_target(
+			escoria.object_manager.get_object(command_params[1]).node,
+			command_params[0]
+		)
+
+	if command_params[0] > 0.0:
+		yield(_camera_tween, "tween_completed")
+
+	return ESCExecution.RC_OK
+
+
+# Function called when the command is interrupted.
+func interrupt():
+	escoria.logger.debug(
+		self,
+		"[%s] interrupt() function not implemented." % get_command_name()
+	)

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

@@ -0,0 +1,67 @@
+# `camera_set_zoom_block magnitude [time]`
+#
+# Zooms the camera in/out to the desired `magnitude`. Values larger than '1' zoom
+# the camera out while smaller values zoom in. These values are relative to the
+# default zoom value of '1', not the current value. As such, while using a value
+# of '0.5' would double the size of the graphics, running the same command again
+# would result in no change. The zoom will happen over the given time period.
+# Blocks until the command completes.
+#
+# **Parameters**
+#
+# - *magnitude*: Magnitude of zoom
+# - *time*: Number of seconds the transition should take, with a value of `0`
+#   meaning the zoom should happen instantly (default: `0`)
+#
+# For more details see: https://docs.escoria-framework.org/camera
+#
+# @ESC
+extends ESCCameraBaseCommand
+class_name CameraSetZoomBlockCommand
+
+
+var _camera_tween: Tween
+
+
+# Return the descriptor of the arguments of this command
+func configure() -> ESCCommandArgumentDescriptor:
+	return ESCCommandArgumentDescriptor.new(
+		1,
+		[[TYPE_REAL, TYPE_INT], [TYPE_REAL, TYPE_INT]],
+		[null, 0.0]
+	)
+
+
+# Validate whether the given arguments match the command descriptor
+func validate(arguments: Array):
+	if not .validate(arguments):
+		return false
+
+	var camera: ESCCamera = escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera
+	_camera_tween = camera.get_tween()
+
+	return true
+
+
+# Run the command
+func run(command_params: Array) -> int:
+	var camera: ESCCamera = escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera
+
+	camera\
+		.set_camera_zoom(
+			command_params[0],
+			command_params[1]
+		)
+
+	if command_params[1] > 0.0:
+		yield(_camera_tween, "tween_completed")
+
+	return ESCExecution.RC_OK
+
+
+# Function called when the command is interrupted.
+func interrupt():
+	escoria.logger.debug(
+		self,
+		"[%s] interrupt() function not implemented." % get_command_name()
+	)

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

@@ -0,0 +1,70 @@
+# `camera_set_zoom_height_block pixels [time]`
+#
+# Zooms the camera in/out so it occupies the given height in pixels.
+# Blocks until the command completes.
+#
+# **Parameters**
+#
+# - *pixels*: Target height in pixels
+# - *time*: Number of seconds the transition should take, with a value of `0`
+#   meaning the zoom should happen instantly (default: `0`)
+#
+# For more details see: https://docs.escoria-framework.org/camera
+#
+# @ESC
+extends ESCBaseCommand
+class_name CameraSetZoomHeightBlockCommand
+
+
+# Tween for blocking
+var _camera_tween: Tween
+
+
+# Return the descriptor of the arguments of this command
+func configure() -> ESCCommandArgumentDescriptor:
+	return ESCCommandArgumentDescriptor.new(
+		1,
+		[TYPE_INT, [TYPE_INT, TYPE_REAL]],
+		[null, 0.0]
+	)
+
+
+# Validate whether the given arguments match the command descriptor
+func validate(arguments: Array):
+	if not .validate(arguments):
+		return false
+
+	if arguments[0] < 0:
+		escoria.logger.error(
+			self,
+			"[%s]: invalid height. Can't zoom to a negative height (%d)."
+					% [get_command_name(), arguments[0]]
+		)
+		return false
+
+	var camera: ESCCamera = escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera
+	_camera_tween = camera.get_tween()
+
+	return true
+
+
+# Run the command
+func run(command_params: Array) -> int:
+	(escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera)\
+		.set_camera_zoom(
+			command_params[0] / escoria.game_size.y,
+			command_params[1]
+		)
+
+	if command_params[1] > 0.0:
+		yield(_camera_tween, "tween_completed")
+
+	return ESCExecution.RC_OK
+
+
+# Function called when the command is interrupted.
+func interrupt():
+	escoria.logger.debug(
+		self,
+		"[%s] interrupt() function not implemented." % get_command_name()
+	)

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

@@ -0,0 +1,106 @@
+# `camera_shift_block x y [time] [type]`
+#
+# Shifts the camera by the given horizontal and vertical amounts relative to the
+# current location. Blocks until the command completes.
+#
+# **Parameters**
+#
+# - *x*: Shift by x pixels along the x-axis
+# - *y*: Shift by y pixels along the y-axis
+# - *time*: Number of seconds the transition should take, with a value of `0`
+#   meaning the zoom should happen instantly (default: `1`)
+# - *type*: Transition type to use (default: `QUAD`)
+#
+# Supported transitions include the names of the values used
+# in the "TransitionType" enum of the "Tween" type (without the "TRANS_" prefix):
+#
+# https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
+#
+# For more details see: https://docs.escoria-framework.org/camera
+#
+# @ESC
+extends ESCCameraBaseCommand
+class_name CameraShiftBlockCommand
+
+
+# The list of supported transitions as per the link mentioned above
+const SUPPORTED_TRANSITIONS = ["LINEAR","SINE","QUINT","QUART","QUAD" ,"EXPO","ELASTIC","CUBIC",
+	"CIRC","BOUNCE","BACK"]
+
+
+# Tween for blocking
+var _camera_tween: Tween
+
+
+# Return the descriptor of the arguments of this command
+func configure() -> ESCCommandArgumentDescriptor:
+	return ESCCommandArgumentDescriptor.new(
+		2,
+		[
+			[TYPE_INT, TYPE_REAL],
+			[TYPE_INT, TYPE_REAL],
+			[TYPE_INT, TYPE_REAL],
+			TYPE_STRING
+		],
+		[null, null, 1, "QUAD"]
+	)
+
+
+# Run the command
+func run(command_params: Array) -> int:
+	(escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera)\
+		.shift(
+			Vector2(
+				command_params[0],
+				command_params[1]
+			),
+			command_params[2],
+			ClassDB.class_get_integer_constant("Tween", "TRANS_%s" % command_params[3])
+		)
+
+	if command_params[2] > 0.0:
+		yield(_camera_tween, "tween_completed")
+
+	return ESCExecution.RC_OK
+
+
+# Validate whether the given arguments match the command descriptor
+func validate(arguments: Array):
+	if not .validate(arguments):
+		return false
+
+	if not arguments[3] in SUPPORTED_TRANSITIONS:
+		escoria.logger.error(
+			self,
+			(
+				"[{command_name}]: invalid transition type" +
+				"Transition type {t_type} is not one of the accepted types : {allowed_types}"
+			).format(
+				{
+					"command_name": get_command_name(),
+					"t_type":arguments[3],
+					"allowed_types":SUPPORTED_TRANSITIONS
+				}
+			)
+		)
+		return false
+
+	var camera: ESCCamera = escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera
+	var shift_by: Vector2 = Vector2(arguments[0], arguments[1])
+	var new_pos: Vector2 = Vector2(camera.position.x + shift_by.x, camera.position.y + shift_by.y)
+
+	if not camera.check_point_is_inside_viewport_limits(new_pos):
+		generate_viewport_warning(new_pos, camera)
+		return false
+
+	_camera_tween = camera.get_tween()
+
+	return true
+
+
+# Function called when the command is interrupted.
+func interrupt():
+	escoria.logger.debug(
+		self,
+		"[%s] interrupt() function not implemented." % get_command_name()
+	)

addons/escoria-core/game/scenes/camera_player/esc_camera.gd

@@ -94,14 +94,14 @@ func set_target(p_target, p_time : float = 0.0):
 		self.global_position = _target
 	else:
 		if _tween.is_active():
-			escoria.logger.warn(
+			escoria.logger.debug(
 				self,
 				"Tween is still active: %f seconds of %f completed." % [
 					_tween.tell(),
 					_tween.get_runtime()
 				]
 			)
-			_tween.emit_signal("tween_completed")
+			_tween.stop_all()
 
 		# Need to wait a frame in order to ensure the screen centre position is
 		# recalculated.
@@ -142,14 +142,22 @@ func set_camera_zoom(p_zoom_level: float, p_time: float):
 		self.zoom = _zoom_target
 	else:
 		if _tween.is_active():
-			escoria.logger.warn(
+			escoria.logger.debug(
 				self,
-				"Tween is still active: %f/%f" % [
+				"Tween is still active: %f seconds of %f completed." % [
 					_tween.tell(),
 					_tween.get_runtime()
 				]
 			)
-			_tween.emit_signal("tween_completed")
+			_tween.stop_all()
+
+		# Need to wait a frame in order to ensure the screen centre position is
+		# recalculated.
+		yield(get_tree(), "idle_frame")
+
+		set_drag_margin_enabled(false, false)
+
+		_convert_current_global_pos_for_disabled_drag_margin()
 
 		_tween.interpolate_property(
 			self,
@@ -189,14 +197,14 @@ func push(p_target, p_time: float = 0.0, p_type: int = 0):
 			self.zoom = _zoom_target
 	else:
 		if _tween.is_active():
-			escoria.logger.warn(
+			escoria.logger.debug(
 				self,
 				"Tween is still active: %f seconds of %f completed." % [
 					_tween.tell(),
 					_tween.get_runtime()
 				]
 			)
-			_tween.emit_signal("tween_completed", null, null)
+			_tween.stop_all()
 
 		if _zoom_target != Vector2():
 			_tween.interpolate_property(
@@ -247,14 +255,14 @@ func shift(p_target: Vector2, p_time: float, p_type: int):
 	_target = new_pos
 
 	if _tween.is_active():
-		escoria.logger.warn(
+		escoria.logger.debug(
 			self,
 			"Tween is still active: %f seconds of %f completed." % [
 				_tween.tell(),
 				_tween.get_runtime()
 			]
 		)
-		_tween.emit_signal("tween_completed")
+		_tween.stop_all()
 
 	# Need to wait a frame in order to ensure the screen centre position is
 	# recalculated.