bevy-ichun 0.5.0

A simple kinematic character controller for avian3d
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

//! # System Sets for the Ichun Character Controller
//!
//! This module defines the system sets used for ordering the execution of
//! character controller systems. The `IchunSystemSetsPlugin` configures these sets
//! in the correct order within Bevy's update schedule and is automatically added
//! when using the main Ichun character controller plugin.
//!
//! System sets ensure that systems run in the correct order to maintain proper
//! data flow and dependencies. For example, input processing should happen before
//! movement calculations, and physics updates should happen at specific times.
//!
//! ## System Set Execution Order
//!
//! 1. `InputSet`: Process player input and generate movement events
//! 2. `KccPhysicsSet`: Handle physics calculations (grounding, gravity, etc.)
//!
//! 3. `MovementEventsSet`: Handles movement events based on input and writes the movement actions
//! 4. `ActionsSets`: Apply movement actions to the KCC
//! 5. `VelocityModifiersSet`: Modify velocity (external forces, physics & movement)
//!
//! ## Usage in Custom Systems
//!
//! When adding your own systems that interact with the character controller,
//! you can use these sets to ensure your systems run at the appropriate time:
//!
//! ```rust
//! use bevy::prelude::*;
//! use bevy_ichun::system_sets::IchunSystemSet;
//!
//! fn my_movement_system() {
//!     // System implementation
//! }
//!
//! fn plugin_setup(app: &mut App) {
//!     // Run custom system during the movement phase
//!     app.add_systems(Update, my_movement_system.in_set(IchunSystemSet::MovementSet));
//! }
//! ```
use bevy::{
    app::{Plugin, Update},
    ecs::schedule::{IntoScheduleConfigs, SystemSet},
};

/// Plugin that configures the system sets for the Ichun character controller.
///
/// This plugin configures all the system sets in a sequential chain to ensure proper
/// execution order of the character controller systems. It is automatically added
/// when using the main Ichun character controller plugin.
pub struct IchunSystemSetsPlugin;

impl Plugin for IchunSystemSetsPlugin {
    fn build(&self, app: &mut bevy::app::App) {
        app.configure_sets(
            Update,
            (
                IchunSystemSet::InputSet,
                IchunSystemSet::KccPhysicsSet,
                IchunSystemSet::MovementEventsSet,
                IchunSystemSet::ActionsSet,
                IchunSystemSet::VelocityModifiersSet,
            )
                .chain(),
        );
    }
}

/// System sets for organizing the character controller systems.
///
/// These sets are executed in the following order:
/// 1. `InputSet`: Process player input
/// 2. `KccPhysicsSet`: Handle physics calculations
/// 3. `MovementEventsSet`: Handles movement events based on input and writes the movement actions
/// 4. `ActionsSets`: Apply movement actions to the KCC
/// 5. `VelocityModifiersSet`: Modify velocity (external forces, physics & movement)
///
/// # Usage
///
/// When adding your own systems, you can use these sets to ensure they run
/// at the appropriate time relative to the character controller systems:
///
/// ```rust
/// use bevy::prelude::*;
/// use ichun::system_sets::IchunSystemSet;
///
/// fn my_movement_system() {
///     // System implementation
/// }
///
/// fn plugin_setup(app: &mut App) {
///     app.add_systems(Update, my_movement_system.in_set(IchunSystemSet::MovementSet));
/// }
/// ```
#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
pub enum IchunSystemSet {
    /// Process player input for character movement.
    /// Systems in this set detect player input and generate movement events.
    InputSet,
    /// Perform physics calculations for the kinematic character controller.
    /// Systems in this set handle gravity, ground detection, and physics interactions.
    KccPhysicsSet,
    /// Convert movement events to action components.
    /// Systems in this set respond to movement events and create/update action components on entities.
    MovementEventsSet,
    /// Process action components and apply movement logic.
    /// Systems in this set read action components and apply their effects to velocity, transform, and other character properties.
    ActionsSet,
    /// Apply velocity modifiers like damping, clamping, etc. and
    /// adds up kcc velocity and external force to linear velocity
    /// Systems in this set perform final adjustments to velocity before it's applied.
    VelocityModifiersSet,
}