Hexx

https://docs.rs/hexx/latest/
Admin
Hexx is a Rust library for hexagonal grid manipulation, providing tools for coordinates, map...
Tokens:77,254
Snippets:679
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure UVOptions

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.UVOptions.html

Example showing how to initialize and chain configuration methods for UVOptions.

```rust
let options = UVOptions::new()
    .with_offset(vec2(1.0, 0.5))
    .flip_u()
    .with_scale_factor(vec2(1.0, 2.0));
```

--------------------------------

### Customize MeshInfo

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.MeshInfo.html

Example of building and transforming a hexagonal column mesh.

```rust
let layout = HexLayout::default();
// Build the mesh info
let info: MeshInfo = ColumnMeshBuilder::new(&layout, 2.0).build();
// Customize the generated mesh
let info = info
    .rotated(Quat::IDENTITY)
    .with_offset(Vec3::new(12.0, 34.2, -43.54));
```

--------------------------------

### Perform coordinate conversion with HexLayout

Source: https://docs.rs/hexx/latest/hexx/layout/struct.HexLayout.html

Example showing how to initialize a HexLayout and convert between hex and world coordinates.

```rust
let layout = HexLayout {
    // We want flat topped hexagons
    orientation: HexOrientation::Flat,
    // We define the world space origin equivalent of `Hex::ZERO` in hex space
    origin: Vec2::new(1.0, 2.0),
    // We define the world space scale of the hexagons
    scale: Vec2::new(1.0, 1.0),
};
// You can now find the world positon (center) of any given hexagon
let world_pos = layout.hex_to_world_pos(Hex::ZERO);
// You can also find which hexagon is at a given world/screen position
let hex_pos = layout.world_pos_to_hex(Vec2::new(1.23, 45.678));
```

--------------------------------

### a_star(start, end, cost)

Source: https://docs.rs/hexx/latest/hexx/algorithms/fn.a_star.html

Performs A* pathfinding between a start and end coordinate on a hexagonal grid. The cost function determines the weight of moving to a specific coordinate, where None indicates an impassable tile.

```APIDOC
## fn a_star

### Description
Performs A* pathfinding between `start` and `end` coordinates. The function automatically handles heuristics based on the distance between the two points.

### Signature
`pub fn a_star(start: Hex, end: Hex, cost: impl Fn(Hex, Hex) -> Option<u32>) -> Option<Vec<Hex>>`

### Parameters
- **start** (Hex) - The starting coordinate.
- **end** (Hex) - The destination coordinate.
- **cost** (Fn(Hex, Hex) -> Option<u32>) - A function that takes a node pair (from, to) and returns the cost to move to the destination node. Return `None` if the coordinate is impassable.

### Returns
- **Option<Vec<Hex>>** - An optional vector containing the path of coordinates from start to end, or `None` if no path exists.

### Example
```rust
use hexx::algorithms::a_star;

let start = hex(0, 0);
let end = hex(10, 0);
let path = a_star(start, end, |_, b| {
    Some(1) // Simple cost of 1 for all tiles
});
```
```

--------------------------------

### EdgeDirection Operations Example

Source: https://docs.rs/hexx/latest/hexx/direction/struct.EdgeDirection.html

Demonstrates negation and bitwise rotation operators for EdgeDirection instances.

```rust
let direction = EdgeDirection::FLAT_TOP;
assert_eq!(-direction, EdgeDirection::FLAT_BOTTOM);
assert_eq!(direction >> 1, EdgeDirection::FLAT_TOP_RIGHT);
assert_eq!(direction << 1, EdgeDirection::FLAT_TOP_LEFT);
```

--------------------------------

### VertexDirection Operations Example

Source: https://docs.rs/hexx/latest/hexx/direction/struct.VertexDirection.html

Demonstrates rotating and negating vertex directions using operators and methods.

```rust
let direction = VertexDirection::FLAT_RIGHT;
assert_eq!(-direction, VertexDirection::FLAT_LEFT);
assert_eq!(direction >> 1, VertexDirection::FLAT_BOTTOM_RIGHT);
assert_eq!(direction << 1, VertexDirection::FLAT_TOP_RIGHT);
```

--------------------------------

### ColumnMeshBuilder Usage

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.ColumnMeshBuilder.html

Example demonstrating how to initialize and configure a ColumnMeshBuilder to generate a custom hexagonal column mesh.

```APIDOC
## ColumnMeshBuilder Usage

### Description
This builder allows for the customization of hex column mesh generation, including setting the layout, height, position, and various transformation options like scale and rotation.

### Example
```rust
let layout = HexLayout::default();
let mesh = ColumnMeshBuilder::new(&layout, 15.0)
    .at(hex(2, 3))
    .facing(Vec3::Z)
    .with_subdivisions(5)
    .with_offset(Vec3::new(1.2, 3.45, 6.7))
    .without_bottom_face()
    .without_top_face()
    .build();
```
```

--------------------------------

### Generating a Heightmap Mesh

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.HeightMapMeshBuilder.html

Example usage of the builder to construct a mesh with specific offsets, height ranges, and face configurations.

```rust
let map: HashMap<Hex, f32> = [
    (hex(0, 0), 0.0),
    (hex(1, 0), 2.0),
    // ...
]
.into();
let layout = HexLayout::default();
let mesh = HeightMapMeshBuilder::new(&layout, &map)
    .with_offset(Vec3::new(1.2, 3.45, 6.7))
    .with_height_range(0.0..=5.0)
    .without_top_face()
    .build();
```

--------------------------------

### a_star(start: Hex, end: Hex, cost: impl Fn(Hex, Hex) -> Option<u32>) -> Option<Vec<Hex>>

