chore: fills in missing docstrings; adds new base class for cameras to avoid duplication of viewport warnings.

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

@@ -25,7 +25,7 @@
 # For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
-extends ESCBaseCommand
+extends ESCCameraBaseCommand
 class_name CameraPushCommand
 
 # The list of supported transitions as per the link mentioned above
@@ -59,7 +59,7 @@ func validate(arguments: Array):
 	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)
+		generate_viewport_warning(target_pos, camera)
 		return false
 
 	if not arguments[2] in SUPPORTED_TRANSITIONS:
@@ -100,27 +100,13 @@ func interrupt():
 	)
 
 
-func _generate_viewport_warning(new_pos: Vector2, camera: ESCCamera) -> void:
+# Gets the appropriate target position from the `ESCItem`, as used by the camera.
-	var camera_limit: Rect2 = camera.get_camera_limit_rect()
+#
-	var message: String = \
+# #### Parameters
-	"""
+#
-	[%s]: Invalid camera position. Camera cannot be moved to %s as this is outside the viewport with current camera limit %s. 
+# - target_global_id: The `global_id` of the `ESCItem` to check.
-	Current valid ranges for positions are: x = %s inclusive; y = %s inclusive.
+#
-	"""
+# **Returns** the item's position based on its camera node.
-	
-	escoria.logger.warn(
-		self,
-		message
-			% [
-				get_command_name(),
-				new_pos.floor(),
-				camera_limit,
-				camera.get_current_valid_viewport_values_x(),
-				camera.get_current_valid_viewport_values_y()
-			]
-	)
-
-
 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_limits.gd

@@ -14,7 +14,7 @@
 # For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
-extends ESCBaseCommand
+extends ESCCameraBaseCommand
 class_name CameraSetLimitsCommand
 
 

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

@@ -11,7 +11,7 @@
 # For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
-extends ESCBaseCommand
+extends ESCCameraBaseCommand
 class_name CameraSetPosCommand
 
 
@@ -31,10 +31,9 @@ func validate(arguments: Array):
 
 	var new_pos: Vector2 = Vector2(arguments[1], arguments[2])
 	var camera: ESCCamera = escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera
-	var camera_limit: Rect2 = camera.get_camera_limit_rect()
 
 	if not camera.check_point_is_inside_viewport_limits(new_pos):
-		_generate_viewport_warning(new_pos, camera)
+		generate_viewport_warning(new_pos, camera)
 		return false
 
 	return true
@@ -56,24 +55,3 @@ func interrupt():
 		self,
 		"[%s] interrupt() function not implemented." % get_command_name()
 	)
-
-
-func _generate_viewport_warning(new_pos: Vector2, camera: ESCCamera) -> void:
-	var camera_limit: Rect2 = camera.get_camera_limit_rect()
-	var message: String = \
-	"""
-	[%s]: Invalid camera position. Camera cannot be moved to %s as this is outside the viewport with current camera limit %s. 
-	Current valid ranges for positions are: x = %s inclusive; y = %s inclusive.
-	"""
-	
-	escoria.logger.warn(
-		self,
-		message
-			% [
-				get_command_name(),
-				new_pos.floor(),
-				camera_limit,
-				camera.get_current_valid_viewport_values_x(),
-				camera.get_current_valid_viewport_values_y()
-			]
-	)

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

@@ -13,7 +13,7 @@
 # For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
-extends ESCBaseCommand
+extends ESCCameraBaseCommand
 class_name CameraSetTargetCommand
 
 

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

@@ -15,7 +15,7 @@
 # For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
-extends ESCBaseCommand
+extends ESCCameraBaseCommand
 class_name CameraSetZoomCommand
 
 

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

@@ -19,7 +19,7 @@
 # For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
-extends ESCBaseCommand
+extends ESCCameraBaseCommand
 class_name CameraShiftCommand
 
 # The list of supported transitions as per the link mentioned above
@@ -76,12 +76,11 @@ func validate(arguments: Array):
 		return false
 
 	var camera: ESCCamera = escoria.object_manager.get_object(escoria.object_manager.CAMERA).node as ESCCamera
-	var camera_limit: Rect2 = Rect2(camera.limit_left, camera.limit_top, camera.limit_right - camera.limit_left, camera.limit_bottom - camera.limit_top)
 	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)
+		generate_viewport_warning(new_pos, camera)
 		return false
 
 	return true
