From 5ba65113e67b321427443bb708cc1f861ca8af15 Mon Sep 17 00:00:00 2001
From: Alcibiades Athens <alcibiades.eth@protonmail.com>
Date: Sat, 28 Dec 2024 16:59:05 -0500
Subject: [PATCH 1/4] feat: more realistic

---
 src/ball.rs   | 104 ++++++++++----------
 src/player.rs | 266 +++++++++++++++++++++++++++++++++++---------------
 2 files changed, 237 insertions(+), 133 deletions(-)

diff --git a/src/ball.rs b/src/ball.rs
index b0ca3e1..45670e9 100644
--- a/src/ball.rs
+++ b/src/ball.rs
@@ -15,10 +15,11 @@ use bevy_rapier2d::prelude::*;
 
 /// Physical properties of the ball that define its behavior
 const BALL_SIZE: f32 = 0.3; // Diameter in world units
-const BALL_SPEED: f32 = 10.0; // Constant speed the ball should maintain
-const SPEED_TOLERANCE: f32 = 0.5; // Allowed speed variation before correction
-const RESTITUTION: f32 = 1.5; // Bounciness (>1 means gaining energy)
-const BALL_MASS: f32 = 0.1; // Mass affects collision response
+const MIN_VELOCITY: f32 = 7.0; // Minimum speed for the ball
+const MAX_VELOCITY: f32 = 32.0; // Maximum speed for the ball
+const SPEED_TOLERANCE: f32 = 3.0; // Allowed speed variation before correction
+const RESTITUTION: f32 = 0.9; // Bounciness (>1 means gaining energy)
+const BALL_MASS: f32 = 0.0027; // Mass affects collision response
 
 /// Marker component to identify ball entities.
 /// Used for querying and managing ball-specific behavior.
@@ -38,41 +39,42 @@ pub fn create_ball(
     materials: &mut ResMut<Assets<ColorMaterial>>,
     served_by_p1: bool,
 ) {
-    // Determine initial direction based on server
     let direction = if served_by_p1 { 1 } else { -1 };
+    let initial_velocity = Vec2::new(MIN_VELOCITY * direction as f32, 0.0);
 
-    commands.spawn((
-        // Identification and visual components
-        Ball,                                                             // Marker component
-        Mesh2d(meshes.add(Circle::new(BALL_SIZE / 2.0))),                 // Visual shape
-        MeshMaterial2d(materials.add(ColorMaterial::from(Color::WHITE))), // Color
-        Transform::from_xyz(0.0, 0.0, 0.0),                               // Start at center
-        // Physics body configuration
-        RigidBody::Dynamic,              // Moves based on physics
-        Collider::ball(BALL_SIZE / 2.0), // Circular collision shape
-        // Initial velocity (horizontal only)
-        Velocity::linear(Vec2::new(BALL_SPEED * direction as f32, 0.0)),
-        // Collision response properties
-        Restitution {
+    commands
+        .spawn(Ball)
+        // Visual components
+        .insert(Mesh2d(meshes.add(Circle::new(BALL_SIZE / 2.0))))
+        .insert(MeshMaterial2d(
+            materials.add(ColorMaterial::from(Color::WHITE)),
+        ))
+        .insert(Transform::from_xyz(0.0, 0.0, 0.0))
+        // Physics body setup
+        .insert(RigidBody::Dynamic)
+        .insert(Collider::ball(BALL_SIZE / 2.0))
+        .insert(Velocity::linear(initial_velocity))
+        // Collision properties
+        .insert(Restitution {
             coefficient: RESTITUTION,
-            combine_rule: CoefficientCombineRule::Max, // Use highest restitution in collisions
-        },
-        Friction {
-            coefficient: 0.0,                          // Frictionless
-            combine_rule: CoefficientCombineRule::Min, // Use lowest friction in collisions
-        },
-        // Physics behavior modifiers
-        Damping {
-            linear_damping: 0.0,  // No speed loss over time
-            angular_damping: 0.0, // No rotation slowdown
-        },
-        GravityScale(0.0), // Ignore gravity
-        // Collision detection settings
-        Ccd::enabled(),                            // Continuous collision detection
-        ActiveCollisionTypes::all(),               // Detect all collision types
-        ActiveEvents::COLLISION_EVENTS,            // Generate collision events
-        AdditionalMassProperties::Mass(BALL_MASS), // Set specific mass
-    ));
+            combine_rule: CoefficientCombineRule::Max,
+        })
+        .insert(Friction {
+            coefficient: 0.0,
+            combine_rule: CoefficientCombineRule::Min,
+        })
+        // Physics modifiers
+        .insert(Damping {
+            linear_damping: 0.0,
+            angular_damping: 0.0,
+        })
+        .insert(GravityScale(0.0))
+        // Collision detection
+        .insert(Ccd::enabled())
+        .insert(Sleeping::disabled())
+        .insert(ActiveCollisionTypes::all())
+        .insert(ActiveEvents::COLLISION_EVENTS)
+        .insert(AdditionalMassProperties::Mass(BALL_MASS));
 }
 
 /// System to clean up the ball when exiting the Playing state.
@@ -83,24 +85,22 @@ fn cleanup_ball(mut commands: Commands, ball_query: Query<Entity, With<Ball>>) {
     }
 }
 
-/// System that maintains constant ball speed regardless of collisions.
-///
-/// This is necessary because:
-/// 1. Collisions can change the ball's speed
-/// 2. We want the game to maintain a consistent pace
-/// 3. Numerical errors can accumulate over time
-///
-/// The system checks the current speed against BALL_SPEED and
-/// corrects it if it deviates beyond SPEED_TOLERANCE.
 fn maintain_ball_velocity(mut query: Query<&mut Velocity, With<Ball>>) {
     for mut velocity in query.iter_mut() {
         let current_velocity = velocity.linvel;
         let current_speed = current_velocity.length();
 
-        // Correct speed if it's outside tolerance range
-        if (current_speed - BALL_SPEED).abs() > SPEED_TOLERANCE {
-            // Maintain direction but normalize speed
-            velocity.linvel = current_velocity.normalize() * BALL_SPEED;
+        // Check absolute magnitude and adjust if needed
+        if current_speed != 0.0 {  // Prevent division by zero
+            let new_speed = if current_speed.abs() < MIN_VELOCITY {
+                MIN_VELOCITY
+            } else if current_speed.abs() > MAX_VELOCITY {
+                MAX_VELOCITY
+            } else {
+                current_speed
+            };
+
+            velocity.linvel = current_velocity.normalize() * new_speed;
         }
     }
 }
@@ -113,10 +113,6 @@ impl Plugin for BallPlugin {
         app
             // Clean up ball when leaving Playing state
             .add_systems(OnExit(GameState::Playing), cleanup_ball)
-            // Maintain ball velocity during gameplay
-            .add_systems(
-                Update,
-                maintain_ball_velocity.run_if(in_state(GameState::Playing)),
-            );
+            .add_systems(Update, maintain_ball_velocity);
     }
 }
diff --git a/src/player.rs b/src/player.rs
index bb52310..b504c13 100644
--- a/src/player.rs
+++ b/src/player.rs
@@ -12,21 +12,28 @@ use crate::ball::Ball;
 use crate::GameState;
 use bevy::app::{App, Plugin, Startup, Update};
 use bevy::prelude::*;
+use bevy::render::mesh::Indices;
+use bevy::render::render_asset::RenderAssetUsages;
+use bevy::render::render_resource::PrimitiveTopology;
 use bevy_rapier2d::prelude::*;
 
 /// Constants defining the player paddles' physical and gameplay properties
-const PADDLE_WIDTH: f32 = 0.5; // Width in world units
-const PADDLE_HEIGHT: f32 = 2.0; // Height in world units
-const PADDLE_SPEED: f32 = 5.0; // Movement speed in units per second
+const PADDLE_SPEED: f32 = 20.0; // Movement speed in units per second
 const MAX_BOUNCE_ANGLE: f32 = 1.0; // Maximum angle ball can bounce (radians)
 const LEFT_PADDLE_X: f32 = -7.65; // X position of left paddle
 const RIGHT_PADDLE_X: f32 = 7.65; // X position of right paddle
 
+// Define scoop paddle shape constants
+const PADDLE_WIDTH: f32 = 0.5; // Base width of the paddle
+const PADDLE_HEIGHT: f32 = 2.0; // Height of the paddle
+const PADDLE_DEPTH: f32 = 0.3; // How deep the curve goes
+const SEGMENTS: usize = 100; // Number of segments to create the curve
+
 /// Update rate for AI decisions to simulate human-like reaction time
 const AI_UPDATE_RATE: f32 = 0.3; // Updates 3.33 times per second
 
 /// Component that identifies which player a paddle belongs to
