kristoferssolo/hexlab
1
0
Fork 0
mirror of https://github.com/kristoferssolo/hexlab.git synced 2025-10-21 19:40:34 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: fix typos

Browse Source
This commit is contained in:
Kristofers Solo 2024-12-25 17:06:22 +02:00
parent 44dbbbbacf
commit dd6111dce3
2 changed files with 340 additions and 310 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
src/builder.rs
View File

@ -24,58 +24,60 @@ pub enum MazeBuilderError {
GenerationError(String), GenerationError(String),
} }
/// A builder pattern for creating hexagonal mazes. /**
/// A builder pattern for creating hexagonal mazes.
/// This struct provides a fluent interface for configuring and building hexagonal mazes.
/// It offers flexibility in specifying the maze size, random seed, and generation algorithm. This struct provides a fluent interface for configuring and building hexagonal mazes.
/// It offers flexibility in specifying the maze size, random seed, and generation algorithm.
/// # Examples
/// # Examples
/// Basic usage:
/// ```rust Basic usage:
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let maze = MazeBuilder::new()
/// .with_radius(5) let maze = MazeBuilder::new()
/// .build() .with_radius(5)
/// .expect("Failed to create maze"); .build()
/// .expect("Failed to create maze");
/// // A radius of 5 creates 61 hexagonal tiles
/// assert!(!maze.is_empty()); // A radius of 5 creates 61 hexagonal tiles
/// assert_eq!(maze.len(), 91); assert!(!maze.is_empty());
/// ``` assert_eq!(maze.len(), 91);
/// ```
/// Using a seed for reproducible results:
/// ```rust Using a seed for reproducible results:
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let maze1 = MazeBuilder::new()
/// .with_radius(3) let maze1 = MazeBuilder::new()
/// .with_seed(12345) .with_radius(3)
/// .build() .with_seed(12345)
/// .expect("Failed to create maze"); .build()
/// .expect("Failed to create maze");
/// let maze2 = MazeBuilder::new()
/// .with_radius(3) let maze2 = MazeBuilder::new()
/// .with_seed(12345) .with_radius(3)
/// .build() .with_seed(12345)
/// .expect("Failed to create maze"); .build()
/// .expect("Failed to create maze");
/// // Same seed should produce identical mazes
/// assert_eq!(maze1.len(), maze2.len()); // Same seed should produce identical mazes
/// assert_eq!(maze1, maze2); assert_eq!(maze1.len(), maze2.len());
/// ``` assert_eq!(maze1, maze2);
/// ```
/// Specifying a custom generator:
/// ```rust Specifying a custom generator:
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let maze = MazeBuilder::new()
/// .with_radius(7) let maze = MazeBuilder::new()
/// .with_generator(GeneratorType::RecursiveBacktracking) .with_radius(7)
/// .build() .with_generator(GeneratorType::RecursiveBacktracking)
/// .expect("Failed to create maze"); .build()
/// ``` .expect("Failed to create maze");
```
*/
#[allow(clippy::module_name_repetitions)] #[allow(clippy::module_name_repetitions)]
#[derive(Default)] #[derive(Default)]
pub struct MazeBuilder { pub struct MazeBuilder {
@ -138,31 +140,33 @@ impl MazeBuilder {
self self
} }
/// Builds the hexagonal maze based on the configured parameters. /**
/// Builds the hexagonal maze based on the configured parameters.
/// # Errors
/// # Errors
/// Returns [`MazeBuilderError::NoRadius`] if no radius is specified.
/// Returns [`MazeBuilderError::InvalidStartPosition`] if the start position is outside maze bounds. Returns [`MazeBuilderError::NoRadius`] if no radius is specified.
/// Returns [`MazeBuilderError::InvalidStartPosition`] if the start position is outside maze bounds.
/// # Examples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// // Should fail without radius
/// let result = MazeBuilder::new().build(); // Should fail without radius
/// assert!(result.is_err()); let result = MazeBuilder::new().build();
/// assert!(result.is_err());
/// // Should succeed with radius
/// let result = MazeBuilder::new() // Should succeed with radius
/// .with_radius(3) let result = MazeBuilder::new()
/// .build(); .with_radius(3)
/// assert!(result.is_ok()); .build();
/// assert!(result.is_ok());
/// let maze = result.unwrap();
/// assert!(!maze.is_empty()); let maze = result.unwrap();
/// ``` assert!(!maze.is_empty());
```
*/
pub fn build(self) -> Result<HexMaze, MazeBuilderError> { pub fn build(self) -> Result<HexMaze, MazeBuilderError> {
let radius = self.radius.ok_or(MazeBuilderError::NoRadius)?; let radius = self.radius.ok_or(MazeBuilderError::NoRadius)?;
let mut maze = create_hex_maze(radius); let mut maze = create_hex_maze(radius);

492
src/walls.rs
View File

@ -2,46 +2,48 @@
use bevy::prelude::*; use bevy::prelude::*;
use hexx::EdgeDirection; use hexx::EdgeDirection;
/// A bit-flag representation of walls in a hexagonal tile. /**
/// A bit-flag representation of walls in a hexagonal tile.
/// `Walls` uses an efficient bit-flag system to track the presence or absence of walls
/// along each edge of a hexagonal tile. Each of the six possible walls is represented `Walls` uses an efficient bit-flag system to track the presence or absence of walls
/// by a single bit in an 8-bit integer, allowing for fast operations and minimal memory usage. along each edge of a hexagonal tile. Each of the six possible walls is represented
/// by a single bit in an 8-bit integer, allowing for fast operations and minimal memory usage.
/// # Examples
/// # Examples
/// Creating and manipulating walls:
/// ```rust Creating and manipulating walls:
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// // Create a hexagon with all walls
/// let walls = Walls::new(); // Create a hexagon with all walls
/// assert!(walls.is_closed()); let walls = Walls::new();
/// assert!(walls.is_closed());
/// // Create a hexagon with no walls
/// let mut walls = Walls::empty(); // Create a hexagon with no walls
/// assert!(walls.is_empty()); let mut walls = Walls::empty();
/// assert!(walls.is_empty());
/// // Add specific walls
/// walls.add(EdgeDirection::FLAT_NORTH); // Add specific walls
/// walls.add(EdgeDirection::FLAT_SOUTH); walls.add(EdgeDirection::FLAT_NORTH);
/// assert_eq!(walls.count(), 2); walls.add(EdgeDirection::FLAT_SOUTH);
/// ``` assert_eq!(walls.count(), 2);
/// ```
/// Using walls in game logic:
/// Using walls in game logic:
/// ```rust
/// use hexlab::prelude::*; ```
/// let mut walls = Walls::empty(); use hexlab::prelude::*;
/// let mut walls = Walls::empty();
/// // Add walls to create a corner
/// walls.add(EdgeDirection::FLAT_NORTH); // Add walls to create a corner
/// walls.add(EdgeDirection::FLAT_SOUTH_EAST); walls.add(EdgeDirection::FLAT_NORTH);
/// walls.add(EdgeDirection::FLAT_SOUTH_EAST);
/// // Check if a specific direction has a wall
/// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); // Check if a specific direction has a wall
/// assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); assert!(walls.contains(EdgeDirection::FLAT_NORTH));
/// ``` assert!(!walls.contains(EdgeDirection::FLAT_SOUTH));
```
*/
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "bevy_reflect", derive(Reflect))] #[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
#[cfg_attr(feature = "bevy", derive(Component))] #[cfg_attr(feature = "bevy", derive(Component))]
@ -50,81 +52,89 @@ use hexx::EdgeDirection;
pub struct Walls(u8); pub struct Walls(u8);
impl Walls { impl Walls {
/// Creates a new set of walls with all edges closed. /**
/// Creates a new set of walls with all edges closed.
/// This is the default state where all six edges of the hexagon have walls.
/// This is the default state where all six edges of the hexagon have walls.
/// # Examples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let walls = Walls::new();
/// assert!(walls.is_closed()); let walls = Walls::new();
/// assert_eq!(walls.count(), 6); assert!(walls.is_closed());
/// ``` assert_eq!(walls.count(), 6);
```
*/
#[inline] #[inline]
#[must_use] #[must_use]
pub fn new() -> Self { pub fn new() -> Self {
Self::default() Self::default()
} }
/// Creates a new set of walls with no edges (completely open). /**
/// Creates a new set of walls with no edges (completely open).
/// # Examples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let walls = Walls::empty();
/// assert!(walls.is_empty()); let walls = Walls::empty();
/// assert_eq!(walls.count(), 0); assert!(walls.is_empty());
/// ``` assert_eq!(walls.count(), 0);
```
*/
#[inline] #[inline]
#[must_use] #[must_use]
pub const fn empty() -> Self { pub const fn empty() -> Self {
Self(0) Self(0)
} }
/// Checks if the walls are currently empty /**
/// Checks if the walls are currently empty
/// Returns `true` if all directions have no walls set.
/// # Examples Returns `true` if all directions have no walls set.
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let walls = Walls::empty();
/// assert!(walls.is_empty()); let walls = Walls::empty();
/// assert!(walls.is_empty());
/// let walls = Walls::new();
/// assert!(!walls.is_empty()); let walls = Walls::new();
/// ``` assert!(!walls.is_empty());
```
*/
#[inline] #[inline]
#[must_use] #[must_use]
pub const fn is_empty(&self) -> bool { pub const fn is_empty(&self) -> bool {
self.0 == 0 self.0 == 0
} }
/// Adds a wall in the specified direction /**
/// Adds a wall in the specified direction
/// This method uses bitwise operations to efficiently set the wall flag
/// for the given direction. Multiple walls can be added to the same hexagon. This method uses bitwise operations to efficiently set the wall flag
/// for the given direction. Multiple walls can be added to the same hexagon.
/// # Examples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let mut walls = Walls::empty();
/// walls.add(EdgeDirection::FLAT_NORTH); let mut walls = Walls::empty();
/// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); walls.add(EdgeDirection::FLAT_NORTH);
/// assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); assert!(walls.contains(EdgeDirection::FLAT_NORTH));
/// assert!(!walls.contains(EdgeDirection::FLAT_SOUTH));
/// walls.add(EdgeDirection::FLAT_SOUTH);
/// assert!(walls.contains(EdgeDirection::FLAT_SOUTH)); walls.add(EdgeDirection::FLAT_SOUTH);
/// assert_eq!(walls.count(), 2); assert!(walls.contains(EdgeDirection::FLAT_SOUTH));
/// ``` assert_eq!(walls.count(), 2);
```
*/
#[inline] #[inline]
pub fn add<T>(&mut self, direction: T) pub fn add<T>(&mut self, direction: T)
where where
@ -133,23 +143,25 @@ impl Walls {
self.0 |= direction.into().0; self.0 |= direction.into().0;
} }
/// Removes a wall in the specified direction /**
/// Removes a wall in the specified direction
/// Returns `true` if a wall was actually removed, `false` if there was no wall
/// in the specified direction. Returns `true` if a wall was actually removed, `false` if there was no wall
/// in the specified direction.
/// # Exmaples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let mut walls = Walls::new();
/// assert!(walls.remove(EdgeDirection::FLAT_NORTH)); let mut walls = Walls::new();
/// assert!(!walls.contains(EdgeDirection::FLAT_NORTH)); assert!(walls.remove(EdgeDirection::FLAT_NORTH));
/// assert!(!walls.contains(EdgeDirection::FLAT_NORTH));
/// // Removing a non-existent wall returns false
/// assert!(!walls.remove(EdgeDirection::FLAT_NORTH)); // Removing a non-existent wall returns false
/// ``` assert!(!walls.remove(EdgeDirection::FLAT_NORTH));
```
*/
#[inline] #[inline]
pub fn remove<T>(&mut self, direction: T) -> bool pub fn remove<T>(&mut self, direction: T) -> bool
where where
@ -162,21 +174,23 @@ impl Walls {
was_removed was_removed
} }
/// Returns true if there is a wall in the specified direction /**
/// Returns true if there is a wall in the specified direction
/// Uses efficient bitwise operations to check for the presence of a wall.
/// Uses efficient bitwise operations to check for the presence of a wall.
/// # Exmaples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let mut walls = Walls::empty();
/// let mut walls = Walls::empty();
/// walls.add(EdgeDirection::FLAT_NORTH);
/// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); walls.add(EdgeDirection::FLAT_NORTH);
/// assert!(!walls.contains(EdgeDirection::FLAT_SOUTH)); assert!(walls.contains(EdgeDirection::FLAT_NORTH));
/// ``` assert!(!walls.contains(EdgeDirection::FLAT_SOUTH));
```
*/
#[inline] #[inline]
pub fn contains<T>(&self, other: T) -> bool pub fn contains<T>(&self, other: T) -> bool
where where
@ -185,90 +199,98 @@ impl Walls {
self.0 & other.into().0 != 0 self.0 & other.into().0 != 0
} }
/// Returns the raw bit representation of the walls /**
/// Returns the raw bit representation of the walls
/// This method provides access to the underlying bit flags for advanced usage.
/// The bits are ordered according to the `EdgeDirection` indices. This method provides access to the underlying bit flags for advanced usage.
/// The bits are ordered according to the `EdgeDirection` indices.
/// # Exmaples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let mut walls = Walls::new();
/// let mut walls = Walls::new();
/// assert_eq!(walls.as_bits(), 0b111111);
/// ``` assert_eq!(walls.as_bits(), 0b111111);
```
*/
#[inline] #[inline]
#[must_use] #[must_use]
pub const fn as_bits(&self) -> u8 { pub const fn as_bits(&self) -> u8 {
self.0 self.0
} }
/// Returns the total number of walls present /**
/// Returns the total number of walls present
/// Efficiently counts the number of set bits in the internal representation.
/// Efficiently counts the number of set bits in the internal representation.
/// # Exmaples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let mut walls = Walls::empty();
/// let mut walls = Walls::empty();
/// assert_eq!(walls.count(), 0);
/// assert_eq!(walls.count(), 0);
/// walls.add(EdgeDirection::FLAT_NORTH);
/// walls.add(EdgeDirection::FLAT_SOUTH); walls.add(EdgeDirection::FLAT_NORTH);
/// assert_eq!(walls.count(), 2); walls.add(EdgeDirection::FLAT_SOUTH);
/// ``` assert_eq!(walls.count(), 2);
```
*/
#[inline] #[inline]
#[must_use] #[must_use]
pub fn count(&self) -> u8 { pub fn count(&self) -> u8 {
u8::try_from(self.0.count_ones()).unwrap_or_default() u8::try_from(self.0.count_ones()).unwrap_or_default()
} }
/// Returns all possible directions as a `Walls` value /**
/// Returns all possible directions as a `Walls` value
/// This represents a hexagon with walls in all six directions.
/// This represents a hexagon with walls in all six directions.
/// # Exmaples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let all_walls = Walls::all_directions();
/// let all_walls = Walls::all_directions();
/// assert_eq!(all_walls.count(), 6);
/// assert!(all_walls.is_closed()); assert_eq!(all_walls.count(), 6);
/// ``` assert!(all_walls.is_closed());
```
*/
#[inline] #[inline]
#[must_use] #[must_use]
pub const fn all_directions() -> Self { pub const fn all_directions() -> Self {
Self(0b11_1111) Self(0b11_1111)
} }
/// Toggles a wall in the specified direction. /**
/// Toggles a wall in the specified direction.
/// If a wall exists in the given direction, it will be removed.
/// If no wall exists, one will be added. If a wall exists in the given direction, it will be removed.
/// Returns the previous state (`true` if a wall was present). If no wall exists, one will be added.
/// Returns the previous state (`true` if a wall was present).
/// # Examples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let mut walls = Walls::empty();
/// let mut walls = Walls::empty();
/// assert!(!walls.toggle(EdgeDirection::FLAT_NORTH)); // Returns false, wall was not present
/// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); // Wall is now present assert!(!walls.toggle(EdgeDirection::FLAT_NORTH)); // Returns false, wall was not present
/// assert!(walls.contains(EdgeDirection::FLAT_NORTH)); // Wall is now present
/// let mut walls = Walls::new();
/// let mut walls = Walls::new();
/// assert!(walls.toggle(EdgeDirection::FLAT_NORTH)); // Returns true, wall was present
/// assert!(!walls.contains(EdgeDirection::FLAT_NORTH)); // Wall is now removed assert!(walls.toggle(EdgeDirection::FLAT_NORTH)); // Returns true, wall was present
/// ``` assert!(!walls.contains(EdgeDirection::FLAT_NORTH)); // Wall is now removed
```
*/
pub fn toggle<T>(&mut self, direction: T) -> bool pub fn toggle<T>(&mut self, direction: T) -> bool
where where
T: Into<Self> + Copy, T: Into<Self> + Copy,
@ -282,50 +304,54 @@ impl Walls {
is_present is_present
} }
/// Checks if walls are present in all six directions. /**
/// Checks if walls are present in all six directions.
/// Returns `true` if the hexagon has all possible walls, making it completely enclosed.
/// Returns `true` if the hexagon has all possible walls, making it completely enclosed.
/// # Examples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let walls = Walls::new();
/// assert!(walls.is_closed()); let walls = Walls::new();
/// assert!(walls.is_closed());
/// let mut walls = Walls::empty();
/// assert!(!walls.is_closed()); let mut walls = Walls::empty();
/// // Add all walls manually assert!(!walls.is_closed());
/// for direction in EdgeDirection::iter() { // Add all walls manually
/// walls.add(direction); for direction in EdgeDirection::iter() {
/// } walls.add(direction);
/// assert!(walls.is_closed()); }
/// ``` assert!(walls.is_closed());
```
*/
#[inline] #[inline]
#[must_use] #[must_use]
pub fn is_closed(&self) -> bool { pub fn is_closed(&self) -> bool {
self.count() == 6 self.count() == 6
} }
/// Sets walls for multiple directions at once. /**
/// Sets walls for multiple directions at once.
/// This method efficiently adds multiple walls in a single operation while
/// preserving any existing walls not specified in the input. This method efficiently adds multiple walls in a single operation while
/// preserving any existing walls not specified in the input.
/// # Examples
/// # Examples
/// ```rust
/// use hexlab::prelude::*; ```
/// use hexlab::prelude::*;
/// let mut walls = Walls::empty();
/// walls.add(EdgeDirection::FLAT_NORTH); let mut walls = Walls::empty();
/// walls.add(EdgeDirection::FLAT_NORTH);
/// walls.fill([EdgeDirection::FLAT_SOUTH, EdgeDirection::FLAT_SOUTH_EAST]);
/// walls.fill([EdgeDirection::FLAT_SOUTH, EdgeDirection::FLAT_SOUTH_EAST]);
/// assert!(walls.contains(EdgeDirection::FLAT_SOUTH));
/// assert_eq!(walls.count(), 3); assert!(walls.contains(EdgeDirection::FLAT_SOUTH));
/// ``` assert_eq!(walls.count(), 3);
```
*/
#[inline] #[inline]
pub fn fill<T>(&mut self, other: T) pub fn fill<T>(&mut self, other: T)
where where