@@ -93,24 +92,3 @@ func interrupt():
 		self,
 		"[%s] interrupt() function not implemented." % get_command_name()
 	)
-
-
-func _generate_viewport_warning(new_pos: Vector2, camera: ESCCamera) -> void:
-	var camera_limit: Rect2 = camera.get_camera_limit_rect()
-	var message: String = \
-	"""
-	[%s]: Invalid camera position. Camera cannot be moved to %s as this is outside the viewport with current camera limit %s. 
-	Current valid ranges for positions are: x = %s inclusive; y = %s inclusive.
-	"""
-	
-	escoria.logger.warn(
-		self,
-		message
-			% [
-				get_command_name(),
-				new_pos.floor(),
-				camera_limit,
-				camera.get_current_valid_viewport_values_x(),
-				camera.get_current_valid_viewport_values_y()
-			]
-	)

addons/escoria-core/game/core-scripts/esc/types/esc_camera_base_command.gd

@@ -0,0 +1,29 @@
+extends ESCBaseCommand
+class_name ESCCameraBaseCommand
+
+
+# Generaters a log entry when attempting to move the camera to an invalid position.
+#
+# #### Parameters
+#
+# - pos: The offending position.
+# - camera: The camera object that `pos` was checked against.
+func generate_viewport_warning(pos: Vector2, camera: ESCCamera) -> void:
+	var camera_limit: Rect2 = camera.get_camera_limit_rect()
+	var message: String = \
+	"""
+	[%s]: Invalid camera position. Camera cannot be moved to %s as this is outside the viewport with current camera limit %s. 
+	Current valid ranges for positions are: x = %s inclusive; y = %s inclusive.
+	"""
+	
+	escoria.logger.warn(
+		self,
+		message
+			% [
+				get_command_name(),
+				pos.floor(),
+				camera_limit,
+				camera.get_current_valid_viewport_values_x(),
+				camera.get_current_valid_viewport_values_y()
+			]
+	)

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

@@ -3,13 +3,6 @@ extends Camera2D
 class_name ESCCamera
 	
 
-enum Compensation {
-	NONE,
-	ADDED,
-	SUBTRACTED
-}
-
-
 # Reference to the tween node for animating camera movements
 var _tween: Tween
 
@@ -328,18 +321,30 @@ func check_point_is_inside_viewport_limits(point: Vector2) -> bool:
 	return limits_to_test.has_point(point)
 
 
+# Returns the inclusive minimum and maximum values for the x-component of the current valid viewport.
+# Mainly used in any logging messages related to same.
+#
+# **Returns** the inclusive minimum and maximum values for the x-component of the current valid viewport.
 func get_current_valid_viewport_values_x() -> Array:
 	var viewport_rect: Rect2 = get_viewport_rect()
 	
 	return [limit_left + viewport_rect.size.x * 0.5, limit_right - viewport_rect.size.x * 0.5]
 
 
+# Returns the inclusive minimum and maximum values for the y-component of the current valid viewport.
+# Mainly used in any logging messages related to same.
+#
+# **Returns* the inclusive minimum and maximum values for the y-component of the current valid viewport.
 func get_current_valid_viewport_values_y() -> Array:
 	var viewport_rect: Rect2 = get_viewport_rect()
 	
 	return [limit_top + viewport_rect.size.y * 0.5, limit_bottom - viewport_rect.size.y * 0.5]
 
 
+# Returns the camera's current limits as a Rect2.
+# Mainly used in any logging messages related to same.
+#
+# **Returns** the camera's current limits as a Rect2.
 func get_camera_limit_rect() -> Rect2:
 	return Rect2(limit_left, limit_top, limit_right - limit_left, limit_bottom - limit_top)
 
@@ -386,6 +391,17 @@ func _convert_current_global_pos_for_disabled_drag_margin() -> void:
 	self.global_position = ret_position
 
 
+# Converts the given position set with drag margins enabled to the same position when calculated
+# with drag margins disabled.
+#
+# This is helpful for preventing the camera from "jumping" when disabling drag margins, e.g. in
+# order to perform some camera translations/tweening.
+#
+# #### Parameters
+# - pos: Position to be converted.
+#
+# **Returns** the position on the screen that would be the equivalent of `pos` when rendered with
+# drag margins disabled.
 func _convert_pos_for_disabled_drag_margin(pos: Vector2) -> Vector2:
 	var viewport_rect: Rect2 = get_viewport_rect()
 	var ret_position: Vector2 = pos