fix: yield a frame for any tweening period in case camera commands are back-to-back, resulting in a potential race condition.

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

@@ -10,7 +10,7 @@
 #
 # - *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`
+#   `ESCLocation` node). If the "camera_node" property is empty, `camera_push_block`
 #   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.
@@ -18,7 +18,7 @@
 # - *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):
+# 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
 #
@@ -99,7 +99,10 @@ func run(command_params: Array) -> int:
 
 	if command_params[1] > 0.0:
 		yield(_camera_tween, "tween_completed")
-		print("------DONE-----------")
+		escoria.logger.debug(
+			self,
+			"camera_push_block tween complete."
+		)
 
 	return ESCExecution.RC_OK
 
@@ -118,7 +121,7 @@ func interrupt():
 #
 # - target_global_id: The `global_id` of the `ESCItem` to check.
 #
-# **Returns** the item's position based on its camera node.
+# **Returns** the ESCitem'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

@@ -3,6 +3,8 @@
 # Moves the camera to the given absolute position over a time period. Blocks
 # until the command completes.
 #
+# Make sure the coordinates are reachable if camera limits have been configured.
+#
 # **Parameters**
 #
 # - *time*: Number of seconds the transition should take
@@ -56,7 +58,10 @@ func run(command_params: Array) -> int:
 
 	if command_params[0] > 0.0:
 		yield(_camera_tween, "tween_completed")
-
+	escoria.logger.debug(
+			self,
+			"camera_set_pos_block tween complete."
+		)
 	return ESCExecution.RC_OK
 
 

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

@@ -1,8 +1,11 @@
 # `camera_set_target_block time object`
 #
-# Configures the camera to follow the specified target `object` as it moves
+# Configures the camera to follow the specified target `object` (ESCItem) 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.
+# 
+# The camera will move as close as it can if camera limits have been configured
+# and the `object` is at coordinates that are not reachable.
 #
 # **Parameters**
 #
@@ -59,7 +62,10 @@ func run(command_params: Array) -> int:
 
 	if command_params[0] > 0.0:
 		yield(_camera_tween, "tween_completed")
-
+	escoria.logger.debug(
+			self,
+			"camera_set_target_block tween complete."
+		)
 	return ESCExecution.RC_OK
 
 

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

@@ -7,6 +7,9 @@
 # would result in no change. The zoom will happen over the given time period.
 # Blocks until the command completes.
 #
+# Zoom operations might not be as smooth as desired if the requested zoom
+# level results in an edge of the camera meeting any defined camera limits.
+#
 # **Parameters**
 #
 # - *magnitude*: Magnitude of zoom
@@ -55,7 +58,10 @@ func run(command_params: Array) -> int:
 
 	if command_params[1] > 0.0:
 		yield(_camera_tween, "tween_completed")
-
+	escoria.logger.debug(
+			self,
+			"camera_set_zoom_block tween complete."
+		)
 	return ESCExecution.RC_OK
 
 

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

@@ -5,7 +5,7 @@
 #
 # **Parameters**
 #
-# - *pixels*: Target height in pixels
+# - *pixels*: Target height in pixels (integer values only)
 # - *time*: Number of seconds the transition should take, with a value of `0`
 #   meaning the zoom should happen instantly (default: `0`)
 #
@@ -34,7 +34,7 @@ func validate(arguments: Array):
 	if not .validate(arguments):
 		return false
 
-	if arguments[0] < 0:
+	if arguments[0] <= 0:
 		escoria.logger.error(
 			self,
 			"[%s]: invalid height. Can't zoom to a negative height (%d)."
@@ -58,7 +58,10 @@ func run(command_params: Array) -> int:
 
 	if command_params[1] > 0.0:
 		yield(_camera_tween, "tween_completed")
-
+	escoria.logger.debug(
+			self,
+			"camera_set_zoom_height_block tween complete."
+		)
 	return ESCExecution.RC_OK
 
 

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

@@ -3,6 +3,9 @@
 # Shifts the camera by the given horizontal and vertical amounts relative to the
 # current location. Blocks until the command completes.
 #
+# Make sure the destination coordinates are reachable if 
+# camera limits have been configured.
+#
 # **Parameters**
 #
 # - *x*: Shift by x pixels along the x-axis
@@ -12,9 +15,9 @@
 # - *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):
+# 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
+# See https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
 #
 # For more details see: https://docs.escoria-framework.org/camera
 #
@@ -60,7 +63,10 @@ func run(command_params: Array) -> int:
 
 	if command_params[2] > 0.0:
 		yield(_camera_tween, "tween_completed")
-
+	escoria.logger.debug(
+			self,
+			"camera_shift_block tween complete."
+		)
 	return ESCExecution.RC_OK
 
 

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

@@ -93,20 +93,20 @@ func set_target(p_target, p_time : float = 0.0):
 	if p_time == 0.0:
 		self.global_position = _target
 	else:
+		# Need to wait a frame in order to ensure the screen centre position is
+		# recalculated. Also to allow any close-calls with the tween to finish.
+		yield(get_tree(), "idle_frame")
+
 		if _tween.is_active():
 			escoria.logger.debug(
 				self,
-				"Tween is still active: %f seconds of %f completed." % [
+				"set_target tween is still active: %f seconds of %f completed." % [
 					_tween.tell(),
 					_tween.get_runtime()
 				]
 			)
 			_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()
@@ -141,20 +141,20 @@ func set_camera_zoom(p_zoom_level: float, p_time: float):
 	if p_time == 0:
 		self.zoom = _zoom_target
 	else:
+		# Need to wait a frame in order to ensure the screen centre position is
+		# recalculated. Also to allow any close-calls with the tween to finish.
+		yield(get_tree(), "idle_frame")
+
 		if _tween.is_active():
 			escoria.logger.debug(
 				self,
-				"Tween is still active: %f seconds of %f completed." % [
+				"set_camera_zoom tween is still active: %f seconds of %f completed." % [
 					_tween.tell(),
 					_tween.get_runtime()
 				]
 			)
 			_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()
@@ -196,10 +196,14 @@ func push(p_target, p_time: float = 0.0, p_type: int = 0):
 		if _zoom_target != Vector2():
 			self.zoom = _zoom_target
 	else:
+		# Need to wait a frame in order to ensure the screen centre position is
+		# recalculated. Also to allow any close-calls with the tween to finish.
+		yield(get_tree(), "idle_frame")
+
 		if _tween.is_active():
 			escoria.logger.debug(
 				self,
-				"Tween is still active: %f seconds of %f completed." % [
+				"camera push tween is still active: %f seconds of %f completed." % [
 					_tween.tell(),
 					_tween.get_runtime()
 				]
@@ -217,10 +221,6 @@ func push(p_target, p_time: float = 0.0, p_type: int = 0):
 				Tween.EASE_IN_OUT
 			)
 
-		# 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()
@@ -255,19 +255,19 @@ func shift(p_target: Vector2, p_time: float, p_type: int):
 	_target = new_pos
 
 	if _tween.is_active():
+		# Need to wait a frame in order to ensure the screen centre position is
+		# recalculated. Also to allow any close-calls with the tween to finish.
+		yield(get_tree(), "idle_frame")
+
 		escoria.logger.debug(
 			self,
-			"Tween is still active: %f seconds of %f completed." % [
+			"camera shift tween is still active: %f seconds of %f completed." % [
 				_tween.tell(),
 				_tween.get_runtime()
 			]
 		)
 		_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()