components.py

"""
Game components module for Pong.

This module contains the core game objects: Ball and Paddle.
Each class encapsulates the behavior and rendering of its respective game element.
"""
import pygame as py
from typing import Tuple

# Type alias for color
Color = Tuple[int, int, int]

WHITE: Color = (255, 255, 255)
BLACK: Color = (0, 0, 0)
GREEN: Color = (19, 58, 38)

class Ball:
    """
    Represents the ball in the Pong game.
    
    The ball moves across the screen and bounces off paddles and walls.
    Its velocity can be modified based on where it hits the paddle.
    
    Attributes:
        COLOR: The color of the ball (RGB tuple)
        MAX_VEL: Maximum velocity of the ball
        x: Current x-coordinate
        y: Current y-coordinate
        radius: Radius of the ball
        x_vel: Current velocity in x-direction
        y_vel: Current velocity in y-direction
        original_x: Starting x-coordinate for reset
        original_y: Starting y-coordinate for reset
    """
    COLOR: Color = WHITE
    MAX_VEL: int = 5

    def __init__(self, x: int, y: int, radius: int) -> None:
        """
        Initialize a Ball instance.
        
        Args:
            x: Starting x-coordinate
            y: Starting y-coordinate
            radius: Radius of the ball
        """
        self.x: int = x
        self.y: int = y
        self.original_x: int = x
        self.original_y: int = y
        self.radius: int = radius
        self.x_vel: int = self.MAX_VEL
        self.y_vel: int = 0

    def draw(self, win: py.Surface) -> None:
        """
        Draw the ball on the given surface.
        
        Args:
            win: Pygame surface to draw on
        """
        py.draw.circle(win, self.COLOR, (int(self.x), int(self.y)), self.radius)

    def move(self) -> None:
        """
        Update the ball's position based on its current velocity.
        
        This method should be called once per frame to animate the ball.
        """
        self.x += self.x_vel
        self.y += self.y_vel

    def reset(self) -> None:
        """
        Reset the ball to its original position and invert horizontal direction.
        
        Called when a point is scored to restart play from the center.
        """
        self.x = self.original_x
        self.y = self.original_y
        self.y_vel = 0
        self.x_vel *= -1
    
    def __repr__(self) -> str:
        """Return string representation of Ball for debugging."""
        return f"Ball(x={self.x:.1f}, y={self.y:.1f}, vel=({self.x_vel}, {self.y_vel}))"


class Paddle:
    """
    Represents a paddle in the Pong game.
    
    Paddles are controlled by players to hit the ball back and forth.
    They can move vertically within the screen boundaries.
    
    Attributes:
        COLOR: The color of the paddle (RGB tuple)
        VEL: Movement speed of the paddle
        x: Current x-coordinate
        y: Current y-coordinate
        width: Width of the paddle
        height: Height of the paddle
        original_x: Starting x-coordinate for reset
        original_y: Starting y-coordinate for reset
    """
    COLOR: Color = WHITE
    VEL: int = 4

    def __init__(self, x: int, y: int, width: int, height: int) -> None:
        """
        Initialize a Paddle instance.
        
        Args:
            x: Starting x-coordinate
            y: Starting y-coordinate
            width: Width of the paddle
            height: Height of the paddle
        """
        self.x: int = x
        self.y: int = y
        self.original_x: int = x
        self.original_y: int = y
        self.width: int = width
        self.height: int = height

    def draw(self, win: py.Surface) -> None:
        """
        Draw the paddle on the given surface.
        
        Args:
            win: Pygame surface to draw on
        """
        py.draw.rect(win, self.COLOR, (self.x, self.y, self.width, self.height))

    def move(self, up: bool = True) -> None:
        """
        Move the paddle up or down.
        
        Args:
            up: If True, move up; if False, move down
        """
        if up:
            self.y -= self.VEL
        else:
            self.y += self.VEL

    def reset(self) -> None:
        """
        Reset the paddle to its original position.
        
        Called when a new game round starts.
        """
        self.x = self.original_x
        self.y = self.original_y
    
    def get_rect(self) -> py.Rect:
        """
        Get a pygame Rect object representing the paddle's bounding box.
        
        Useful for collision detection.
        
        Returns:
            pygame.Rect object with paddle dimensions and position
        """
        return py.Rect(self.x, self.y, self.width, self.height)
    
    def __repr__(self) -> str:
        """Return string representation of Paddle for debugging."""
        return f"Paddle(x={self.x}, y={self.y}, size=({self.width}x{self.height}))"