Source: https://docs.rs/hexx/latest/src/hexx/algorithms/pathfinding.rs.html

Performs A* pathfinding between a start and end coordinate. The cost function determines the cost of moving between two nodes; returning None indicates the coordinate is impassable.

```APIDOC
## Function: a_star

### Description
Performs A* pathfinding between `start` and `end` coordinates. The `cost` closure defines the traversal cost between two hexes, allowing for dynamic pathfinding constraints like forbidden tiles or terrain costs.

### Signature
`pub fn a_star(start: Hex, end: Hex, cost: impl Fn(Hex, Hex) -> Option<u32>) -> Option<Vec<Hex>>`

### Parameters
- **start** (Hex) - The starting coordinate.
- **end** (Hex) - The destination coordinate.
- **cost** (Fn(Hex, Hex) -> Option<u32>) - A closure that takes the current hex and the neighbor hex, returning `Some(cost)` to traverse or `None` if the path is blocked.

### Returns
- **Option<Vec<Hex>>** - Returns `Some(Vec<Hex>)` containing the path from start to end if a path exists, otherwise `None`.
```

--------------------------------

### Cache Custom Rings

Source: https://docs.rs/hexx/latest/src/hexx/hex/rings.rs.html

Pre-compute custom rings with specific starting directions and rotation.

```rust
# use hexx::*;

// We cache 10 rings around the origin
let cache = Hex::ORIGIN.cached_custom_rings::<10>(EdgeDirection::FLAT_TOP, true);
// We have our target center
let target = Hex::new(11, 24);
// We retrieve the ring of range 5 and offset it to match the target
let five_ring = cache[5].iter().map(|h| *h + target);
```

--------------------------------

### Generate a Hexagonal Column Mesh

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.ColumnMeshBuilder.html

Example usage of the builder pattern to configure and build a custom hexagonal column mesh.

```rust
let layout = HexLayout::default();
let mesh = ColumnMeshBuilder::new(&layout, 15.0)
    .at(hex(2, 3))
    .facing(Vec3::Z)
    .with_subdivisions(5)
    .with_offset(Vec3::new(1.2, 3.45, 6.7))
    .without_bottom_face()
    .without_top_face()
    .build();
```

--------------------------------

### rombus(point: Hex, rows: u32, columns: u32)

Source: https://docs.rs/hexx/latest/hexx/shapes/fn.rombus.html

Generates a Rombus from a starting point with a specified number of rows and columns.

```APIDOC
## Function: rombus

### Description
Generates a Rombus from `point` of `rows` in y and `columns` in `x`.

### Signature
`pub fn rombus(point: Hex, rows: u32, columns: u32) -> impl ExactSizeIterator<Item = Hex>`

### Parameters
- **point** (Hex) - The starting coordinate for the rhombus.
- **rows** (u32) - The number of rows in the y-axis.
- **columns** (u32) - The number of columns in the x-axis.

### Returns
- **impl ExactSizeIterator<Item = Hex>** - An iterator over the hexagons forming the rhombus.
```

--------------------------------

### Initialize and build a RectMap

Source: https://docs.rs/hexx/latest/hexx/storage/struct.RectMetadata.html

Demonstrates configuring a RectMetadata instance with size, orientation, and wrapping strategies before building a default map.

```rust
let rect_hex_map = RectMetadata::from_half_size(UVec2::new(8, 12))
    .with_orientation(HexOrientation::Pointy)
    .with_offset_mode(OffsetHexMode::Odd)
    .with_wrap_strategies([WrapStrategy::Cycle, WrapStrategy::Clamp])
    .build_default::<i32>();
let hex = Hex::new(0, 0);

assert_eq!(rect_hex_map.get(hex), Some(&0_i32));
assert_eq!(rect_hex_map.wrapped_get(hex), &0_i32);
```

--------------------------------

### Rotate VertexDirection

Source: https://docs.rs/hexx/latest/hexx/struct.VertexDirection.html

Examples of rotating a vertex direction counter-clockwise or clockwise.

```rust
assert_eq!(
    VertexDirection::X.counter_clockwise(),
    VertexDirection::NEG_Y
);
```

```rust
assert_eq!(VertexDirection::X, VertexDirection::X.rotate_ccw(6));
```

```rust
assert_eq!(VertexDirection::X, VertexDirection::X.rotate_cw(6));
```

--------------------------------

### Initialize a RectMap

Source: https://docs.rs/hexx/latest/hexx/storage/struct.RectMap.html

Demonstrates creating a RectMap using RectMetadata with specific orientation and wrap strategies.

```rust
use hexx::{
    storage::{HexStore, RectMap, RectMetadata, WrapStrategy},
    *,
};

let rect_map = RectMetadata::from_half_size(UVec2 { x: 8, y: 4 })
    .with_orientation(HexOrientation::Pointy)
    .with_wrap_strategies([WrapStrategy::Cycle, WrapStrategy::Clamp])
    .build_default::<i32>();

assert_eq!(rect_map.get(Hex::new(0, 0)), Some(&0));
```

--------------------------------

### Configure HexLayout using the builder pattern

Source: https://docs.rs/hexx/latest/hexx/layout/struct.HexLayout.html

Demonstrates using the builder pattern to configure layout properties and axis inversion.

```rust
let mut layout = HexLayout::flat()
    .with_scale(Vec2::new(2.0, 3.0)) // Individual Hexagon size
    .with_origin(Vec2::new(-1.0, 0.0)); // World origin
// Invert the x axis, which will now go left. Will change `scale.x` to `-2.0`
layout.invert_x();
// Invert the y axis, which will now go down. Will change `scale.y` to `-3.0`
layout.invert_y();
```

--------------------------------

