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