docs: pumpkin-util (#1719)

* init

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

* part 1

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

* finished math section

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

* fmt

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

* finished text and some initial work on other unfinished folders

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

* fmt

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

* fmt

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

* finish noise

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

* finish random

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>

---------

Signed-off-by: illyrius666 <28700752+illyrius666@users.noreply.github.com>
Signed-off-by: Illyrius <28700752+illyrius666@users.noreply.github.com>

Author: illyrius666

pumpkin-util/Cargo.toml

@@ -21,9 +21,7 @@ proc-macro2.workspace = true
 enum_dispatch.workspace = true
 
 uuid.workspace = true
-tokio = { workspace = true, features = [
-    "sync",
-] }
+tokio = { workspace = true, features = ["sync"] }
 base64.workspace = true
 p384 = { workspace = true, features = ["ecdsa"] }
 thiserror.workspace = true

pumpkin-util/src/biome.rs

@@ -4,29 +4,44 @@ use serde::Deserialize;
 
 use crate::{noise::simplex::OctaveSimplexNoiseSampler, random::legacy_rand::LegacyRand};
 
+/// Global noise sampler for biome temperature variation.
 pub static TEMPERATURE_NOISE: LazyLock<OctaveSimplexNoiseSampler> = LazyLock::new(|| {
     let mut rand = LegacyRand::from_seed(1234);
     OctaveSimplexNoiseSampler::new(&mut rand, &[0])
 });
 
+/// Global noise sampler for frozen ocean biome adjustments.
 pub static FROZEN_OCEAN_NOISE: LazyLock<OctaveSimplexNoiseSampler> = LazyLock::new(|| {
     let mut rand = LegacyRand::from_seed(3456);
     OctaveSimplexNoiseSampler::new(&mut rand, &[-2, -1, 0])
 });
 
+/// Global noise sampler for foliage-based temperature adjustments.
 pub static FOLIAGE_NOISE: LazyLock<OctaveSimplexNoiseSampler> = LazyLock::new(|| {
     let mut rand = LegacyRand::from_seed(2345);
     OctaveSimplexNoiseSampler::new(&mut rand, &[0])
 });
 
+/// Modifiers that adjust the base biome temperature.
 #[derive(Clone, Deserialize, Copy, Hash, PartialEq, Eq, Debug)]
 #[serde(rename_all = "UPPERCASE")]
 pub enum TemperatureModifier {
+    /// No temperature modification.
     None,
+    /// Frozen biome adjustment, typically used for frozen oceans and snowy areas.
     Frozen,
 }
 
 impl TemperatureModifier {
+    /// Applies the temperature modifier to a given position and base temperature.
+    ///
+    /// # Parameters
+    /// - `x`: X coordinate in the world.
+    /// - `z`: Z coordinate in the world.
+    /// - `temperature`: The base biome temperature.
+    ///
+    /// # Returns
+    /// - The modified temperature as an `f32`.
     pub fn convert_temperature(&self, x: f64, z: f64, temperature: f32) -> f32 {
         match self {
             Self::None => temperature,
@@ -49,17 +64,28 @@ impl TemperatureModifier {
     }
 }
 
+/// Represents weather information for a biome, including temperature and precipitation.
 #[derive(Clone, Debug)]
 pub struct Weather {
     #[expect(dead_code)]
     has_precipitation: bool,
+    /// Base temperature of the biome.
     temperature: f32,
+    /// Modifier affecting the base temperature.
     temperature_modifier: TemperatureModifier,
+    /// Rate of rainfall or snowfall in the biome.
     #[expect(dead_code)]
     downfall: f32,
 }
 
 impl Weather {
+    /// Creates a new `Weather` instance.
+    ///
+    /// # Parameters
+    /// - `has_precipitation`: Whether the biome has precipitation.
+    /// - `temperature`: Base temperature of the biome.
+    /// - `temperature_modifier`: Modifier affecting the temperature.
+    /// - `downfall`: Amount of rainfall or snowfall.
     #[must_use]
     pub const fn new(
         has_precipitation: bool,
@@ -75,7 +101,19 @@ impl Weather {
         }
     }
 
-    /// This is an expensive function and should be cached
+    /// Computes the effective temperature at a given position.
+    ///
+    /// # Parameters
+    /// - `x`, `z`: World coordinates.
+    /// - `y`: Y-level of the position.
+    /// - `sea_level`: Sea level in the world.
+    ///
+    /// # Returns
+    /// - The temperature at the position as `f32`.
+    ///
+    /// # Notes
+    /// - This function is computationally expensive and should be cached.
+    /// - Temperature is influenced by `TemperatureModifier` and noise samplers.
     pub fn compute_temperature(&self, x: f64, y: i32, z: f64, sea_level: i32) -> f32 {
         let modified_temperature =
             self.temperature_modifier

pumpkin-util/src/difficulty.rs

@@ -3,13 +3,25 @@ use std::str::FromStr;
 use num_derive::{FromPrimitive, ToPrimitive};
 use serde::{Deserialize, Serialize};
 
+/// Error returned when parsing a [`Difficulty`] from a string fails.
 pub struct ParseDifficultyError;
 
+/// Represents the difficulty level of the game.
+///
+/// Each numeric value corresponds to a specific difficulty:
+/// - `Peaceful` (0): No hostile mobs spawn, health regenerates naturally.
+/// - `Easy` (1): Standard gameplay, hostile mobs spawn with reduced damage.
+/// - `Normal` (2): Standard difficulty with full damage from mobs.
+/// - `Hard` (3): Hostile mobs deal extra damage and health regeneration is limited.
 #[derive(Serialize, Deserialize, FromPrimitive, ToPrimitive, PartialEq, Eq, Clone, Copy, Debug)]
 pub enum Difficulty {
+    /// No hostile mobs; natural health regeneration.
     Peaceful = 0,
+    /// Easy difficulty; hostile mobs deal reduced damage.
     Easy = 1,
+    /// Normal difficulty; standard mob damage and health.
     Normal = 2,
+    /// Hard difficulty; increased mob damage and limited health regen.
     Hard = 3,
 }
 

pumpkin-util/src/gamemode.rs

@@ -1,18 +1,25 @@
 use serde::{Deserialize, Serialize};
 use std::str::FromStr;
 
+/// Error returned when parsing a string into a [`GameMode`] fails.
 #[derive(Debug, PartialEq, Eq)]
 pub struct ParseGameModeError;
 
+/// Represents the various game modes a player can be in.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
 pub enum GameMode {
+    /// Standard survival mode: players take damage, gather resources, and interact normally.
     Survival = 0,
+    /// Creative mode: players have unlimited resources, can fly, and cannot take damage.
     Creative = 1,
+    /// Adventure mode: players cannot break blocks without the proper tools.
     Adventure = 2,
+    /// Spectator mode: players can fly through blocks and observe without interacting.
     Spectator = 3,
 }
 
 impl GameMode {
+    /// Returns the display string for this game mode.
     #[must_use]
     pub const fn to_str(&self) -> &'static str {
         match self {
@@ -27,6 +34,18 @@ impl GameMode {
 impl TryFrom<i8> for GameMode {
     type Error = ();
 
+    /// Attempts to convert an `i8` value into a [`GameMode`].
+    ///
+    /// # Parameters
+    /// - `value`: The numeric representation of a game mode.
+    ///
+    /// # Returns
+    /// - `Ok(GameMode)` if the value corresponds to a valid game mode:
+    ///   - `0` → `Survival`
+    ///   - `1` → `Creative`
+    ///   - `2` → `Adventure`
+    ///   - `3` → `Spectator`
+    /// - `Err(())` if the value does not correspond to any valid game mode.
     fn try_from(value: i8) -> Result<Self, Self::Error> {
         match value {
             0 => Ok(Self::Survival),

pumpkin-util/src/lib.rs

@@ -28,17 +28,25 @@ pub mod y_offset;
 
 pub mod jwt;
 
+/// Represents the different types of height maps used for terrain generation and collision checks.
 #[derive(Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
 #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum HeightMap {
+    /// Topmost block including plants, snow layers, and surface features (used during world generation).
     WorldSurfaceWg,
+    /// Topmost solid or liquid block counting as surface.
     WorldSurface,
+    /// Lowest solid block in oceans including underwater terrain features (used during world generation).
     OceanFloorWg,
+    /// Lowest solid block in oceans, ignoring non-solid features like kelp.
     OceanFloor,
+    /// Topmost block that blocks entity motion (ignores leaves).
     MotionBlocking,
+    /// Topmost block that blocks entity motion, ignoring leaf blocks.
     MotionBlockingNoLeaves,
 }
 
+/// Constructs a global file system path relative to the project root.
 #[macro_export]
 macro_rules! global_path {
     ($path:expr) => {{
@@ -53,7 +61,7 @@ macro_rules! global_path {
     }};
 }
 
-/// Reads JSON files from disk. Don't use this for static files!
+/// Reads JSON files from the disk. Don't use this for static files!
 #[macro_export]
 macro_rules! read_data_from_file {
     ($path:expr) => {{
@@ -86,24 +94,35 @@ pub fn encompassing_bits(count: usize) -> u8 {
     }
 }
 
+/// Represents actions applied to a player profile that may require moderation or restrictions.
 #[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq)]
 #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum ProfileAction {
+    /// The player's name was forcibly changed by the server or an administrator.
     ForcedNameChange,
+    /// The player attempted to use a skin that is banned or not allowed on the server.
     UsingBannedSkin,
 }
 
+/// Represents the six possible block-facing directions in a 3D world.
 #[derive(Clone, Copy, PartialEq, Eq)]
 pub enum BlockDirection {
+    /// Points downward along the Y axis; often used for blocks attached to the ceiling.
     Down = 0,
+    /// Points upward along the Y axis; commonly used for blocks resting on the ground.
     Up,
+    /// Points toward the negative Z axis; typically toward the front of a structure.
     North,
+    /// Points toward the positive Z axis; typically toward the back of a structure.
     South,
+    /// Points toward the negative X axis; commonly used for left-facing orientation.
     West,
+    /// Points toward the positive X axis; commonly used for right-facing orientation.
     East,
 }
 
 impl BlockDirection {
+    /// Returns the principal axis (`X`, `Y`, or `Z`) associated with this direction.
     #[must_use]
     pub const fn get_axis(&self) -> Axis {
         match self {
@@ -114,14 +133,21 @@ impl BlockDirection {
     }
 }
 
-/// Takes a mutable reference of an index and returns a mutable "slice" where we can mutate both at
-/// the same time
+/// A mutable slice split into three parts: the element at the split index, the start, and the end.
+///
+/// This allows modifying the selected element while still having access to the surrounding slices.
 pub struct MutableSplitSlice<'a, T> {
+    /// Elements before the split index.
     start: &'a mut [T],
+    /// Elements after the split index.
     end: &'a mut [T],
 }
 
 impl<'a, T> MutableSplitSlice<'a, T> {
+    /// Extracts the `index`-th element as a mutable reference along with a `MutableSplitSlice` representing the remaining elements.
+    ///
+    /// # Panics
+    /// * if `index` is out of bounds of the base slice.
     pub const fn extract_ith(base: &'a mut [T], index: usize) -> (&'a mut T, Self) {
         let (start, end_inclusive) = base.split_at_mut(index);
         let (value, end) = end_inclusive
@@ -131,11 +157,13 @@ impl<'a, T> MutableSplitSlice<'a, T> {
         (value, Self { start, end })
     }
 
+    /// Returns the total number of elements in the split slice (start + removed element + end).
     #[must_use]
     pub const fn len(&self) -> usize {
         self.start.len() + self.end.len() + 1
     }
 
+    /// Returns `false` since the split slice always contains at least the removed element.
     #[must_use]
     pub const fn is_empty(&self) -> bool {
         false
@@ -157,10 +185,13 @@ impl<T> Index<usize> for MutableSplitSlice<'_, T> {
     }
 }
 
+/// Codec for deserializing parameters of a double Perlin noise sampler.
 #[derive(Deserialize, Clone)]
 pub struct DoublePerlinNoiseParametersCodec {
+    /// The first octave index (can be negative for lower frequencies).
     #[serde(rename = "firstOctave")]
     pub first_octave: i32,
+    /// Amplitude values for each octave, determining the weight of each frequency layer.
     pub amplitudes: Vec<f64>,
 }
 
@@ -193,11 +224,20 @@ impl Hand {
     }
 }
 
+/// Error type for invalid hand conversion.
 pub struct InvalidHand;
 
 impl TryFrom<i32> for Hand {
     type Error = InvalidHand;
 
+    /// Converts an integer into a `Hand`.
+    ///
+    /// # Parameters
+    /// - `0`: `Left`
+    /// - `1`: `Right`
+    ///
+    /// # Errors
+    /// Returns `InvalidHand` if the value is not 0 or 1.
     fn try_from(value: i32) -> Result<Self, Self::Error> {
         match value {
             0 => Ok(Self::Left),