### Customize MeshInfo

Source: https://docs.rs/hexx/latest/src/hexx/mesh/mod.rs.html

Demonstrates how to build a mesh using ColumnMeshBuilder and apply transformations like rotation and offset.

```rust
# use hexx::*;

let layout = HexLayout::default();
// Build the mesh info
let info: MeshInfo = ColumnMeshBuilder::new(&layout, 2.0).build();
// Customize the generated mesh
let info = info
    .rotated(Quat::IDENTITY)
    .with_offset(Vec3::new(12.0, 34.2, -43.54));
```

--------------------------------

### FaceOptions::new

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.FaceOptions.html

Creates a new instance of FaceOptions with default values.

```APIDOC
## pub const fn new() -> Self

### Description
Generates a new FaceOptions instance with default quad options.

### Signature
`pub const fn new() -> Self`
```

--------------------------------

### field_of_movement

Source: https://docs.rs/hexx/latest/hexx/algorithms/fn.field_of_movement.html

Computes a field of movement around a starting coordinate given a budget and a cost function.

```APIDOC
## fn field_of_movement(coord: Hex, budget: u32, cost: impl Fn(Hex) -> Option<u32>) -> HashSet<Hex>

### Description
Computes a field of movement around `coord` given a `budget`. This algorithm takes a `cost` function, which calculates and returns the cost of movement through a given `Hex` tile. A tile that returns a computable cost would return `Some(cost)`, whereas `None` should be returned for tiles that cannot be moved through. The algorithm adds `+ 1` to the computed cost to ensure a minimum movement cost of 1 per tile.

### Parameters
- **coord** (Hex) - The starting coordinate.
- **budget** (u32) - The total movement budget available.
- **cost** (impl Fn(Hex) -> Option<u32>) - A closure that returns the cost of moving through a specific `Hex` tile, or `None` if the tile is impassable.

### Returns
- **HashSet<Hex>** - A set of all reachable `Hex` coordinates within the given budget.
```

--------------------------------

### RectMetadata Build Methods

Source: https://docs.rs/hexx/latest/src/hexx/storage/rect.rs.html

Methods to finalize the configuration and construct a RectMap.

```APIDOC
## RectMetadata Build Operations

### build<T>(values: impl FnMut(Hex) -> T) -> RectMap<T>
Constructs a RectMap by evaluating a function for each hex coordinate.

### build_parallel<T, F>(values: F) -> RectMap<T>
Constructs a RectMap using parallel processing (requires 'rayon' feature).

### build_default<T>() -> RectMap<T>
Constructs a RectMap where all cells are initialized with their default values.
```

--------------------------------

### Retrieve Custom Hex Rings

Source: https://docs.rs/hexx/latest/hexx/hex/struct.Hex.html

Retrieves a sequence of Hex rings with custom starting direction and rotation.

```rust
let rings: Vec<Vec<Hex>> = Hex::ZERO
    .custom_rings(3..10, EdgeDirection::FLAT_TOP, true)
    .collect();
assert_eq!(rings.len(), 7);
```

--------------------------------

### Compute A* with biome costs

Source: https://docs.rs/hexx/latest/hexx/algorithms/fn.a_star.html

Demonstrates pathfinding using a custom biome-based cost function where different terrain types have varying movement costs or are impassable.

```rust
use hexx::algorithms::a_star;

enum Biome {
    Mountain,
    Plains,
    Forest,
    Desert,
}

impl Biome {
    pub fn cost(&self) -> Option<u32> {
        match self {
            Self::Mountain => None, // Moutains are not included in pathfinding
            Self::Plains => Some(0),
            Self::Forest => Some(1),
            Self::Desert => Some(2),
        }
    }
}

let start = hex(0, 0);
let end = hex(10, 0);
let mut biomes: HashMap<Hex, Biome> = HashMap::new();
// Set coordinate biomes
// biomes.insert(hex(1, 2), Biome::Mountain);
// ..
let path = a_star(start, end, |_, b| {
    biomes.get(&b).and_then(|biome| biome.cost())
});
```

--------------------------------

### custom_spiral_range

Source: https://docs.rs/hexx/latest/src/hexx/hex/rings.rs.html

Generates an iterator of hexagonal coordinates forming a spiral pattern based on a custom range, starting direction, and rotation.

```APIDOC
## custom_spiral_range

### Description
Retrieves all Hex coordinates around the current hex in a given range, ordered as successive rings starting from a specified direction and rotation.

### Parameters
- **range** (impl Iterator<Item = u32>) - Required - The sequence of ring distances to include.
- **start_dir** (EdgeDirection) - Required - The starting direction for the spiral.
- **clockwise** (bool) - Required - If true, the spiral loops clockwise; otherwise, it loops counter-clockwise.

### Returns
- **Iterator<Item = Self>** - An iterator yielding the hexagonal coordinates in the spiral sequence.
```

--------------------------------

### Quad::new

Source: https://docs.rs/hexx/latest/hexx/mesh/face/type.Quad.html

Constructs a regular quad from two 2D positions and height values.

```APIDOC
## pub fn new([left, right]: [Vec2; 2], bottom_height: f32, top_height: f32) -> Self

### Description
Construct a regular quad from two [left, right] 2d positions for x and z and a bottom_height and top_height for y.

### Arguments
- **[left, right]** ([Vec2; 2]) - The two bottom 2d vertex positions
- **bottom_height** (f32) - The bottom vertices Y value
- **top_height** (f32) - The top vertices Y value
```

--------------------------------

### Cache custom rings

Source: https://docs.rs/hexx/latest/hexx/hex/struct.Hex.html

Pre-compute rings around a coordinate with a custom start direction and rotation, then offset them to a target center.

