veloren_common/comp/
energy.rs

1use crate::comp;
2use serde::{Deserialize, Serialize};
3use specs::{Component, DerefFlaggedStorage};
4use std::ops::Mul;
5
6#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
7/// Energy is represented by u32s within the module, but treated as a float by
8/// the rest of the game.
9// As a general rule, all input and output values to public functions should be
10// floats rather than integers.
11pub struct Energy {
12    // Current and base_max are scaled by 256 within this module compared to what is visible to
13    // outside this module. The scaling is done to allow energy to function as a fixed point while
14    // still having the advantages of being an integer. The scaling of 256 was chosen so that max
15    // energy could be u16::MAX - 1, and then the scaled energy could fit inside an f32 with no
16    // precision loss
17    /// Current energy is how much energy the entity currently has
18    current: u32,
19    /// Base max is the amount of energy the entity has without considering
20    /// temporary modifiers such as buffs
21    base_max: u32,
22    /// Maximum is the amount of energy the entity has after temporary modifiers
23    /// are considered
24    maximum: u32,
25    /// Rate of regeneration per tick. Starts at zero and accelerates.
26    regen_rate: f32,
27}
28
29impl Energy {
30    /// Used when comparisons to energy are needed outside this module.
31    // This value is chosen as anything smaller than this is more precise than our
32    // units of energy.
33    pub const ENERGY_EPSILON: f32 = 0.5 / Self::MAX_SCALED_ENERGY as f32;
34    /// Maximum value allowed for energy before scaling
35    const MAX_ENERGY: u16 = u16::MAX - 1;
36    /// The maximum value allowed for current and maximum energy
37    /// Maximum value is (u16:MAX - 1) * 256, which only requires 24 bits. This
38    /// can fit into an f32 with no loss to precision
39    // Cast to u32 done as u32::from cannot be called inside constant
40    const MAX_SCALED_ENERGY: u32 = Self::MAX_ENERGY as u32 * Self::SCALING_FACTOR_INT;
41    /// The amount energy is scaled by within this module
42    const SCALING_FACTOR_FLOAT: f32 = 256.;
43    const SCALING_FACTOR_INT: u32 = Self::SCALING_FACTOR_FLOAT as u32;
44
45    /// Returns the current value of energy casted to a float
46    pub fn current(&self) -> f32 { self.current as f32 / Self::SCALING_FACTOR_FLOAT }
47
48    /// Returns the base maximum value of energy casted to a float
49    pub fn base_max(&self) -> f32 { self.base_max as f32 / Self::SCALING_FACTOR_FLOAT }
50
51    /// Returns the maximum value of energy casted to a float
52    pub fn maximum(&self) -> f32 { self.maximum as f32 / Self::SCALING_FACTOR_FLOAT }
53
54    /// Returns the fraction of energy an entity has remaining
55    pub fn fraction(&self) -> f32 { self.current() / self.maximum().max(1.0) }
56
57    /// Calculates a new maximum value and returns it if the value differs from
58    /// the current maximum.
59    ///
60    /// Note: The returned value uses an internal format so don't expect it to
61    /// be useful for anything other than a parameter to
62    /// [`Self::update_maximum`].
63    pub fn needs_maximum_update(&self, modifiers: comp::stats::StatsModifier) -> Option<u32> {
64        let maximum = modifiers
65            .compute_maximum(self.base_max())
66            .mul(Self::SCALING_FACTOR_FLOAT)
67            // NaN does not need to be handled here as rust will automatically change to 0 when casting to u32
68            .clamp(0.0, Self::MAX_SCALED_ENERGY as f32) as u32;
69
70        (maximum != self.maximum).then_some(maximum)
71    }
72
73    /// Updates the maximum value for energy.
74    ///
75    /// Note: The accepted `u32` value is in the internal format of this type.
76    /// So attempting to pass values that weren't returned from
77    /// [`Self::needs_maximum_update`] can produce strange or unexpected
78    /// results.
79    pub fn update_internal_integer_maximum(&mut self, maximum: u32) {
80        self.maximum = maximum;
81        // Clamp the current energy to enforce the current <= maximum invariant.
82        self.current = self.current.min(self.maximum);
83    }
84
85    pub fn new(body: comp::Body) -> Self {
86        let energy = u32::from(body.base_energy()) * Self::SCALING_FACTOR_INT;
87        Energy {
88            current: energy,
89            base_max: energy,
90            maximum: energy,
91            regen_rate: 0.0,
92        }
93    }
94
95    /// Returns `true` if the current value is less than the maximum
96    pub fn needs_regen(&self) -> bool { self.current < self.maximum }
97
98    /// Regenerates energy based on the provided acceleration
99    pub fn regen(&mut self, accel: f32, dt: f32) {
100        if self.current < self.maximum {
101            self.change_by(self.regen_rate * dt);
102            self.regen_rate = (self.regen_rate + accel * dt).min(10.0);
103        }
104    }
105
106    /// Checks whether the `regen_rate` is zero or not. Returns true if the
107    /// value is anything other than `0.0`.
108    pub fn needs_regen_rate_reset(&self) -> bool { self.regen_rate != 0.0 }
109
110    /// Resets the energy regeneration rate to zero
111    pub fn reset_regen_rate(&mut self) { self.regen_rate = 0.0 }
112
113    pub fn change_by(&mut self, change: f32) {
114        self.current = (((self.current() + change).clamp(0.0, f32::from(Self::MAX_ENERGY))
115            * Self::SCALING_FACTOR_FLOAT) as u32)
116            .min(self.maximum);
117    }
118
119    #[expect(clippy::result_unit_err)]
120    pub fn try_change_by(&mut self, change: f32) -> Result<(), ()> {
121        let new_val = self.current() + change;
122        if new_val < 0.0 || new_val > self.maximum() {
123            Err(())
124        } else {
125            self.change_by(change);
126            Ok(())
127        }
128    }
129
130    pub fn refresh(&mut self) { self.current = self.maximum; }
131}
132
133impl Component for Energy {
134    type Storage = DerefFlaggedStorage<Self, specs::VecStorage<Self>>;
135}
veloren_common/comp/energy.rs

veloren_common/comp/
energy.rs
