bevy-ichun 0.6.0

//! # Gravity Action
//!
//! This module provides gravity modification functionality for kinematic character controllers.
//! It allows overriding or limiting the character's falling speed by applying custom gravity values.

use bevy::math::Vec3;

use crate::kcc::KccVelocity;

/// Action for modifying gravity effects on a character.
///
/// This action allows you to override or limit the character's downward velocity
/// by applying a custom gravity value. It's commonly used for:
///
/// * **Floating/Gliding**: Reducing fall speed for gliding mechanics
/// * **Low Gravity Areas**: Creating areas with different gravity
/// * **Terminal Velocity**: Capping maximum fall speed
/// * **Anti-Gravity**: Creating upward forces or zero gravity
///
/// The action works by clamping the Y velocity to not exceed the custom gravity value,
/// effectively limiting how fast the character can fall.
///
/// ## Example
///
/// ```rust
/// use bevy::math::Vec3;
/// use your_crate::actions::GravityAction;
///
/// // Create a floating/gliding effect (slower falling)
/// let floating = GravityAction::new(Vec3::new(0.0, -2.0, 0.0));
///
/// // Create zero gravity
/// let zero_gravity = GravityAction::new(Vec3::ZERO);
///
/// // Create upward force (anti-gravity)
/// let anti_gravity = GravityAction::new(Vec3::new(0.0, 5.0, 0.0));
/// ```
#[derive(Default, Debug)]
pub struct GravityAction {
    /// The custom gravity vector to apply.
    pub custom_gravity: Vec3,
}

impl GravityAction {
    /// Creates a new gravity action with the specified custom gravity.
    ///
    /// # Arguments
    ///
    /// * `custom_gravity` - The gravity vector to apply. The Y component controls
    ///   vertical gravity, while X and Z can be used for directional forces.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use bevy::math::Vec3;
    /// use your_crate::actions::GravityAction;
    ///
    /// // Slow falling (floating effect)
    /// let slow_fall = GravityAction::new(Vec3::new(0.0, -3.0, 0.0));
    ///
    /// // Zero gravity
    /// let weightless = GravityAction::new(Vec3::ZERO);
    /// ```
    pub fn new(custom_gravity: Vec3) -> Self {
        Self { custom_gravity }
    }

    pub(super) fn apply(&mut self, kcc_vel: &mut KccVelocity) {
        // Apply custom gravity to the Y velocity
        // Using max() ensures we don't fall faster than the custom gravity allows
        kcc_vel.0.y = kcc_vel.0.y.max(self.custom_gravity.y);
    }
}