```rust

// We cache 10 rings around the origin
let cache = Hex::ORIGIN.cached_custom_rings::<10>(EdgeDirection::FLAT_TOP, true);
// We have our target center
let target = Hex::new(11, 24);
// We retrieve the ring of range 5 and offset it to match the target
let five_ring = cache[5].iter().map(|h| *h + target);
```

--------------------------------

### Quad::new

Source: https://docs.rs/hexx/latest/src/hexx/mesh/face.rs.html

Constructs a regular quad face from two 2D positions and height bounds.

```APIDOC
## fn new([left, right]: [Vec2; 2], bottom_height: f32, top_height: f32) -> Self

### Description
Construct a regular quad from two [left, right] 2d positions for x and z and a bottom_height and top_height for y.

### Parameters
- **[left, right]** ([Vec2; 2]) - The two bottom 2d vertex positions.
- **bottom_height** (f32) - The bottom vertices Y value.
- **top_height** (f32) - The top vertices Y value.
```

--------------------------------

### Compute field of movement with custom biome costs

Source: https://docs.rs/hexx/latest/src/hexx/algorithms/field_of_movement.rs.html

Demonstrates how to use a closure to define traversal costs for different terrain types, where None represents impassable tiles.

```rust
# use hexx::*;
# use std::collections::HashMap;
use hexx::algorithms::field_of_movement;

enum Biome {
    Mountain,
    Plains,
    Forest,
    Desert,
}

impl Biome {
    pub fn cost(&self) -> Option<u32> {
        match self {
            Self::Mountain => None, // Moutains cannot be traversed
            Self::Plains => Some(0),
            Self::Forest => Some(1),
            Self::Desert => Some(2),
        }
    }
}

let start = hex(0, 0);
let movement_budget = 5u32;
let mut biomes: HashMap<Hex, Biome> = HashMap::new();
// Set coordinate biomes
// biomes.insert(hex(1, 2), Biome::Mountain);
// ..
let reachable_tiles = field_of_movement(start, movement_budget, |h| {
    biomes.get(&h).and_then(|b| b.cost())
});
```

--------------------------------

### Coordinate Conversion Tests

Source: https://docs.rs/hexx/latest/src/hexx/storage/rect.rs.html

Validates the consistency between index, hexagonal, and offset coordinate systems across various start and end bounds.

```rust
const START_END: &[([i32; 2], [i32; 2])] = &[
    ([0, 0], [0, 0]),
    ([0, 0], [1, 1]),
    ([-1, -1], [1, 1]),
    ([-10, -10], [10, 10]),
    ([-10, -10], [15, 15]),
    ([0, 0], [15, 15]),
    ([0, 0], [-30, -30]),
    ([-17, -13], [31, 41]),
    ([-64, -64], [64, 64]),
];

#[test]
fn idx_hex_test() {
    for (start, end) in START_END {
        let rect_map =
            RectMetadata::from_start_end((*start).into(), (*end).into()).build_default::<i32>();

        for idx in 0..rect_map.len() {
            let hex = rect_map.idx_to_hex(idx);
            assert!(rect_map.contains_hex(hex));
            let ij = rect_map.hex_to_offset(hex);
            assert!(rect_map.contains_offset(ij));
            assert_eq!(Some(idx), rect_map.hex_to_idx(hex));
        }
        assert_eq!(rect_map.iter().count(), rect_map.len());
    }
}
```

--------------------------------

### Create RectMap with custom values

Source: https://docs.rs/hexx/latest/hexx/storage/struct.RectMap.html

Initializes a RectMap by providing a closure to define values for each coordinate.

```rust

let meta = RectMetadata::from_half_size(UVec2 { x: 8, y: 4 })
    .with_orientation(HexOrientation::Pointy)
    .with_wrap_strategies([WrapStrategy::Cycle, WrapStrategy::Clamp]);
let rect_map = RectMap::new(meta, |hex| hex.x + hex.y);

assert_eq!(rect_map.get(Hex::new(0, 0)), Some(&0));
```

--------------------------------

### Face::new

Source: https://docs.rs/hexx/latest/hexx/mesh/face/struct.Face.html

Constructs a regular quad face from two 2D positions and height values.

```APIDOC
## Face::new([left, right]: [Vec2; 2], bottom_height: f32, top_height: f32) -> Self

### Description
Construct a regular quad from two [left, right] 2d positions for x and z and a bottom_height and top_height for y.

### Parameters
- **[left, right]** ([Vec2; 2]) - Required - The two bottom 2d vertex positions
- **bottom_height** (f32) - Required - The bottom vertices Y value
- **top_height** (f32) - Required - The top vertices Y value
```

--------------------------------

### rombus(point: Hex, rows: u32, columns: u32)

Source: https://docs.rs/hexx/latest/src/hexx/shapes.rs.html

Generates an iterator of Hex coordinates forming a rhombus shape starting from a given point.

```APIDOC
## fn rombus(point: Hex, rows: u32, columns: u32)

### Description
Generates a Rombus from `point` of `rows` in y and `columns` in `x`.

### Parameters
- **point** (Hex) - The starting origin coordinate.
- **rows** (u32) - The number of rows.
- **columns** (u32) - The number of columns.

### Returns
- **impl ExactSizeIterator<Item = Hex>** - An iterator yielding the coordinates within the rhombus shape.
```

--------------------------------

### Compute field of view with range_fov

Source: https://docs.rs/hexx/latest/hexx/algorithms/fn.range_fov.html

Calculates visible tiles from a starting coordinate, using a closure to identify blocking tiles that obstruct the field of view.