-#[derive(Component)]
+#[derive(Component, Clone)]
 pub enum Player {
     P1, // Human player (left paddle)
     P2, // AI player (right paddle)
@@ -40,6 +47,14 @@ struct AiPaddle {
     move_down: bool,     // Simulates S key press
 }
 
+/// Component to track paddle punch state
+#[derive(Component)]
+struct PunchState {
+    timer: Timer,
+    is_punching: bool,
+    rest_x: f32, // The x position to return to
+}
+
 impl Default for AiPaddle {
     fn default() -> Self {
         Self {
@@ -50,6 +65,46 @@ impl Default for AiPaddle {
     }
 }
 
+impl Default for PunchState {
+    fn default() -> Self {
+        Self {
+            timer: Timer::from_seconds(0.05, TimerMode::Once), // 50ms punch duration
+            is_punching: false,
+            rest_x: 0.0, // Will be set on spawn
+        }
+    }
+}
+
+/// Helper function to generate vertices for a segment of the scoop paddle shape
+/// Creates a paddle with a flat back and curved front
+///
+/// # Arguments
+/// * `index` - Index of the current segment being generated
+/// * `total_segments` - Total number of segments in the paddle
+///
+/// # Returns
+/// * Vector of Vec2 points defining a convex segment of the paddle
+fn generate_segment_vertices(index: usize, total_segments: usize) -> Vec<Vec2> {
+    let segment_height = PADDLE_HEIGHT / (total_segments as f32);
+    let y_start = -PADDLE_HEIGHT / 2.0 + (index as f32 * segment_height);
+    let y_end = y_start + segment_height;
+
+    // Calculate x position for the curved front using a parabolic curve
+    // The curve bulges outward from the flat back
+    let curve = |y: f32| -> f32 {
+        let normalized_y = (y + PADDLE_HEIGHT / 2.0) / PADDLE_HEIGHT;
+        // Start from left side and curve outward
+        PADDLE_DEPTH * (4.0 * normalized_y * (1.0 - normalized_y))
+    };
+
+    vec![
+        Vec2::new(0.0, y_start),            // Back left (flat)
+        Vec2::new(curve(y_start), y_start), // Front curved
+        Vec2::new(curve(y_end), y_end),     // Front curved
+        Vec2::new(0.0, y_end),              // Back right (flat)
+    ]
+}
+
 /// Calculates where the ball will intersect with a paddle's x-position
 ///
 /// # Arguments
@@ -85,7 +140,6 @@ fn ai_decision_making(
     mut ai_query: Query<(&Transform, &mut AiPaddle)>,
 ) {
     for (paddle_transform, mut ai) in ai_query.iter_mut() {
-        // Update AI decisions at fixed intervals
         if ai.update_timer.tick(time.delta()).just_finished() {
             if let Ok((ball_transform, ball_velocity)) = ball_query.get_single() {
                 if let Some(predicted_y) = predict_intersection(
@@ -93,8 +147,16 @@ fn ai_decision_making(
                     ball_velocity.linvel,
                     RIGHT_PADDLE_X,
                 ) {
+                    // Add offset to account for curved surface optimal hit point
+                    let optimal_y = predicted_y
+                        + (if ball_velocity.linvel.y > 0.0 {
+                            -PADDLE_HEIGHT / 4.0
+                        } else {
+                            PADDLE_HEIGHT / 4.0
+                        });
+
                     // Calculate difference between current and target position
-                    let diff = predicted_y - paddle_transform.translation.y;
+                    let diff = optimal_y - paddle_transform.translation.y;
 
                     // Reset movement flags
                     ai.move_up = false;
@@ -113,13 +175,6 @@ fn ai_decision_making(
 }
 
 /// Unified system that handles both human and AI paddle movement
-///
-/// For human players:
-/// - W/Up Arrow: Move up
-/// - S/Down Arrow: Move down
-///
-/// For AI:
-/// - Uses simulated input from AI decision making system
 fn paddle_movement(
     input: Res<ButtonInput<KeyCode>>,
     time: Res<Time>,
@@ -158,98 +213,150 @@ fn paddle_movement(
     }
 }
 
-/// Handles ball-paddle collision events and calculates bounce trajectories
-fn handle_paddle_collision(
+fn handle_paddle_collisions(
     mut collision_events: EventReader<CollisionEvent>,
-    mut ball_query: Query<(&Transform, &mut Velocity), With<Ball>>,
-    paddle_query: Query<(&Transform, &Player)>,
+    mut paddle_query: Query<(Entity, &mut Transform, &mut PunchState), With<Player>>,
+    ball_query: Query<Entity, With<Ball>>,
 ) {
+    let Ok(ball_entity) = ball_query.get_single() else {
+        return;
+    };
+
     for collision_event in collision_events.read() {
-        if let CollisionEvent::Started(e1, e2, _) = collision_event {
-            // Check both collision entity orders
-            if let Ok((ball_transform, mut ball_vel)) = ball_query.get_mut(*e1) {
-                if let Ok((paddle_transform, _)) = paddle_query.get(*e2) {
-                    handle_bounce(ball_transform, &mut ball_vel, paddle_transform);
-                }
-            } else if let Ok((ball_transform, mut ball_vel)) = ball_query.get_mut(*e2) {
-                if let Ok((paddle_transform, _)) = paddle_query.get(*e1) {
-                    handle_bounce(ball_transform, &mut ball_vel, paddle_transform);
+        // Only handle actual contact events
+        if let CollisionEvent::Started(e1, e2, flags) = collision_event {
+            // Skip if neither entity is the ball
+            if *e1 != ball_entity && *e2 != ball_entity {
+                continue;
+            }
+
+            for (paddle_entity, mut transform, mut punch_state) in paddle_query.iter_mut() {
+                if (paddle_entity == *e1 || paddle_entity == *e2) && !punch_state.is_punching {
+                    punch_state.is_punching = true;
+                    punch_state.timer.reset();
+
+                    let punch_offset = if transform.translation.x < 0.0 {
+                        0.15
+                    } else {
+                        -0.15
+                    };
+                    transform.translation.x += punch_offset;
+                    break;
                 }
             }
         }
     }
 }
 
-/// Calculates and applies ball bounce physics based on paddle hit position
-///
-/// The bounce angle is determined by where the ball hits the paddle:
-/// - Center: Straight bounce
-/// - Top: Upward angle
-/// - Bottom: Downward angle
-fn handle_bounce(
-    ball_transform: &Transform,
-    ball_vel: &mut Velocity,
-    paddle_transform: &Transform,
+/// System to reset paddle position after punch
+fn update_paddle_punch(
+    time: Res<Time>,
+    mut paddle_query: Query<(&mut Transform, &mut PunchState)>,
 ) {
-    // Calculate relative hit position (-1 to 1)
-    let relative_hit =
-        (ball_transform.translation.y - paddle_transform.translation.y) / (PADDLE_HEIGHT / 2.0);
+    for (mut transform, mut punch_state) in paddle_query.iter_mut() {
+        if punch_state.is_punching {
+            punch_state.timer.tick(time.delta());
+            if punch_state.timer.finished() {
+                transform.translation.x = punch_state.rest_x;
+                punch_state.is_punching = false;
+            }
+        }
+    }
+}
 
-    // Calculate bounce angle based on hit position
-    let bounce_angle = relative_hit * MAX_BOUNCE_ANGLE;
+/// Spawns both player paddles: human P1 on left and AI P2 on right
+fn spawn_players(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<ColorMaterial>>,
+) {
+    // Create compound collider for the scoop shape
+    let mut compound_collider = vec![];
+    let mut all_vertices = vec![];
+
+    // Generate segments for the scoop
+    for i in 0..SEGMENTS {
+        let vertices = generate_segment_vertices(i, SEGMENTS);
 
-    // Preserve the ball's speed magnitude
-    let current_speed = ball_vel.linvel.length();
-    let direction = if ball_vel.linvel.x > 0.0 { 1.0 } else { -1.0 };
+        // Add vertices to the complete mesh
+        all_vertices.extend(vertices.iter().cloned());
+
+        // Create collider for this segment
+        if let Some(collider) = Collider::convex_hull(&vertices) {
+            compound_collider.push((Vec2::ZERO, 0.0, collider));
+        }
+    }
 
-    // Apply new velocity vector while maintaining speed
-    ball_vel.linvel = Vec2::new(
-        -direction * current_speed * bounce_angle.cos(),
-        current_speed * bounce_angle.sin(),
+    // Create the mesh for visualization
+    let mut mesh = Mesh::new(
+        PrimitiveTopology::TriangleList,
+        RenderAssetUsages::RENDER_WORLD,
     );
-}
 
-/// Spawns both player paddles: human P1 on left and AI P2 on right
-fn spawn_players(mut commands: Commands) {
-    // Player 1 (left paddle, human controlled)
+    // Convert 2D vertices to 3D for mesh
+    let vertices_3d: Vec<[f32; 3]> = all_vertices.iter().map(|v| [v.x, v.y, 0.0]).collect();
+
+    // Generate indices for triangulation
+    let mut indices = Vec::new();
+    for i in 0..SEGMENTS {
+        let base = i as u32 * 4;
+        // First triangle
+        indices.extend_from_slice(&[base, base + 1, base + 2]);
+        // Second triangle
+        indices.extend_from_slice(&[base, base + 2, base + 3]);
+    }
+
+    mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, vertices_3d);
+    mesh.insert_indices(Indices::U32(indices));
+
+    let mesh_handle = meshes.add(mesh);
+    let material_handle = materials.add(ColorMaterial::from(Color::WHITE));
+
+    // Spawn Player 1 (left paddle)
     commands.spawn((
-        // Visual components
-        Sprite {
-            color: Color::WHITE,
-            custom_size: Some(Vec2::new(PADDLE_WIDTH, PADDLE_HEIGHT)),
-            ..default()
-        },
+        Mesh2d(mesh_handle.clone()),
+        MeshMaterial2d(material_handle.clone()),
         Transform::from_xyz(LEFT_PADDLE_X, 0.0, 0.0),
         GlobalTransform::default(),
         Visibility::default(),
-        // Physics components
+        ViewVisibility::default(),
+        InheritedVisibility::default(),
         RigidBody::KinematicPositionBased,
-        Collider::cuboid(PADDLE_WIDTH / 2.0, PADDLE_HEIGHT / 2.0),
+        Collider::compound(compound_collider.clone()),
         KinematicCharacterController::default(),
         ActiveEvents::COLLISION_EVENTS,
-        // Player identification
         Player::P1,
+        AdditionalMassProperties::Mass(0.1),
+        PunchState {
+            rest_x: LEFT_PADDLE_X,
+            ..default()
+        },
     ));
 
-    // Player 2 (right paddle, AI controlled)
+    // Spawn Player 2 (right paddle)
     commands.spawn((
-        // Visual components
-        Sprite {
-            color: Color::WHITE,
-            custom_size: Some(Vec2::new(PADDLE_WIDTH, PADDLE_HEIGHT)),
+        Mesh2d(mesh_handle),
+        MeshMaterial2d(material_handle),
+        Transform {
+            translation: Vec3::new(RIGHT_PADDLE_X, 0.0, 0.0),
+            rotation: Quat::from_rotation_z(std::f32::consts::PI), // Flip the paddle
             ..default()
         },
-        Transform::from_xyz(RIGHT_PADDLE_X, 0.0, 0.0),
         GlobalTransform::default(),
         Visibility::default(),
-        // Physics components
+        ViewVisibility::default(),
+        InheritedVisibility::default(),
         RigidBody::KinematicPositionBased,
-        Collider::cuboid(PADDLE_WIDTH / 2.0, PADDLE_HEIGHT / 2.0),
+        Collider::compound(compound_collider),
         KinematicCharacterController::default(),
         ActiveEvents::COLLISION_EVENTS,
-        // Player and AI components
         Player::P2,
         AiPaddle::default(),
+        AdditionalMassProperties::Mass(0.1),
+        PunchState {
+            rest_x: RIGHT_PADDLE_X,
+            ..default()
+        },
     ));
 }
 
@@ -258,14 +365,15 @@ pub struct PlayerPlugin;
 
 impl Plugin for PlayerPlugin {
     fn build(&self, app: &mut App) {
-        app
-            // Spawn players at startup
-            .add_systems(Startup, spawn_players)
-            // Add gameplay systems that run only in Playing state
-            .add_systems(
-                Update,
-                (ai_decision_making, paddle_movement, handle_paddle_collision)
-                    .run_if(in_state(GameState::Playing)),
-            );
+        app.add_systems(Startup, spawn_players).add_systems(
+            Update,
+            (
+                ai_decision_making,
+                paddle_movement,
+                handle_paddle_collisions,
+                update_paddle_punch,
+            )
+                .run_if(in_state(GameState::Playing)),
+        );
     }
 }

From e35843c9b96a072602b4620595d75084dc107bfd Mon Sep 17 00:00:00 2001
From: Alcibiades Athens <alcibiades.eth@protonmail.com>
Date: Sat, 28 Dec 2024 17:58:26 -0500
Subject: [PATCH 2/4] fix: make AI more beatable

---
 src/ball.rs   | 164 ++++++++++---
 src/board.rs  |   2 +-
 src/player.rs | 623 +++++++++++++++++++++++++++++++++++---------------
 3 files changed, 565 insertions(+), 224 deletions(-)

diff --git a/src/ball.rs b/src/ball.rs
index 45670e9..4f676c7 100644
--- a/src/ball.rs
+++ b/src/ball.rs
@@ -1,118 +1,214 @@
 //! Ball Physics Module
 //!
-//! This module handles all aspects of the game ball, including:
-//! - Physical properties and behavior
-//! - Spawn and cleanup logic
-//! - Velocity maintenance
-//! - Collision detection and response
+//! This module implements the core ball mechanics for the Pong game using the Bevy game engine
+//! and Rapier2D physics engine. It handles all aspects of the ball's behavior including:
 //!
-//! The ball uses Rapier2D physics for realistic movement and collisions.
+//! - Ball creation and initialization
+//! - Physics properties and collision response
+//! - Velocity management and speed constraints
+//! - Cleanup and state management
+//! - Collision detection and event handling
+//!
+//! The ball uses Rapier2D's rigid body physics system for realistic movement and collisions,
+//! with carefully tuned parameters to ensure engaging gameplay while maintaining physical plausibility.
 
 use crate::GameState;
 use bevy::app::{App, Plugin, Update};
 use bevy::prelude::*;
 use bevy_rapier2d::prelude::*;
 
-/// Physical properties of the ball that define its behavior
-const BALL_SIZE: f32 = 0.3; // Diameter in world units
-const MIN_VELOCITY: f32 = 7.0; // Minimum speed for the ball
-const MAX_VELOCITY: f32 = 32.0; // Maximum speed for the ball
-const SPEED_TOLERANCE: f32 = 3.0; // Allowed speed variation before correction
-const RESTITUTION: f32 = 0.9; // Bounciness (>1 means gaining energy)
-const BALL_MASS: f32 = 0.0027; // Mass affects collision response
+/// Physical properties and gameplay constants for the ball
+///
+/// These constants define both the visual and physical characteristics of the ball,
+/// carefully tuned to provide satisfying gameplay mechanics while maintaining
+/// physical plausibility.
+const BALL_SIZE: f32 = 0.3; // Ball diameter in world units (small enough for precise gameplay)
+const MIN_VELOCITY: f32 = 7.0; // Minimum ball speed (ensures game keeps moving)
+const MAX_VELOCITY: f32 = 20.0; // Maximum ball speed (prevents ball from becoming too fast)
+const RESTITUTION: f32 = 0.9; // Bounce elasticity (slightly inelastic for better control)
+const BALL_MASS: f32 = 0.0027; // Ball mass (tuned for realistic collision responses)
 
-/// Marker component to identify ball entities.
-/// Used for querying and managing ball-specific behavior.
+/// Marker component for identifying ball entities in the game world.
+///
+/// This component is used as a tag to:
+/// - Query for ball entities in systems
+/// - Filter collision events involving the ball
+/// - Manage ball-specific behavior and cleanup
+///
+/// # Example Usage
+/// ```rust
+/// // Query for ball entities
+/// fn ball_system(query: Query<&Transform, With<Ball>>) {
+///     for transform in query.iter() {
+///         // Process ball position
+///     }
+/// }
+/// ```
 #[derive(Component)]
 pub struct Ball;
 
-/// Creates a new ball entity with all necessary components for physics and rendering.
+/// Creates a new ball entity with complete physics and rendering setup.
+///
+/// This function creates a ball entity configured with:
+/// - Visual representation (white circle mesh)
+/// - Physics body and collider
+/// - Initial velocity based on serving direction
+/// - Collision properties and response settings
+/// - Physics modifiers for gameplay behavior
 ///
 /// # Arguments
-/// * `commands` - Command buffer for entity creation
-/// * `meshes` - Asset storage for the ball's mesh
-/// * `materials` - Asset storage for the ball's material
-/// * `served_by_p1` - Direction ball should initially move (true = right, false = left)
+/// * `commands` - Command buffer for entity creation and component insertion
+/// * `meshes` - Asset storage for managing the ball's visual mesh
+/// * `materials` - Asset storage for managing the ball's material/color
+/// * `served_by_p1` - Boolean flag indicating serve direction (true = right, false = left)
+///
+/// # Physics Configuration
+/// The ball is configured with:
+/// - Dynamic rigid body for physics-based movement
+/// - Zero friction to maintain momentum
+/// - Zero gravity for 2D pong mechanics
+/// - Continuous collision detection for reliability
+/// - Custom mass and restitution for desired bounce behavior
+///
+/// # Example
+/// ```rust
+/// create_ball(&mut commands, &mut meshes, &mut materials, true); // Serve to the right
+/// ```
 pub fn create_ball(
     commands: &mut Commands,
     meshes: &mut ResMut<Assets<Mesh>>,
     materials: &mut ResMut<Assets<ColorMaterial>>,
     served_by_p1: bool,
 ) {
+    // Calculate initial direction and velocity
     let direction = if served_by_p1 { 1 } else { -1 };
     let initial_velocity = Vec2::new(MIN_VELOCITY * direction as f32, 0.0);
 
     commands
         .spawn(Ball)
-        // Visual components
+        // Visual Components
+        // Creates a circular mesh for rendering with appropriate size
         .insert(Mesh2d(meshes.add(Circle::new(BALL_SIZE / 2.0))))
+        // Applies white color material to the ball
         .insert(MeshMaterial2d(
             materials.add(ColorMaterial::from(Color::WHITE)),
         ))
+        // Positions ball at center of screen initially
         .insert(Transform::from_xyz(0.0, 0.0, 0.0))
-        // Physics body setup
+        // Physics Body Configuration
+        // Sets up dynamic rigid body for physics simulation
         .insert(RigidBody::Dynamic)
+        // Creates circular collider matching visual size
         .insert(Collider::ball(BALL_SIZE / 2.0))
+        // Sets initial movement velocity
         .insert(Velocity::linear(initial_velocity))
-        // Collision properties
+        // Collision Properties
+        // Configures bounce behavior
         .insert(Restitution {
             coefficient: RESTITUTION,
             combine_rule: CoefficientCombineRule::Max,
         })
+        // Removes friction for consistent movement
         .insert(Friction {
             coefficient: 0.0,
             combine_rule: CoefficientCombineRule::Min,
         })
-        // Physics modifiers
+        // Physics Modifiers
+        // Disables velocity damping to maintain speed
         .insert(Damping {
             linear_damping: 0.0,
             angular_damping: 0.0,
         })
+        // Removes gravity effect
         .insert(GravityScale(0.0))
-        // Collision detection
+        // Collision Detection Setup
+        // Enables continuous collision detection for fast movement
         .insert(Ccd::enabled())
+        // Prevents physics sleep for consistent behavior
         .insert(Sleeping::disabled())
+        // Enables all collision types for comprehensive detection
         .insert(ActiveCollisionTypes::all())
+        // Enables collision event generation
         .insert(ActiveEvents::COLLISION_EVENTS)
+        // Sets mass for collision response calculations
         .insert(AdditionalMassProperties::Mass(BALL_MASS));
 }
 
-/// System to clean up the ball when exiting the Playing state.
-/// This prevents the ball from persisting in other game states.
+/// System that removes the ball entity when exiting the Playing state.
+///
+/// This cleanup system ensures that:
+/// - Ball is properly despawned when leaving gameplay
+/// - No ball entities persist in other game states
+/// - Memory is properly freed
+/// - Game state transitions are clean
+///
+/// # System Parameters
+/// * `commands` - Command buffer for entity manipulation
+/// * `ball_query` - Query to find ball entities for cleanup
 fn cleanup_ball(mut commands: Commands, ball_query: Query<Entity, With<Ball>>) {
     for entity in ball_query.iter() {
         commands.entity(entity).despawn();
     }
 }
 
+/// System that maintains the ball's velocity within gameplay constraints.
+///
+/// This system ensures that:
+/// - Ball never moves too slowly (maintains minimum speed)
+/// - Ball never moves too quickly (caps maximum speed)
+/// - Direction is preserved when adjusting speed
+/// - Ball maintains consistent gameplay feel
+///
+/// The system runs every frame during gameplay to:
+/// 1. Check current ball speed
+/// 2. Compare against min/max bounds
+/// 3. Adjust if necessary while preserving direction
+/// 4. Handle edge cases (like zero velocity)
+///
+/// # Physics Notes
+/// - Uses vector normalization to preserve direction
+/// - Handles potential division by zero
+/// - Maintains speed constraints for consistent gameplay
 fn maintain_ball_velocity(mut query: Query<&mut Velocity, With<Ball>>) {
     for mut velocity in query.iter_mut() {
         let current_velocity = velocity.linvel;
         let current_speed = current_velocity.length();
 
-        // Check absolute magnitude and adjust if needed
-        if current_speed != 0.0 {  // Prevent division by zero
+        // Only adjust non-zero velocities to prevent normalization issues
+        if current_speed != 0.0 {
+            // Determine new speed based on constraints
             let new_speed = if current_speed.abs() < MIN_VELOCITY {
-                MIN_VELOCITY
+                MIN_VELOCITY // Enforce minimum speed
             } else if current_speed.abs() > MAX_VELOCITY {
-                MAX_VELOCITY
+                MAX_VELOCITY // Cap maximum speed
             } else {
-                current_speed
+                current_speed // Maintain current speed if within bounds
             };
 
+            // Apply new speed while preserving direction
             velocity.linvel = current_velocity.normalize() * new_speed;
         }
     }
 }
 
-/// Plugin that manages all ball-related systems.
+/// Plugin that manages all ball-related systems and behavior.
+///
+/// This plugin integrates the ball systems into the game by:
+/// - Adding cleanup system for state transitions
+/// - Adding velocity maintenance system for gameplay
+/// - Organizing ball-related functionality
+///
+/// The plugin ensures proper initialization and cleanup of ball
+/// mechanics while maintaining clean integration with the game's
+/// state system.
 pub struct BallPlugin;
 
 impl Plugin for BallPlugin {
     fn build(&self, app: &mut App) {
         app
-            // Clean up ball when leaving Playing state
+            // Add cleanup system for state transitions
             .add_systems(OnExit(GameState::Playing), cleanup_ball)
+            // Add velocity maintenance system during gameplay updates
             .add_systems(Update, maintain_ball_velocity);
     }
 }
diff --git a/src/board.rs b/src/board.rs
index d80042c..f829fd1 100644
--- a/src/board.rs
+++ b/src/board.rs
@@ -38,7 +38,7 @@ const DASH_GAP: f32 = 0.4; // Gap between dashes
 
 /// Physics settings for the walls.
 /// Walls are bouncy to create more interesting gameplay.
-const WALL_RESTITUTION: f32 = 1.5; // Wall bounciness (>1 means adding energy)
+const WALL_RESTITUTION: f32 = 2.0; // Wall bounciness (>1 means adding energy)
 
 /// Creates the black background color resource.
 /// This sets the clear color for the game's rendering.
diff --git a/src/player.rs b/src/player.rs
index b504c13..856cc7c 100644
--- a/src/player.rs
+++ b/src/player.rs
@@ -1,12 +1,7 @@
 //! Player Module
 //!
-//! This module handles both human and AI-controlled paddles, including:
-//! - Paddle physics and movement
-//! - Player input handling
-//! - AI behavior and decision making
-//! - Ball collision and bounce mechanics
-//!
-//! The module supports both human input (Player 1) and AI control (Player 2).
+//! This module implements the player paddle mechanics for the Pong game, including both
+//! human-controlled and AI-controlled paddles.
 
 use crate::ball::Ball;
 use crate::GameState;
@@ -16,111 +11,212 @@ use bevy::render::mesh::Indices;
 use bevy::render::render_asset::RenderAssetUsages;
 use bevy::render::render_resource::PrimitiveTopology;
 use bevy_rapier2d::prelude::*;
+use std::time::Duration;
+
+/// Configuration constants for paddle physics and gameplay
+#[derive(Debug, Resource)]
+pub struct PaddleConfig {
+    /// Movement speed in world units per second
+    pub speed: f32,
+    /// Maximum angle the ball can bounce (in radians)
+    pub max_bounce_angle: f32,
+    /// X-coordinate for left paddle position
+    pub left_x: f32,
+    /// X-coordinate for right paddle position
+    pub right_x: f32,
+    /// Base width of the paddle
+    pub width: f32,
+    /// Total height of the paddle
+    pub height: f32,
+    /// Depth of the paddle's curve
+    pub curve_depth: f32,
+    /// Number of segments used to create the curved shape
+    pub segments: usize,
+    /// Mass of the paddle for physics calculations
+    pub mass: f32,
+    /// Duration of punch animation in seconds
+    pub punch_duration: f32,
+    /// Distance paddle moves during punch
+    pub punch_distance: f32,
+}
 
-/// Constants defining the player paddles' physical and gameplay properties
-const PADDLE_SPEED: f32 = 20.0; // Movement speed in units per second
-const MAX_BOUNCE_ANGLE: f32 = 1.0; // Maximum angle ball can bounce (radians)
-const LEFT_PADDLE_X: f32 = -7.65; // X position of left paddle
-const RIGHT_PADDLE_X: f32 = 7.65; // X position of right paddle
+impl Default for PaddleConfig {
+    fn default() -> Self {
+        Self {
+            speed: 20.0,
+            max_bounce_angle: 1.0,
+            left_x: -7.65,
+            right_x: 7.65,
+            width: 0.5,
+            height: 2.0,
+            curve_depth: 0.3,
+            segments: 100,
+            mass: 0.1,
+            punch_duration: 0.05,
+            punch_distance: 0.15,
+        }
+    }
+}
 
-// Define scoop paddle shape constants
-const PADDLE_WIDTH: f32 = 0.5; // Base width of the paddle
-const PADDLE_HEIGHT: f32 = 2.0; // Height of the paddle
-const PADDLE_DEPTH: f32 = 0.3; // How deep the curve goes
-const SEGMENTS: usize = 100; // Number of segments to create the curve
+/// Configuration for AI difficulty tuning
+#[derive(Debug, Resource)]
+pub struct AiConfig {
+    /// Time between AI decisions (seconds)
+    pub update_rate: f32,
+    /// Deadzone for movement to prevent jitter
+    pub movement_deadzone: f32,
+    /// Offset from center for optimal hit point
+    pub hit_point_offset: f32,
+    /// Chance to make a prediction error (0.0 - 1.0)
+    pub error_chance: f32,
+    /// Maximum prediction error amount in world units
+    pub max_error: f32,
+    /// Chance to completely miss the ball (0.0 - 1.0)
+    pub miss_chance: f32,
+}
 
-/// Update rate for AI decisions to simulate human-like reaction time
-const AI_UPDATE_RATE: f32 = 0.3; // Updates 3.33 times per second
+/// Configuration for a challenging AI opponent
+///
+/// While challenging, this AI is intentionally not perfect:
+/// - It can be baited into wrong movements
+/// - It occasionally misreads steep angles
+/// - It has a slight delay before position adjustments
+/// - It sometimes misses extremely fast shots
+impl Default for AiConfig {
+    fn default() -> Self {
+        Self {
+            // Time between position adjustments
+            // Fast enough to handle most shots, but with enough delay
+            // that quick direction changes can catch it out of position
+            update_rate: 0.3,
+
+            // Minimum distance before adjusting position
+            // Small enough to maintain precise positioning for returns,
+            // but creates brief windows where slight misalignments can
+            // be exploited
+            movement_deadzone: 0.08,
+
+            // Preferred hitting position relative to paddle center
+            // Aims slightly off-center to maintain better control,
+            // but this creates small gaps near the paddle edges that
+            // can be targeted
+            hit_point_offset: 0.4,
+
+            // Chance to misread the ball's trajectory
+            // Most noticeable when handling steep angles or after
+            // multiple bounces, representing the limits of its
+            // prediction capabilities
+            error_chance: 0.12,
+
+            // Maximum prediction error magnitude
+            // When errors occur, they're significant enough to create
+            // scoring opportunities if the player is positioned to
+            // capitalize on them
+            max_error: 1.0,
+
+            // Chance to completely miss the ball
+            // Primarily occurs during very fast exchanges or when
+            // the ball approaches at extreme angles, simulating
+            // the challenge of handling powerful shots
+            miss_chance: 0.05,
+        }
+    }
+}
 
 /// Component that identifies which player a paddle belongs to
-#[derive(Component, Clone)]
+#[derive(Component, Clone, Debug)]
 pub enum Player {
     P1, // Human player (left paddle)
     P2, // AI player (right paddle)
 }
 
-/// Component for AI-controlled paddles that simulates human-like input behavior
-#[derive(Component)]
-struct AiPaddle {
-    update_timer: Timer, // Controls AI decision rate
-    move_up: bool,       // Simulates W key press
-    move_down: bool,     // Simulates S key press
+/// Represents the current movement state of the AI paddle
+#[derive(Debug)]
+enum MovementState {
+    Idle,
+    MovingUp(f32),   // Contains target Y position
+    MovingDown(f32), // Contains target Y position
 }
 
-/// Component to track paddle punch state
-#[derive(Component)]
-struct PunchState {
-    timer: Timer,
-    is_punching: bool,
-    rest_x: f32, // The x position to return to
+/// Component for AI-controlled paddles that simulates human-like input behavior
+#[derive(Component, Debug)]
+struct AiPaddle {
+    /// Timer to control AI decision rate
+    update_timer: Timer,
+    /// Timer for upward movement duration
+    move_up_timer: Timer,
+    /// Timer for downward movement duration
+    move_down_timer: Timer,
+    /// Current movement state
+    movement_state: MovementState,
+    /// Last predicted intersection point
+    last_prediction: Option<f32>,
 }
 
 impl Default for AiPaddle {
     fn default() -> Self {
         Self {
-            update_timer: Timer::from_seconds(AI_UPDATE_RATE, TimerMode::Repeating),
-            move_up: false,
-            move_down: false,
+            update_timer: Timer::from_seconds(
+                AiConfig::default().update_rate,
+                TimerMode::Repeating,
+            ),
+            move_up_timer: Timer::from_seconds(0.0, TimerMode::Once),
+            move_down_timer: Timer::from_seconds(0.0, TimerMode::Once),
+            movement_state: MovementState::Idle,
+            last_prediction: None,
         }
     }
 }
 
+/// Component to track paddle punch state and animation
+#[derive(Component, Debug)]
+struct PunchState {
+    /// Timer for punch animation duration
+    timer: Timer,
+    /// Whether paddle is currently in punch state
+    is_punching: bool,
+    /// Original x position to return to after punch
+    rest_x: f32,
+}
+
 impl Default for PunchState {
     fn default() -> Self {
         Self {
-            timer: Timer::from_seconds(0.05, TimerMode::Once), // 50ms punch duration
+            timer: Timer::from_seconds(PaddleConfig::default().punch_duration, TimerMode::Once),
             is_punching: false,
-            rest_x: 0.0, // Will be set on spawn
+            rest_x: 0.0,
         }
     }
 }
 
-/// Helper function to generate vertices for a segment of the scoop paddle shape
-/// Creates a paddle with a flat back and curved front
-///
-/// # Arguments
-/// * `index` - Index of the current segment being generated
-/// * `total_segments` - Total number of segments in the paddle
-///
-/// # Returns
-/// * Vector of Vec2 points defining a convex segment of the paddle
-fn generate_segment_vertices(index: usize, total_segments: usize) -> Vec<Vec2> {
-    let segment_height = PADDLE_HEIGHT / (total_segments as f32);
-    let y_start = -PADDLE_HEIGHT / 2.0 + (index as f32 * segment_height);
-    let y_end = y_start + segment_height;
-
-    // Calculate x position for the curved front using a parabolic curve
-    // The curve bulges outward from the flat back
-    let curve = |y: f32| -> f32 {
-        let normalized_y = (y + PADDLE_HEIGHT / 2.0) / PADDLE_HEIGHT;
-        // Start from left side and curve outward
-        PADDLE_DEPTH * (4.0 * normalized_y * (1.0 - normalized_y))
-    };
-
-    vec![
-        Vec2::new(0.0, y_start),            // Back left (flat)
-        Vec2::new(curve(y_start), y_start), // Front curved
-        Vec2::new(curve(y_end), y_end),     // Front curved
-        Vec2::new(0.0, y_end),              // Back right (flat)
-    ]
+/// Calculate the duration needed to move to a target position
+fn calculate_movement_duration(
+    current_pos: f32,
+    target_pos: f32,
+    speed: f32,
+    min_duration: f32,
+    max_duration: f32,
+) -> f32 {
+    let distance = (target_pos - current_pos).abs();
+    let base_duration = distance / speed;
+
+    // Add small random variation for more human-like behavior
+    let variation = rand::random::<f32>() * 0.1; // Up to 10% variation
+    let duration = base_duration * (1.0 + variation);
+
+    // Clamp duration between minimum and maximum values
+    duration.clamp(min_duration, max_duration)
 }
 
-/// Calculates where the ball will intersect with a paddle's x-position
-///
-/// # Arguments
-/// * `ball_pos` - Current ball position
-/// * `ball_vel` - Current ball velocity
-/// * `paddle_x` - X-coordinate of paddle to check
-///
-/// # Returns
-/// * `Some(y)` - Predicted Y intersection if ball is moving toward paddle
-/// * `None` - If ball is moving away from paddle
+/// Predicts where the ball will intersect with a paddle's x-position
 fn predict_intersection(ball_pos: Vec2, ball_vel: Vec2, paddle_x: f32) -> Option<f32> {
-    // Only predict if ball is moving toward the paddle
-    if (paddle_x > ball_pos.x && ball_vel.x > 0.0) || (paddle_x < ball_pos.x && ball_vel.x < 0.0) {
-        // Calculate time until x-intersection
+    // Check if ball is moving toward paddle
+    let moving_toward =
+        (paddle_x > ball_pos.x && ball_vel.x > 0.0) || (paddle_x < ball_pos.x && ball_vel.x < 0.0);
+
+    if moving_toward {
+        // Calculate intersection time and position
         let time = (paddle_x - ball_pos.x) / ball_vel.x;
-        // Calculate y-position at intersection
         let y = ball_pos.y + (ball_vel.y * time);
         Some(y)
     } else {
@@ -129,45 +225,113 @@ fn predict_intersection(ball_pos: Vec2, ball_vel: Vec2, paddle_x: f32) -> Option
 }
 
 /// System that controls AI paddle movement by simulating human-like input
-///
-/// The AI:
-/// 1. Predicts ball intersection point
-/// 2. Updates movement decision at human-like intervals
-/// 3. Moves paddle toward predicted position
 fn ai_decision_making(
     time: Res<Time>,
+    paddle_config: Res<PaddleConfig>,
+    ai_config: Res<AiConfig>,
     ball_query: Query<(&Transform, &Velocity), With<Ball>>,
     mut ai_query: Query<(&Transform, &mut AiPaddle)>,
 ) {
     for (paddle_transform, mut ai) in ai_query.iter_mut() {
+        // Update movement timers
+        ai.move_up_timer.tick(time.delta());
+        ai.move_down_timer.tick(time.delta());
+
+        // Reset movement state if timers are finished
+        match ai.movement_state {
+            MovementState::MovingUp(_) if ai.move_up_timer.finished() => {
+                ai.movement_state = MovementState::Idle;
+            }
+            MovementState::MovingDown(_) if ai.move_down_timer.finished() => {
+                ai.movement_state = MovementState::Idle;
+            }
+            _ => {}
+        }
+
         if ai.update_timer.tick(time.delta()).just_finished() {
             if let Ok((ball_transform, ball_velocity)) = ball_query.get_single() {
                 if let Some(predicted_y) = predict_intersection(
                     ball_transform.translation.truncate(),
                     ball_velocity.linvel,
-                    RIGHT_PADDLE_X,
+                    paddle_config.right_x,
                 ) {
-                    // Add offset to account for curved surface optimal hit point
-                    let optimal_y = predicted_y
-                        + (if ball_velocity.linvel.y > 0.0 {
-                            -PADDLE_HEIGHT / 4.0
+                    // Decide if we're going to try to hit the ball
+                    if rand::random::<f32>() < ai_config.miss_chance {
+                        // Intentionally miss by moving in wrong direction
+                        let miss_y = if predicted_y > 0.0 { -2.0 } else { 2.0 };
+                        let current_y = paddle_transform.translation.y;
+                        let diff = miss_y - current_y;
+
+                        if diff.abs() > ai_config.movement_deadzone {
+                            let duration = calculate_movement_duration(
+                                current_y,
+                                miss_y,
+                                paddle_config.speed,
+                                0.1,
+                                0.5,
+                            );
+
+                            if diff > 0.0 {
+                                ai.movement_state = MovementState::MovingUp(miss_y);
+                                ai.move_up_timer
+                                    .set_duration(Duration::from_secs_f32(duration));
+                                ai.move_up_timer.reset();
+                            } else {
+                                ai.movement_state = MovementState::MovingDown(miss_y);
+                                ai.move_down_timer
+                                    .set_duration(Duration::from_secs_f32(duration));
+                                ai.move_down_timer.reset();
+                            }
+                        }
+                    } else {
+                        // Add potential prediction error
+                        let error = if rand::random::<f32>() < ai_config.error_chance {
+                            let error_amount = rand::random::<f32>() * ai_config.max_error;
+                            if rand::random::<bool>() {
+                                error_amount
+                            } else {
+                                -error_amount
+                            }
                         } else {
-                            PADDLE_HEIGHT / 4.0
-                        });
-
-                    // Calculate difference between current and target position
-                    let diff = optimal_y - paddle_transform.translation.y;
-
-                    // Reset movement flags
-                    ai.move_up = false;
-                    ai.move_down = false;
-
-                    // Move toward predicted position with small deadzone
-                    if diff > 0.1 {
-                        ai.move_up = true;
-                    } else if diff < -0.1 {
-                        ai.move_down = true;
+                            0.0
+                        };
+
+                        // Calculate hit point with error and offset
+                        let optimal_y = predicted_y
+                            + error
+                            + if ball_velocity.linvel.y > 0.0 {
+                                -ai_config.hit_point_offset
+                            } else {
+                                ai_config.hit_point_offset
+                            };
+
+                        let current_y = paddle_transform.translation.y;
+                        let diff = optimal_y - current_y;
+
+                        // Only change movement if difference is significant
+                        if diff.abs() > ai_config.movement_deadzone {
+                            let duration = calculate_movement_duration(
+                                current_y,
+                                optimal_y,
+                                paddle_config.speed,
+                                0.1, // Minimum duration
+                                0.5, // Maximum duration
+                            );
+
+                            if diff > 0.0 {
+                                ai.movement_state = MovementState::MovingUp(optimal_y);
+                                ai.move_up_timer
+                                    .set_duration(Duration::from_secs_f32(duration));
+                                ai.move_up_timer.reset();
+                            } else {
+                                ai.movement_state = MovementState::MovingDown(optimal_y);
+                                ai.move_down_timer
+                                    .set_duration(Duration::from_secs_f32(duration));
+                                ai.move_down_timer.reset();
+                            }
+                        }
                     }
+                    ai.last_prediction = Some(predicted_y);
                 }
             }
         }
@@ -176,34 +340,46 @@ fn ai_decision_making(
 
 /// Unified system that handles both human and AI paddle movement
 fn paddle_movement(
+    config: Res<PaddleConfig>,
     input: Res<ButtonInput<KeyCode>>,
     time: Res<Time>,
     mut query: Query<(
         &Player,
         &mut KinematicCharacterController,
         Option<&AiPaddle>,
+        &Transform,
     )>,
 ) {
-    for (player, mut controller, ai) in query.iter_mut() {
+    for (player, mut controller, ai, paddle_transform) in query.iter_mut() {
         let mut translation = Vec2::ZERO;
+        let move_amount = config.speed * time.delta_secs();
 
         match (player, ai) {
             // Human player input handling
             (Player::P1, None) => {
                 if input.pressed(KeyCode::KeyW) || input.pressed(KeyCode::ArrowUp) {
-                    translation.y += PADDLE_SPEED * time.delta_secs();
+                    translation.y += move_amount;
                 }
                 if input.pressed(KeyCode::KeyS) || input.pressed(KeyCode::ArrowDown) {
-                    translation.y -= PADDLE_SPEED * time.delta_secs();
+                    translation.y -= move_amount;
                 }
             }
             // AI player movement
             (Player::P2, Some(ai)) => {
-                if ai.move_up {
-                    translation.y += PADDLE_SPEED * time.delta_secs();
-                }
-                if ai.move_down {
-                    translation.y -= PADDLE_SPEED * time.delta_secs();
+                match ai.movement_state {
+                    MovementState::MovingUp(target_y) if !ai.move_up_timer.finished() => {
+                        // Stop moving if we've reached or passed the target
+                        if paddle_transform.translation.y < target_y {
+                            translation.y += move_amount;
+                        }
+                    }
+                    MovementState::MovingDown(target_y) if !ai.move_down_timer.finished() => {
+                        // Stop moving if we've reached or passed the target
+                        if paddle_transform.translation.y > target_y {
+                            translation.y -= move_amount;
+                        }
+                    }
+                    _ => {}
                 }
             }
             _ => {}
@@ -213,7 +389,9 @@ fn paddle_movement(
     }
 }
 
+/// System that handles paddle-ball collisions and triggers punch animations
 fn handle_paddle_collisions(
+    config: Res<PaddleConfig>,
     mut collision_events: EventReader<CollisionEvent>,
     mut paddle_query: Query<(Entity, &mut Transform, &mut PunchState), With<Player>>,
     ball_query: Query<Entity, With<Ball>>,
@@ -223,8 +401,7 @@ fn handle_paddle_collisions(
     };
 
     for collision_event in collision_events.read() {
-        // Only handle actual contact events
-        if let CollisionEvent::Started(e1, e2, flags) = collision_event {
+        if let CollisionEvent::Started(e1, e2, _) = collision_event {
             // Skip if neither entity is the ball
             if *e1 != ball_entity && *e2 != ball_entity {
                 continue;
@@ -235,12 +412,12 @@ fn handle_paddle_collisions(
                     punch_state.is_punching = true;
                     punch_state.timer.reset();
 
-                    let punch_offset = if transform.translation.x < 0.0 {
-                        0.15
+                    let punch_direction = if transform.translation.x < 0.0 {
+                        1.0
                     } else {
-                        -0.15
+                        -1.0
                     };
-                    transform.translation.x += punch_offset;
+                    transform.translation.x += config.punch_distance * punch_direction;
                     break;
                 }
             }
@@ -248,7 +425,7 @@ fn handle_paddle_collisions(
     }
 }
 
-/// System to reset paddle position after punch
+/// System to reset paddle position after punch animation
 fn update_paddle_punch(
     time: Res<Time>,
     mut paddle_query: Query<(&mut Transform, &mut PunchState)>,
@@ -264,24 +441,19 @@ fn update_paddle_punch(
     }
 }
 
-/// Spawns both player paddles: human P1 on left and AI P2 on right
-fn spawn_players(
-    mut commands: Commands,
-    mut meshes: ResMut<Assets<Mesh>>,
-    mut materials: ResMut<Assets<ColorMaterial>>,
-) {
-    // Create compound collider for the scoop shape
+/// Creates mesh and compound collider for paddle
+fn create_paddle_mesh(
+    meshes: &mut ResMut<Assets<Mesh>>,
+    config: &PaddleConfig,
+) -> (Handle<Mesh>, Vec<(Vec2, f32, Collider)>) {
     let mut compound_collider = vec![];
     let mut all_vertices = vec![];
 
     // Generate segments for the scoop
-    for i in 0..SEGMENTS {
-        let vertices = generate_segment_vertices(i, SEGMENTS);
-
-        // Add vertices to the complete mesh
+    for i in 0..config.segments {
+        let vertices = generate_segment_vertices(i, config.segments, config);
         all_vertices.extend(vertices.iter().cloned());
 
-        // Create collider for this segment
         if let Some(collider) = Collider::convex_hull(&vertices) {
             compound_collider.push((Vec2::ZERO, 0.0, collider));
         }
@@ -298,7 +470,7 @@ fn spawn_players(
 
     // Generate indices for triangulation
     let mut indices = Vec::new();
-    for i in 0..SEGMENTS {
+    for i in 0..config.segments {
         let base = i as u32 * 4;
         // First triangle
         indices.extend_from_slice(&[base, base + 1, base + 2]);
@@ -309,55 +481,120 @@ fn spawn_players(
     mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, vertices_3d);
     mesh.insert_indices(Indices::U32(indices));
 
-    let mesh_handle = meshes.add(mesh);
+    (meshes.add(mesh), compound_collider)
+}
+
+/// Helper function to generate vertices for a segment of the scoop paddle shape
+fn generate_segment_vertices(
+    index: usize,
+    total_segments: usize,
+    config: &PaddleConfig,
+) -> Vec<Vec2> {
+    let segment_height = config.height / (total_segments as f32);
+    let y_start = -config.height / 2.0 + (index as f32 * segment_height);
+    let y_end = y_start + segment_height;
+
+    // Parabolic curve function for paddle front
+    let curve = |y: f32| -> f32 {
+        let normalized_y = (y + config.height / 2.0) / config.height;
+        config.curve_depth * (4.0 * normalized_y * (1.0 - normalized_y))
+    };
+
+    vec![
+        Vec2::new(0.0, y_start),            // Back left (flat)
+        Vec2::new(curve(y_start), y_start), // Front curved
+        Vec2::new(curve(y_end), y_end),     // Front curved
+        Vec2::new(0.0, y_end),              // Back right (flat)
+    ]
+}
+
+/// Creates a paddle entity with all necessary components
+fn create_paddle(
+    commands: &mut Commands,
+    config: &PaddleConfig,
+    mesh_handle: Handle<Mesh>,
+    material_handle: Handle<ColorMaterial>,
+    is_player_one: bool,
+    compound_collider: Vec<(Vec2, f32, Collider)>,
+) -> Entity {
+    let x_pos = if is_player_one {
+        config.left_x
+    } else {
+        config.right_x
+    };
+    let rotation = if is_player_one {
+        Quat::IDENTITY
+    } else {
+        Quat::from_rotation_z(std::f32::consts::PI)
+    };
+
+    let mut entity = commands.spawn_empty();
+
+    // Add visual components
+    entity
+        .insert(Mesh2d(mesh_handle))
+        .insert(MeshMaterial2d(material_handle))
+        .insert(Transform::from_xyz(x_pos, 0.0, 0.0).with_rotation(rotation))
+        .insert(GlobalTransform::default())
+        .insert(Visibility::default())
+        .insert(ViewVisibility::default())
+        .insert(InheritedVisibility::default());
+
+    // Add physics components
+    entity
+        .insert(RigidBody::KinematicPositionBased)
+        .insert(KinematicCharacterController::default())
+        .insert(Collider::compound(compound_collider))
+        .insert(ActiveEvents::COLLISION_EVENTS)
+        .insert(AdditionalMassProperties::Mass(config.mass));
+
+    // Add player-specific components
+    if is_player_one {
+        entity.insert(Player::P1);
+    } else {
+        entity.insert(Player::P2).insert(AiPaddle::default());
+    }
+
+    // Add punch state
+    entity.insert(PunchState {
+        rest_x: x_pos,
+        ..default()
+    });
+
+    entity.id()
+}
+
+/// Spawns both player paddles: human P1 on left and AI P2 on right
+fn spawn_players(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<ColorMaterial>>,
+) {
+    let config = PaddleConfig::default();
+
+    // Create paddle mesh and collider
+    let (mesh_handle, compound_collider) = create_paddle_mesh(&mut meshes, &config);
     let material_handle = materials.add(ColorMaterial::from(Color::WHITE));
 
-    // Spawn Player 1 (left paddle)
-    commands.spawn((
-        Mesh2d(mesh_handle.clone()),
-        MeshMaterial2d(material_handle.clone()),
-        Transform::from_xyz(LEFT_PADDLE_X, 0.0, 0.0),
-        GlobalTransform::default(),
-        Visibility::default(),
-        ViewVisibility::default(),
-        InheritedVisibility::default(),
-        RigidBody::KinematicPositionBased,
-        Collider::compound(compound_collider.clone()),
-        KinematicCharacterController::default(),
-        ActiveEvents::COLLISION_EVENTS,
-        Player::P1,
-        AdditionalMassProperties::Mass(0.1),
-        PunchState {
-            rest_x: LEFT_PADDLE_X,
-            ..default()
-        },
-    ));
-
-    // Spawn Player 2 (right paddle)
-    commands.spawn((
-        Mesh2d(mesh_handle),
-        MeshMaterial2d(material_handle),
-        Transform {
-            translation: Vec3::new(RIGHT_PADDLE_X, 0.0, 0.0),
-            rotation: Quat::from_rotation_z(std::f32::consts::PI), // Flip the paddle
-            ..default()
-        },
-        GlobalTransform::default(),
-        Visibility::default(),
-        ViewVisibility::default(),
-        InheritedVisibility::default(),
-        RigidBody::KinematicPositionBased,
-        Collider::compound(compound_collider),
-        KinematicCharacterController::default(),
-        ActiveEvents::COLLISION_EVENTS,
-        Player::P2,
-        AiPaddle::default(),
-        AdditionalMassProperties::Mass(0.1),
-        PunchState {
-            rest_x: RIGHT_PADDLE_X,
-            ..default()
-        },
-    ));
+    // Spawn player 1 (left paddle)
+    create_paddle(
+        &mut commands,
+        &config,
+        mesh_handle.clone(),
+        material_handle.clone(),
+        true,
+        compound_collider.clone(),
+    );
+
+    // Spawn player 2 (right paddle)
+    create_paddle(
+        &mut commands,
+        &config,
+        mesh_handle,
+        material_handle,
+        false,
+        compound_collider,
+    );
 }
 
 /// Plugin that manages all player-related systems
@@ -365,15 +602,23 @@ pub struct PlayerPlugin;
 
 impl Plugin for PlayerPlugin {
     fn build(&self, app: &mut App) {
-        app.add_systems(Startup, spawn_players).add_systems(
-            Update,
-            (
-                ai_decision_making,
-                paddle_movement,
-                handle_paddle_collisions,
-                update_paddle_punch,
-            )
-                .run_if(in_state(GameState::Playing)),
-        );
+        app
+            // Initialize configuration resources
+            .init_resource::<PaddleConfig>()
+            .init_resource::<AiConfig>()
+            // Add startup systems
+            .add_systems(Startup, spawn_players)
+            // Add gameplay systems that run during the Playing state
+            .add_systems(
+                Update,
+                (
+                    ai_decision_making,
+                    paddle_movement,
+                    handle_paddle_collisions,
+                    update_paddle_punch,
+                )
+                    .chain()
+                    .run_if(in_state(GameState::Playing)),
+            );
     }
 }

From fc611711c92bc4d78c0f331da55362606fccaaa3 Mon Sep 17 00:00:00 2001
From: Alcibiades Athens <alcibiades.eth@protonmail.com>
Date: Sat, 28 Dec 2024 18:10:21 -0500
Subject: [PATCH 3/4] fix: score resume from pause

---
 src/score.rs | 345 ++++++++++++++++++++++++++-------------------------
 1 file changed, 176 insertions(+), 169 deletions(-)

diff --git a/src/score.rs b/src/score.rs
index 26104ce..02d6806 100644
--- a/src/score.rs
+++ b/src/score.rs
@@ -1,14 +1,12 @@
 //! Score Management Module
 //!
-//! This module handles all scoring-related functionality, including:
-//! - Score tracking and display
-//! - Serve mechanics and timing
-//! - Ball spawning on points
-//! - Score UI rendering
-//! - Victory conditions and game reset
-//!
-//! The scoring system follows traditional ping-pong rules with
-//! serve switching and deuce handling.
+//! Handles scoring mechanics and display for a table tennis-style game. Features include:
+//! - Score tracking and persistence across game states
+//! - Traditional table tennis scoring rules (first to 11, win by 2)
+//! - Alternating serve patterns with deuce handling
+//! - Score display UI with automatic updates
+//! - Victory condition checking
+//! - Ball spawning and serve mechanics
 
 use crate::ball::{create_ball, Ball};
 use crate::board::Wall;
@@ -17,43 +15,50 @@ use bevy::prelude::*;
 use bevy_rapier2d::prelude::*;
 use rand::Rng;
 
-/// Resource that tracks the game's scoring state.
-/// This persists across state changes to maintain score history.
+// ----- Resources -----
+
+/// Resource that tracks game scoring state and serve mechanics.
+/// This persists across state changes to maintain game progress.
 #[derive(Resource)]
 pub struct Score {
-    pub p1: u32,            // Player 1's score
-    pub p2: u32,            // Player 2's score
-    pub server_is_p1: bool, // Whether P1 is currently serving
-    serve_count: u32,       // Number of serves since last switch
-    serve_timer: Timer,     // Delay between point and next serve
-    pub should_serve: bool, // Whether we're waiting to serve
+    /// Player 1's current score
+    pub p1: u32,
+    /// Player 2's current score
+    pub p2: u32,
+    /// Indicates whether Player 1 is currently serving
+    pub server_is_p1: bool,
+    /// Tracks serves since last server switch
+    serve_count: u32,
+    /// Timer for delay between points
+    serve_timer: Timer,
+    /// Flag indicating a serve is pending
+    pub should_serve: bool,
 }
 
 impl Score {
-    /// Creates a new score state with initial values
+    /// Creates a new scoring state with initial values.
+    /// Server is randomly chosen at start.
     fn new() -> Self {
         Self {
             p1: 0,
             p2: 0,
-            // Randomly choose initial server
             server_is_p1: rand::thread_rng().gen_bool(0.5),
             serve_count: 0,
-            // 0.75 second delay before serving
             serve_timer: Timer::from_seconds(0.75, TimerMode::Once),
             should_serve: false,
         }
     }
 
-    /// Adds a point and handles serve switching logic
+    /// Awards a point and handles serve rotation logic.
     ///
-    /// # Arguments
-    /// * `p1_scored` - Whether player 1 scored the point
+    /// Implements official table tennis serve rules:
+    /// - Server changes every 2 points in normal play
+    /// - Server changes every point during deuce (10-10 or higher)
     ///
-    /// # Serve Switching Rules
-    /// - Normal play: Switch server every 2 points
-    /// - Deuce (10-10 or higher): Switch every point
+    /// # Arguments
+    /// * `p1_scored` - true if point goes to Player 1, false for Player 2
     fn add_point(&mut self, p1_scored: bool) {
-        // Update score
+        // Update appropriate player's score
         if p1_scored {
             self.p1 += 1;
         } else {
@@ -62,25 +67,26 @@ impl Score {
 
         self.serve_count += 1;
 
-        // Check for deuce conditions
+        // Check for deuce conditions (both players at 10+)
         let in_deuce = self.p1 >= 10 && self.p2 >= 10;
         let switch_threshold = if in_deuce { 1 } else { 2 };
 
-        // Switch server if threshold reached
+        // Switch server if we've hit the threshold
         if self.serve_count >= switch_threshold {
             self.server_is_p1 = !self.server_is_p1;
             self.serve_count = 0;
         }
     }
 
-    /// Checks if the game has reached a victory condition
+    /// Checks if either player has won the game.
     ///
-    /// Victory is achieved when:
-    /// - A player reaches 11 or more points AND
-    /// - They have a lead of at least 2 points
+    /// Victory conditions (official table tennis rules):
+    /// 1. Score must be 11 or higher
+    /// 2. Must have a 2-point lead
     ///
     /// # Returns
-    /// `true` if either player has won, `false` if the game should continue
+    /// * `true` if either player has won
+    /// * `false` if game should continue
     pub fn check_victory(&self) -> bool {
         if self.p1 >= 11 && self.p1 >= self.p2 + 2 {
             return true;
@@ -91,13 +97,13 @@ impl Score {
         false
     }
 
-    /// Resets the game state to initial values for a new game
+    /// Resets scoring state for a new game.
     ///
-    /// This:
-    /// - Clears both players' scores
-    /// - Randomly assigns a new server
-    /// - Resets serve count and timer
-    /// - Clears any pending serve flags
+    /// This resets:
+    /// - Both players' scores to 0
+    /// - Serve count to 0
+    /// - Randomly assigns initial server
+    /// - Clears any pending serve state
     pub fn reset(&mut self) {
         self.p1 = 0;
         self.p2 = 0;
@@ -108,30 +114,34 @@ impl Score {
     }
 }
 
-/// Component to identify score display text entities.
-/// Used for both individual score texts and their container.
+// ----- Components -----
+
+/// Component to identify and differentiate score display UI elements.
 #[derive(Component)]
 struct ScoreText {
     kind: ScoreKind,
 }
 
-/// Enum to differentiate between different score UI elements
+/// Types of score display UI elements.
 enum ScoreKind {
-    P1,   // Player 1's score text
-    P2,   // Player 2's score text
-    Root, // The container node
+    P1,   // Player 1's score display
+    P2,   // Player 2's score display
+    Root, // Container element
 }
 
-/// Initializes the Score resource at startup.
-/// This runs once when the game starts and persists through all states.
-fn init_score(mut commands: Commands) {
-    commands.insert_resource(Score::new());
-}
+// ----- UI Creation and Management Systems -----
 
-/// Sets up the score display UI when entering Playing state.
-/// The UI is only visible during actual gameplay.
-fn setup_score_ui(mut commands: Commands) {
-    // Create UI root container
+/// Creates the score display UI layout.
+///
+/// Layout structure:
+/// - Root container (centered, fixed width)
+///   - Player 1 score (left side)
+///   - Player 2 score (right side)
+///
+/// # Arguments
+/// * `commands` - Command buffer for entity creation
+/// * `score` - Current score resource for initial values
+fn setup_score_ui(mut commands: Commands, score: Res<Score>) {
     commands
         .spawn((
             Node {
@@ -143,51 +153,80 @@ fn setup_score_ui(mut commands: Commands) {
                 flex_direction: FlexDirection::Row,
                 ..default()
             },
-            ScoreText {
-                kind: ScoreKind::Root,
-            }, // Mark for cleanup
+            ScoreText { kind: ScoreKind::Root },
         ))
         .with_children(|parent| {
-            // Player 1 score text
-            parent.spawn((
-                Text::new("0"),
-                TextFont {
-                    font_size: 48.0,
-                    ..default()
-                },
-                TextColor(Color::WHITE),
-                Node {
-                    margin: UiRect::right(Val::Px(20.0)),
-                    ..default()
-                },
-                ScoreText {
-                    kind: ScoreKind::P1,
-                },
-            ));
-
-            // Player 2 score text
-            parent.spawn((
-                Text::new("0"),
-                TextFont {
-                    font_size: 48.0,
-                    ..default()
-                },
-                TextColor(Color::WHITE),
-                Node {
-                    margin: UiRect::left(Val::Px(20.0)),
-                    ..default()
-                },
-                ScoreText {
-                    kind: ScoreKind::P2,
-                },
-            ));
+            spawn_player_score(parent, score.p1, ScoreKind::P1, UiRect::right(Val::Px(20.0)));
+            spawn_player_score(parent, score.p2, ScoreKind::P2, UiRect::left(Val::Px(20.0)));
         });
 }
 
-/// Spawns a new ball when:
-/// - Entering Playing state initially
-/// - Resuming from pause
-/// - Starting a new game after victory
+/// Helper function to spawn individual player score displays.
+///
+/// # Arguments
+/// * `parent` - Parent UI node to attach to
+/// * `score` - Initial score value to display
+/// * `kind` - Which player's score this represents
+/// * `margin` - Margin settings for positioning
+fn spawn_player_score(
+    parent: &mut ChildBuilder,
+    score: u32,
+    kind: ScoreKind,
+    margin: UiRect,
+) {
+    parent.spawn((
+        Text::new(score.to_string()),
+        TextFont {
+            font_size: 48.0,
+            ..default()
+        },
+        TextColor(Color::WHITE),
+        Node { margin, ..default() },
+        ScoreText { kind },
+    ));
+}
+
+/// Updates score display text to match current game state.
+///
+/// This system:
+/// - Runs continuously during gameplay
+/// - Updates only when text doesn't match current score
+/// - Ensures consistency after state transitions
+fn update_score_display(score: Res<Score>, mut query: Query<(&mut Text, &ScoreText)>) {
+    for (mut text, score_text) in query.iter_mut() {
+        let current_score = match score_text.kind {
+            ScoreKind::P1 => score.p1,
+            ScoreKind::P2 => score.p2,
+            ScoreKind::Root => continue,
+        };
+
+        let score_text = current_score.to_string();
+        if **text != score_text {
+            **text = score_text;
+        }
+    }
+}
+
+/// Removes score display UI when leaving gameplay state.
+fn cleanup_score_ui(mut commands: Commands, query: Query<Entity, With<ScoreText>>) {
+    for entity in query.iter() {
+        commands.entity(entity).despawn_recursive();
+    }
+}
+
+// ----- Gameplay Systems -----
+
+/// Creates initial Score resource.
+fn init_score(mut commands: Commands) {
+    commands.insert_resource(Score::new());
+}
+
+/// Manages ball spawning for various game situations.
+///
+/// Spawns ball:
+/// - At start of new game
+/// - After resuming from pause
+/// - After each point (with serve delay)
 fn on_resume(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,
@@ -195,39 +234,17 @@ fn on_resume(
     score: Res<Score>,
     ball_query: Query<Entity, With<Ball>>,
 ) {
-    // Only spawn if no ball exists and we're not in serve delay
     if ball_query.is_empty() && !score.should_serve {
-        create_ball(
-            &mut commands,
-            &mut meshes,
-            &mut materials,
-            score.server_is_p1,
-        );
+        create_ball(&mut commands, &mut meshes, &mut materials, score.server_is_p1);
     }
 }
 
-/// Checks for victory conditions and transitions to GameOver state.
-/// This only runs during active gameplay.
-fn check_victory(
-    score: Res<Score>,
-    mut commands: Commands,
-    mut next_state: ResMut<NextState<GameState>>,
-    ball_query: Query<Entity, With<Ball>>,
-) {
-    if score.check_victory() {
-        // Despawn the ball to prevent further scoring
-        for entity in ball_query.iter() {
-            commands.entity(entity).despawn();
-        }
-        // Transition to game over state
-        next_state.set(GameState::GameOver);
-    }
-}
-
-/// Handles the delay between scoring and serving.
-/// This provides a brief pause after points to:
-/// - Let players see what happened
-/// - Prepare for the next serve
+/// Implements serve delay mechanics between points.
+///
+/// This provides:
+/// - Visual pause between points
+/// - Time for players to prepare
+/// - Consistent serve timing
 fn handle_serve_delay(
     time: Res<Time>,
     mut score: ResMut<Score>,
@@ -239,23 +256,19 @@ fn handle_serve_delay(
         score.serve_timer.tick(time.delta());
 
         if score.serve_timer.just_finished() {
-            create_ball(
-                &mut commands,
-                &mut meshes,
-                &mut materials,
-                score.server_is_p1,
-            );
+            create_ball(&mut commands, &mut meshes, &mut materials, score.server_is_p1);
             score.should_serve = false;
             score.serve_timer.reset();
         }
     }
 }
 
-/// Handles ball collisions with scoring walls.
-/// When ball hits left/right walls:
-/// 1. Updates appropriate player's score
-/// 2. Despawns the ball
-/// 3. Triggers serve delay
+/// Processes ball-wall collisions for scoring.
+///
+/// When ball hits scoring wall:
+/// 1. Awards point to appropriate player
+/// 2. Removes the ball
+/// 3. Initiates serve sequence
 fn handle_scoring(
     mut commands: Commands,
     mut score: ResMut<Score>,
@@ -265,7 +278,7 @@ fn handle_scoring(
 ) {
     for collision_event in collision_events.read() {
         if let CollisionEvent::Started(e1, e2, _) = collision_event {
-            // Find the ball and wall entities involved
+            // Find colliding entities
             let ball_entity = ball_query.iter().find(|e| *e == *e1 || *e == *e2);
             let wall = wall_query
                 .iter()
@@ -291,55 +304,49 @@ fn handle_scoring(
     }
 }
 
-/// Updates the score display text whenever scores change
-fn update_score_display(score: Res<Score>, mut query: Query<(&mut Text, &ScoreText)>) {
-    if score.is_changed() {
-        for (mut text, score_text) in query.iter_mut() {
-            match score_text.kind {
-                ScoreKind::P1 => {
-                    **text = score.p1.to_string();
-                }
-                ScoreKind::P2 => {
-                    **text = score.p2.to_string();
-                }
-                ScoreKind::Root => {} // Container doesn't need updating
-            }
+/// Monitors for victory conditions during gameplay.
+///
+/// When victory detected:
+/// 1. Removes the ball to prevent further scoring
+/// 2. Transitions to game over state
+fn check_victory(
+    score: Res<Score>,
+    mut commands: Commands,
+    mut next_state: ResMut<NextState<GameState>>,
+    ball_query: Query<Entity, With<Ball>>,
+) {
+    if score.check_victory() {
+        for entity in ball_query.iter() {
+            commands.entity(entity).despawn();
         }
+        next_state.set(GameState::GameOver);
     }
 }
 
-/// Cleans up the score UI elements when exiting Playing state.
-/// This ensures the UI is removed during:
-/// - Game over
-/// - Pause menu
-/// - Return to splash screen
-fn cleanup_score_ui(mut commands: Commands, query: Query<Entity, With<ScoreText>>) {
-    for entity in query.iter() {
-        commands.entity(entity).despawn_recursive();
-    }
-}
+// ----- Plugin Setup -----
 
-/// Plugin that manages scoring functionality
+/// Plugin that manages all scoring functionality.
 pub struct ScorePlugin;
 
 impl Plugin for ScorePlugin {
     fn build(&self, app: &mut App) {
         app
-            // Initialize score resource at startup
+            // Resource initialization
             .add_systems(Startup, init_score)
-            // Setup UI when entering Playing state
-            .add_systems(OnEnter(GameState::Playing), setup_score_ui)
-            // Clean up UI when exiting Playing state
+
+            // UI management
+            .add_systems(OnEnter(GameState::Playing), (setup_score_ui, update_score_display))
             .add_systems(OnExit(GameState::Playing), cleanup_score_ui)
-            // Handle ball spawning when entering Playing state
             .add_systems(OnEnter(GameState::Playing), on_resume)
-            // Update score display whenever scores change
-            .add_systems(Update, update_score_display)
-            // Handle scoring, serving, and victory checking during gameplay
+
+            // Score display updates
+            .add_systems(Update, update_score_display.run_if(in_state(GameState::Playing)))
+
+            // Gameplay systems
             .add_systems(
                 Update,
                 (handle_scoring, handle_serve_delay, check_victory)
                     .run_if(in_state(GameState::Playing)),
             );
     }
-}
+}
\ No newline at end of file

From 2da636efaa1ade73df3db02d1bbc76eb27965dec Mon Sep 17 00:00:00 2001
From: Alcibiades Athens <alcibiades.eth@protonmail.com>
Date: Sat, 28 Dec 2024 18:12:51 -0500
Subject: [PATCH 4/4] fix: cleanup lint

---
 src/audio.rs  | 11 +----------
 src/player.rs |  6 ------
 src/score.rs  | 52 ++++++++++++++++++++++++++++++++++-----------------
 3 files changed, 36 insertions(+), 33 deletions(-)

diff --git a/src/audio.rs b/src/audio.rs
index 431fa33..e95316f 100644
--- a/src/audio.rs
+++ b/src/audio.rs
@@ -22,7 +22,7 @@ pub struct MusicPlugin;
 ///
 /// The state persists across game state changes to maintain user preferences
 /// for music playback.
-#[derive(Resource)]
+#[derive(Resource, Default)]
 struct MusicState {
     /// Indicates if music should be playing (true) or muted (false)
     playing: bool,
@@ -31,15 +31,6 @@ struct MusicState {
     handle: Option<Handle<AudioInstance>>,
 }
 
-impl Default for MusicState {
-    fn default() -> Self {
-        Self {
-            playing: false, // Start with music enabled by default
-            handle: None,   // No audio instance at initialization
-        }
-    }
-}
-
 impl Plugin for MusicPlugin {
     fn build(&self, app: &mut App) {
         app.add_plugins(AudioPlugin)
diff --git a/src/player.rs b/src/player.rs
index 856cc7c..f4ece98 100644
--- a/src/player.rs
+++ b/src/player.rs
@@ -18,14 +18,10 @@ use std::time::Duration;
 pub struct PaddleConfig {
     /// Movement speed in world units per second
     pub speed: f32,
-    /// Maximum angle the ball can bounce (in radians)
-    pub max_bounce_angle: f32,
     /// X-coordinate for left paddle position
     pub left_x: f32,
     /// X-coordinate for right paddle position
     pub right_x: f32,
-    /// Base width of the paddle
-    pub width: f32,
     /// Total height of the paddle
     pub height: f32,
     /// Depth of the paddle's curve
@@ -44,10 +40,8 @@ impl Default for PaddleConfig {
     fn default() -> Self {
         Self {
             speed: 20.0,
-            max_bounce_angle: 1.0,
             left_x: -7.65,
             right_x: 7.65,
-            width: 0.5,
             height: 2.0,
             curve_depth: 0.3,
             segments: 100,
diff --git a/src/score.rs b/src/score.rs
index 02d6806..e12bc62 100644
--- a/src/score.rs
+++ b/src/score.rs
@@ -153,10 +153,17 @@ fn setup_score_ui(mut commands: Commands, score: Res<Score>) {
                 flex_direction: FlexDirection::Row,
                 ..default()
             },
-            ScoreText { kind: ScoreKind::Root },
+            ScoreText {
+                kind: ScoreKind::Root,
+            },
         ))
         .with_children(|parent| {
-            spawn_player_score(parent, score.p1, ScoreKind::P1, UiRect::right(Val::Px(20.0)));
+            spawn_player_score(
+                parent,
+                score.p1,
+                ScoreKind::P1,
+                UiRect::right(Val::Px(20.0)),
+            );
             spawn_player_score(parent, score.p2, ScoreKind::P2, UiRect::left(Val::Px(20.0)));
         });
 }
@@ -168,12 +175,7 @@ fn setup_score_ui(mut commands: Commands, score: Res<Score>) {
 /// * `score` - Initial score value to display
 /// * `kind` - Which player's score this represents
 /// * `margin` - Margin settings for positioning
-fn spawn_player_score(
-    parent: &mut ChildBuilder,
-    score: u32,
-    kind: ScoreKind,
-    margin: UiRect,
-) {
+fn spawn_player_score(parent: &mut ChildBuilder, score: u32, kind: ScoreKind, margin: UiRect) {
     parent.spawn((
         Text::new(score.to_string()),
         TextFont {
@@ -181,7 +183,10 @@ fn spawn_player_score(
             ..default()
         },
         TextColor(Color::WHITE),
-        Node { margin, ..default() },
+        Node {
+            margin,
+            ..default()
+        },
         ScoreText { kind },
     ));
 }
@@ -235,7 +240,12 @@ fn on_resume(
     ball_query: Query<Entity, With<Ball>>,
 ) {
     if ball_query.is_empty() && !score.should_serve {
-        create_ball(&mut commands, &mut meshes, &mut materials, score.server_is_p1);
+        create_ball(
+            &mut commands,
+            &mut meshes,
+            &mut materials,
+            score.server_is_p1,
+        );
     }
 }
 
@@ -256,7 +266,12 @@ fn handle_serve_delay(
         score.serve_timer.tick(time.delta());
 
         if score.serve_timer.just_finished() {
-            create_ball(&mut commands, &mut meshes, &mut materials, score.server_is_p1);
+            create_ball(
+                &mut commands,
+                &mut meshes,
+                &mut materials,
+                score.server_is_p1,
+            );
             score.should_serve = false;
             score.serve_timer.reset();
         }
@@ -333,15 +348,18 @@ impl Plugin for ScorePlugin {
         app
             // Resource initialization
             .add_systems(Startup, init_score)
-
             // UI management
-            .add_systems(OnEnter(GameState::Playing), (setup_score_ui, update_score_display))
+            .add_systems(
+                OnEnter(GameState::Playing),
+                (setup_score_ui, update_score_display),
+            )
             .add_systems(OnExit(GameState::Playing), cleanup_score_ui)
             .add_systems(OnEnter(GameState::Playing), on_resume)
-
             // Score display updates
-            .add_systems(Update, update_score_display.run_if(in_state(GameState::Playing)))
-
+            .add_systems(
+                Update,
+                update_score_display.run_if(in_state(GameState::Playing)),
+            )
             // Gameplay systems
             .add_systems(
                 Update,
@@ -349,4 +367,4 @@ impl Plugin for ScorePlugin {
                     .run_if(in_state(GameState::Playing)),
             );
     }
-}
\ No newline at end of file
+}