```rust
use hexx::algorithms::range_fov;

let pos = hex(0, 0);
let range = 10;
let blocking_coords: HashSet<Hex> = HashSet::new();
// Add blocking coordinates
// blocking_coords.insert(hex(2, 0));
// ..
let fov = range_fov(pos, range, |h| blocking_coords.contains(&h));
```

--------------------------------

### Compute A* with forbidden tiles

Source: https://docs.rs/hexx/latest/hexx/algorithms/fn.a_star.html

Demonstrates pathfinding with a simple cost function that treats forbidden coordinates as impassable.

```rust
use hexx::algorithms::a_star;

let start = hex(0, 0);
let end = hex(10, 0);
let forbidden_coords: HashSet<Hex> = HashSet::new();
// Add forbidden coordinates
// forbidden_coords.insert(hex(2, 0));
// ..
let path = a_star(start, end, |_, b| {
    (!forbidden_coords.contains(&b)).then_some(0)
});
```

--------------------------------

### UV Rect Initialization and Remapping

Source: https://docs.rs/hexx/latest/src/hexx/mesh/uv_mapping.rs.html

Defines a default UV rectangle and provides a method to remap normalized 0.0-1.0 coordinates into the rectangle's bounds.

```rust
pub(crate) const fn new_uv() -> Self {
        Self {
            min: Vec2::ZERO,
            max: Vec2::ONE,
        }
    }
    /// Remaps `value` (0.0..1.0) to the rect
    #[inline]
    #[must_use]
    pub(crate) fn remap(&self, value: Vec2) -> Vec2 {
        Vec2::new(
            remap(value.x, self.min.x, self.max.x),
            remap(value.y, self.min.y, self.max.y),
        )
    }
}

impl Default for Rect {
    fn default() -> Self {
        Self::new_uv()
    }
}
```

--------------------------------

### Generate a Heightmap Mesh

Source: https://docs.rs/hexx/latest/src/hexx/mesh/heightmap_builder.rs.html

Demonstrates how to initialize and configure a HeightMapMeshBuilder to generate a mesh from a hexagonal map.

```rust
# use hexx::*;
# use std::collections::HashMap;

let map: HashMap<Hex, f32> = [
    (hex(0, 0), 0.0),
    (hex(1, 0), 2.0),
    // ...
]
.into();
let layout = HexLayout::default();
let mesh = HeightMapMeshBuilder::new(&layout, &map)
    .with_offset(Vec3::new(1.2, 3.45, 6.7))
    .with_height_range(0.0..=5.0)
    .without_top_face()
    .build();
```

--------------------------------

### HeightMapMeshBuilder::new

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.HeightMapMeshBuilder.html

Initializes a new builder instance with a hexagonal layout and height map.

```APIDOC
## pub const fn new(layout: &'l HexLayout, map: &'m HeightMap) -> Self

### Description
Setup a new builder using the given layout and height map.

### Parameters
- **layout** (&'l HexLayout) - Required - The associated hexagonal horizontal layout.
- **map** (&'m HeightMap) - Required - The heightmap values (supports HexagonalMap<f32>, RombusMap<f32>, or HashMap<Hex, f32>).
```

--------------------------------

### Center the mesh pivot with with_offset

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.ColumnMeshBuilder.html

Demonstrates how to center the pivot of a hexagonal column mesh by applying an offset equal to half its height.

```rust
let layout = HexLayout::default();
let height = 10.0;
let mesh = ColumnMeshBuilder::new(&layout, height)
    .with_offset(Vec3::new(0.0, -height / 2.0, 0.0))
    .build();
```

--------------------------------

### Construct Quad Faces

Source: https://docs.rs/hexx/latest/src/hexx/mesh/face.rs.html

Methods to create standard or bounded quad faces for mesh generation.

```rust
impl Quad {
    /// Construct a regular quad from two [`left`, `right`] 2d positions for x
    /// and z and a `bottom_height` and `top_height` for y
    ///
    /// # Arguments
    ///
    /// * `[left, right]` - the two bottom 2d vertex positions
    /// * `bottom_height` - the bottom vertices Y value
    /// * `top_height` - the top vertices Y value
    #[must_use]
    pub fn new([left, right]: [Vec2; 2], bottom_height: f32, top_height: f32) -> Self {
        let normal = (left + right).normalize();
        let normal = Vec3::new(normal.x, 0.0, normal.y);
        let positions = [
            Vec3::new(right.x, bottom_height, right.y),
            Vec3::new(right.x, top_height, right.y),
            Vec3::new(left.x, top_height, left.y),
            Vec3::new(left.x, bottom_height, left.y),
        ];
        Self {
            positions,
            normals: [normal; 4],
            uvs: [Vec2::X, Vec2::ONE, Vec2::Y, Vec2::ZERO],
            // 2 - 1
            // | \ |
            // 3 - 0
            triangles: [
                Tri([2, 1, 0]), // Tri 1
                Tri([0, 3, 2]), // Tri 2
            ],
        }
    }

    /// Same as [`Quad::new`] but the UV `y` values are bounded based on
    /// [`min_height`, `max_height`]
    #[must_use]
    pub(crate) fn new_bounded(
        sides: [Vec2; 2],
        bottom_height: f32,
        top_height: f32,
        [min_height, max_height]: [f32; 2],
    ) -> Self {
        let delta = max_height - min_height;
        let mut quad = Self::new(sides, bottom_height, top_height);
        let bottom_v = (bottom_height - min_height) / delta;
        let top_v = (top_height - min_height) / delta;
        quad.uvs[0][1] = bottom_v;
        quad.uvs[1][1] = top_v;
        quad.uvs[2][1] = top_v;
        quad.uvs[3][1] = bottom_v;
        quad
    }
}
```

--------------------------------

### Implement Storage Access and Iteration Methods

Source: https://docs.rs/hexx/latest/src/hexx/storage/mod.rs.html

Methods for retrieving mutable references and iterating over hex-keyed storage values.

```rust
        self.get(&hex)
    }

    #[inline]
    fn get_mut(&mut self, hex: crate::Hex) -> Option<&mut T> {
        self.get_mut(&hex)
    }

    #[inline]
    fn values<'s>(&'s self) -> impl ExactSizeIterator<Item = &'s T>
    where
        T: 's,
    {
        self.values()
    }

    #[inline]
    fn values_mut<'s>(&'s mut self) -> impl ExactSizeIterator<Item = &'s mut T>
    where
        T: 's,
    {
        self.values_mut()
    }

    #[inline]
    fn iter<'s>(&'s self) -> impl ExactSizeIterator<Item = (crate::Hex, &'s T)>
    where
        T: 's,
    {
        self.iter().map(|(k, v)| (*k, v))
    }

    #[inline]
    fn iter_mut<'s>(&'s mut self) -> impl ExactSizeIterator<Item = (crate::Hex, &'s mut T)>
    where
        T: 's,
    {
        self.iter_mut().map(|(k, v)| (*k, v))
    }
}
```

--------------------------------

### Perform Mesh Face Insetting

Source: https://docs.rs/hexx/latest/src/hexx/mesh/face.rs.html

The inset method scales a face's vertices and UVs based on a specified mode and scale, optionally keeping the inner face geometry.

```rust
pub fn inset(self, mode: InsetScaleMode, scale: f32, keep_inner_face: bool) -> MeshInfo {
        // We compute the inset mesh, identical to the original face
        let mut inset_face = self.clone();
        // We downscale the inset face vertices and uvs along its plane
        match mode {
            InsetScaleMode::Centroid => {
                // vertices
                let centroid = inset_face.centroid();
                inset_face.positions.iter_mut().for_each(|v| {
                    *v = *v + ((centroid - *v) * scale);
                });
                // uvs
                let uv_centroid = inset_face.uv_centroid();
                inset_face.uvs.iter_mut().for_each(|uv| {
                    *uv = *uv + ((uv_centroid - *uv) * scale);
                });
            }
            InsetScaleMode::SmallestEdge => {
                let mut new_positions = inset_face.positions;
                let mut new_uvs = inset_face.uvs;
                for idx in 0..VERTS {
                    let [prev_idx, next_idx] = [(idx + VERTS - 1) % VERTS, (idx + 1) % VERTS];
                    // vertices
                    let [pos, prev, next] =
                        [idx, prev_idx, next_idx].map(|i| inset_face.positions[i]);
                    let [dir_prev, dir_next] = [(prev - pos), (next - pos)];
                    let [prev_len, next_len] = [dir_prev.length(), dir_next.length()];
                    let dist = prev_len.min(next_len) * scale;
                    new_positions[idx] =
                        pos + dir_next.normalize() * dist + dir_prev.normalize() * dist;
                    // uvs
                    let [disp_prev, disp_next] = [dist / prev_len, dist / next_len];
                    let [pos, prev, next] = [idx, prev_idx, next_idx].map(|i| inset_face.uvs[i]);
                    let [dir_prev, dir_next] = [(prev - pos), (next - pos)];
                    new_uvs[idx] = pos + dir_next * disp_next + dir_prev * disp_prev;
                }
                inset_face.positions = new_positions;
                inset_face.uvs = new_uvs;
            }
        }
        let mut inset_face = MeshInfo::from(inset_face);
        if !keep_inner_face {
            inset_face.indices.clear();
        }
        let mut mesh = MeshInfo::from(self);
        mesh.indices.clear();
        let vertex_count = VERTS as u16;
        let connection_indices = (0..vertex_count).flat_map(|v_idx| {
            let next_v_idx = (v_idx + 1) % vertex_count;
            let inset_v_idx = v_idx + vertex_count;
            let next_inset_v_idx = next_v_idx + vertex_count;

            let [mut a, mut b] = [
                Tri([next_inset_v_idx, next_v_idx, v_idx]),
                Tri([v_idx, inset_v_idx, next_inset_v_idx]),
            ];
            if scale < 0.0 {
                a.flip();
                b.flip();
            }
            a.0.into_iter().chain(b.0)
        });
        mesh.indices.extend(connection_indices);
        mesh.merge_with(inset_face);
        mesh
    }
```

--------------------------------

### Configure RectMetadata and Wrapped Access

Source: https://docs.rs/hexx/latest/src/hexx/storage/rect.rs.html

Define map metadata including offset modes and demonstrate both standard and wrapped coordinate retrieval.

```rust
# use hexx::{
#    storage::{HexStore, RectMap, RectMetadata, WrapStrategy},
#    *,
# };
let rect_hex_map = RectMetadata::from_half_size(UVec2::new(8, 12))
    .with_orientation(HexOrientation::Pointy)
    .with_offset_mode(OffsetHexMode::Odd)
    .with_wrap_strategies([WrapStrategy::Cycle, WrapStrategy::Clamp])
    .build_default::<i32>();
let hex = Hex::new(0, 0);

assert_eq!(rect_hex_map.get(hex), Some(&0_i32));
assert_eq!(rect_hex_map.wrapped_get(hex), &0_i32);
```

--------------------------------

### RectMetadata Builder Methods

Source: https://docs.rs/hexx/latest/src/hexx/storage/rect.rs.html

Methods for configuring the RectMetadata instance before building a RectMap.

```APIDOC
## RectMetadata Configuration

### from_start_dim(start: IVec2, dim: UVec2) -> Self
Creates a new RectMetadata with a starting coordinate and map dimensions.

### with_half_size(half_size: IVec2) -> Self
Sets the map boundaries based on a half-span vector.

### with_start_end(start: IVec2, end: IVec2) -> Self
Sets the map boundaries using start and end coordinates.

### with_start_dim(start: IVec2, dim: UVec2) -> Self
Sets the start coordinate and map dimension.

### with_orientation(orientation: HexOrientation) -> Self
Sets the hexagonal orientation (e.g., Pointy or Flat).

### with_offset_mode(offset_mode: OffsetHexMode) -> Self
Sets the coordinate offset mode.

### with_wrap_strategies(wrap_strategies: [WrapStrategy; 2]) -> Self
Sets the wrapping strategies for the map.
```

--------------------------------

### build

Source: https://docs.rs/hexx/latest/hexx/mesh/struct.HeightMapMeshBuilder.html

Consumes the builder instance to compute and return the final mesh data.

```APIDOC
## pub fn build(self) -> MeshInfo

### Description
Consumes the builder to return the computed mesh data.
```

--------------------------------

### Quad::apply_options

Source: https://docs.rs/hexx/latest/hexx/mesh/face/type.Quad.html

Applies face options to the quad and returns a MeshInfo object.

```APIDOC
## pub fn apply_options(self, opts: &FaceOptions) -> MeshInfo

### Description
Applies the face options to the face and returns a mesh.
```

--------------------------------

### Triangle::new

Source: https://docs.rs/hexx/latest/hexx/shapes/struct.Triangle.html

Creates a new instance of a Triangle with the specified size.

```APIDOC
## pub const fn new(size: u32) -> Self

### Description
Creates a new Triangle shape with the given size.

### Parameters
- **size** (u32) - The size of the triangle.
```

--------------------------------

### Initialize HexagonalMap

Source: https://docs.rs/hexx/latest/hexx/storage/struct.HexagonalMap.html

Create a new hexagonal map with a specified center, radius, and a closure to populate values.

```rust

let map = HexagonalMap::new(Hex::ZERO, 10, |coord| coord.length());
assert_eq!(map[hex(1, 0)], 1);
```

```rust

let map = HexagonalMap::new(Hex::ZERO, 10, |coord| coord.length());
assert_eq!(map[hex(1, 0)], 1);
```

--------------------------------

### Configure Heightmap Mesh Properties

Source: https://docs.rs/hexx/latest/src/hexx/mesh/heightmap_builder.rs.html

Methods for setting global mesh transformations and height constraints.

```rust
#[must_use]
    pub const fn with_height_range(mut self, range: RangeInclusive<f32>) -> Self {
        self.height_range = Some(range);
        self
    }
```

```rust
#[must_use]
    pub const fn with_rotation(mut self, rotation: Quat) -> Self {
        self.rotation = Some(rotation);
        self
    }
```

```rust
#[must_use]
    #[inline]
    pub const fn with_offset(mut self, offset: Vec3) -> Self {
        self.offset = Some(offset);
        self
    }
```

```rust
#[must_use]
    pub const fn with_scale(mut self, scale: Vec3) -> Self {
        self.scale = Some(scale);
        self
    }
```

--------------------------------

### Cache ring edges

Source: https://docs.rs/hexx/latest/src/hexx/hex/rings.rs.html

Shows how to pre-compute ring edges around a coordinate to use as a cache for later operations.

```rust
# use hexx::*;

// We cache 10 rings around the origin
let cache = Hex::ORIGIN.cached_custom_ring_edges::<10>(VertexDirection::FLAT_RIGHT, true);
// We have our target center
let target = Hex::new(11, 24);
// We retrieve the ring of range 5 and offset it to match the target
let five_ring = cache[5].iter().map(|h| *h + target);
```

--------------------------------

### Initialize HexModMap

Source: https://docs.rs/hexx/latest/hexx/storage/struct.HexModMap.html

Create a new hexagon-shaped map using a closure to define values for each coordinate.

```rust

let map = HexModMap::new(Hex::ZERO, 10, |coord| coord.length());
assert_eq!(map[hex(1, 0)], 1);
```

--------------------------------

### Create EdgeDirection from Pointy Angle Degrees

Source: https://docs.rs/hexx/latest/hexx/direction/struct.EdgeDirection.html

Constructs an EdgeDirection from an angle in degrees for pointy-topped hexagons.

```rust

let direction = EdgeDirection::from_pointy_angle_degrees(35.0);
assert_eq!(direction, EdgeDirection::FLAT_BOTTOM);
```

--------------------------------

### Test HexLayout Implementations

Source: https://docs.rs/hexx/latest/src/hexx/layout.rs.html

Unit tests verifying corner positions for flat and pointy orientations, and ensuring rect size consistency.

```rust
#[test]
    fn flat_corners() {
        let point = Hex::new(0, 0);
        let mut layout = HexLayout::new(HexOrientation::Flat).with_scale(Vec2::new(10., 10.));
        let corners = layout.hex_corners(point).map(Vec2::round);
        assert_eq!(
            corners,
            [
                Vec2::new(10.0, 0.0),
                Vec2::new(5.0, 9.0),
                Vec2::new(-5.0, 9.0),
                Vec2::new(-10.0, 0.0),
                Vec2::new(-5.0, -9.0),
                Vec2::new(5.0, -9.0),
            ]
        );
        layout.invert_y();
        let corners = layout.hex_corners(point).map(Vec2::round);
        assert_eq!(
            corners,
            [
                Vec2::new(10.0, 0.0),
                Vec2::new(5.0, -9.0),
                Vec2::new(-5.0, -9.0),
                Vec2::new(-10.0, 0.0),
                Vec2::new(-5.0, 9.0),
                Vec2::new(5.0, 9.0),
            ]
        );
    }
```

```rust
#[test]
    fn pointy_corners() {
        let point = Hex::new(0, 0);
        let mut layout = HexLayout::new(HexOrientation::Pointy).with_scale(Vec2::new(10., 10.));
        let corners = layout.hex_corners(point).map(Vec2::round);
        assert_eq!(
            corners,
            [
                Vec2::new(9.0, -5.0),
                Vec2::new(9.0, 5.0),
                Vec2::new(-0.0, 10.0),
                Vec2::new(-9.0, 5.0),
                Vec2::new(-9.0, -5.0),
                Vec2::new(0.0, -10.0),
            ]
        );
        layout.invert_y();
        let corners = layout.hex_corners(point).map(Vec2::round);
        assert_eq!(
            corners,
            [
                Vec2::new(9.0, 5.0),
                Vec2::new(9.0, -5.0),
                Vec2::new(-0.0, -10.0),
                Vec2::new(-9.0, -5.0),
                Vec2::new(-9.0, 5.0),
                Vec2::new(0.0, 10.0),
            ]
        );
    }
```

```rust
#[test]
    fn rect_size() {
        let sizes = [
            Vec2::ZERO,
            Vec2::ONE,
            Vec2::X,
            Vec2::Y,
            Vec2::NEG_ONE,
            Vec2::NEG_X,
            Vec2::NEG_Y,
            Vec2::new(10.0, 5.0),
            Vec2::new(-10.0, 31.1),
            Vec2::new(110.0, 25.0),
            Vec2::new(-210.54, -54.0),
        ];
        for size in sizes {
            for orientation in [HexOrientation::Flat, HexOrientation::Pointy] {
                let layout = HexLayout::new(orientation).with_rect_size(size);
                let rect = layout.rect_size();
                assert_relative_eq!(rect.x, size.x, epsilon = 0.00001);
                assert_relative_eq!(rect.y, size.y, epsilon = 0.00001);
            }
        }
    }
```

--------------------------------

### VertexDirection Utility Methods

Source: https://docs.rs/hexx/latest/src/hexx/direction/vertex_direction.rs.html

Methods for iteration, index retrieval, and hex coordinate conversion.

```rust
pub fn iter() -> impl ExactSizeIterator<Item = Self> {
    Self::ALL_DIRECTIONS.into_iter()
}

#[must_use]
#[inline]
pub const fn index(self) -> u8 {
    self.0
}

#[must_use]
#[inline]
pub const fn into_hex(self) -> Hex {
    Hex::DIAGONAL_COORDS[self.0 as usize]
}
```

--------------------------------

### Convert between resolution levels

Source: https://docs.rs/hexx/latest/hexx/hex/struct.Hex.html

Demonstrates converting a coordinate to a lower resolution parent and back to a higher resolution center.

```rust

// We define a coordinate
let coord = hex(23, 45);
// We take its *parent* in a coordinate system of size 5
let parent = coord.to_lower_res(5);
// We can then retrieve the center of that parent in the same system as `coord`
let center = parent.to_higher_res(5);
// Therefore the distance between the parent center and `coord` should be lower than 5
assert!(coord.distance_to(center) <= 5);
```

```rust

// We define a coordinate
let coord = hex(23, 45);
// We take its *parent* in a coordinate system of size 5
let parent = coord.to_lower_res(5);
// We can then retrieve the center of that parent in the same system as `coord`
let center = parent.to_higher_res(5);
// Therefore the distance between the parent center and `coord` should be lower than 5
assert!(coord.distance_to(center) <= 5);
```

--------------------------------

### Storage Implementation Macro

Source: https://docs.rs/hexx/latest/src/hexx/storage/mod.rs.html

A macro to implement standard indexing traits for hexagonal storage types, enabling direct access via the index operator.

```rust
macro_rules! storage_impl {
    ($ty:ty) => {
        impl<T> std::ops::Index<crate::Hex> for $ty {
            type Output = T;

            fn index(&self, index: crate::Hex) -> &Self::Output {
                self.get(index).unwrap()
            }
        }

        impl<T> std::ops::Index<&crate::Hex> for $ty {
            type Output = T;

            fn index(&self, index: &crate::Hex) -> &Self::Output {
                self.get(*index).unwrap()
            }
        }

        impl<T> std::ops::IndexMut<crate::Hex> for $ty {
            fn index_mut(&mut self, index: crate::Hex) -> &mut Self::Output {
                self.get_mut(index).unwrap()
            }
        }

        impl<T> std::ops::IndexMut<&crate::Hex> for $ty {
            fn index_mut(&mut self, index: &crate::Hex) -> &mut Self::Output {
                self.get_mut(*index).unwrap()
            }
        }
    };
}
```

--------------------------------

### Configure Side Face Options

Source: https://docs.rs/hexx/latest/src/hexx/mesh/heightmap_builder.rs.html

Methods to control the appearance of the column side faces.

```rust
#[must_use]
    #[inline]
    pub const fn without_sides(mut self) -> Self {
        self.side_options = None;
        self
    }
```

```rust
#[must_use]
    #[inline]
    pub const fn with_side_options(mut self, options: FaceOptions) -> Self {
        self.side_options = Some(options);
        self
    }
```

--------------------------------

### Create EdgeDirection from Flat Angle Radians

Source: https://docs.rs/hexx/latest/hexx/direction/struct.EdgeDirection.html

Constructs an EdgeDirection from an angle in radians for flat-topped hexagons.

```rust

let direction = EdgeDirection::from_flat_angle(0.6);
assert_eq!(direction, EdgeDirection::FLAT_BOTTOM_RIGHT);
```
Tokens:
Raw