rpfm_extensions/startpos/

coords.rs

//---------------------------------------------------------------------------//
// Copyright (c) 2017-2026 Ismael Gutiérrez González. All rights reserved.
//
// This file is part of the Rusted PackFile Manager (RPFM) project,
// which can be found here: https://github.com/Frodo45127/rpfm.
//
// This file is licensed under the MIT license, which can be found here:
// https://github.com/Frodo45127/rpfm/blob/master/LICENSE.
//---------------------------------------------------------------------------//

//! Coordinate systems of the campaign map.
//!
//! The campaign map uses three related coordinate systems:
//!
//! - **World**: the `f32` positions stored in startpos `Coord2d` nodes.
//! - **Raw**: the `u16` units stored in the map files (`trade_routes.ptd`). `raw = world * scale + 4`.
//! - **Cell**: the logical hex grid of the map (`HEX_MAP_DATA`, 1016x720 cells in Attila's main map). A cell is
//!   6 raw units wide and 8 raw units high, and odd columns are shifted half a cell down.
//!
//! The scales of a map ([`MapScale`]) come from its hex grid and its size in world units: the last column starts
//! at the map's right edge, and the last row of odd columns ends at its bottom edge. Characters placed on cells land
//! exactly where the current game build (the one BOB uses) puts them: 518 of 518 in Attila's main campaign. CA's
//! older build of the shipped startposes rounds the horizontal position differently, one ulp away at most.

use getset::CopyGetters;
use serde_derive::{Deserialize, Serialize};

#[cfg(test)] #[path = "coords_test.rs"] pub(crate) mod coords_test;

/// Offset added to raw coordinates.
pub const RAW_OFFSET: f32 = 4.0;

/// Raw units per cell, horizontally.
pub const CELL_RAW_WIDTH: f32 = 6.0;

/// Raw units per cell, vertically.
pub const CELL_RAW_HEIGHT: f32 = 8.0;

/// Neighbour offsets of a cell in an odd column, in the order the game uses (south first, then clockwise).
const ODD_COLUMN_NEIGHBOURS: [(i32, i32); 6] = [(0, 1), (1, 1), (1, 0), (0, -1), (-1, 0), (-1, 1)];

/// Neighbour offsets of a cell in an even column, in the order the game uses (south first, then clockwise).
const EVEN_COLUMN_NEIGHBOURS: [(i32, i32); 6] = [(0, 1), (1, 0), (1, -1), (0, -1), (-1, -1), (-1, 0)];

/// Edges of a hex cell.
pub const HEX_EDGES: u8 = 6;

/// Edge mask with every edge set.
const ALL_EDGES: u8 = 0b11_1111;

/// Edge mask of the first two edges.
const FIRST_TWO_EDGES: u8 = 0b11;

//---------------------------------------------------------------------------//
//                              Types
//---------------------------------------------------------------------------//

/// A cell of the logical hex grid of the campaign map.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default, CopyGetters, Serialize, Deserialize)]
#[getset(get_copy = "pub")]
pub struct HexCell {

    /// Column.
    x: u16,

    /// Row.
    y: u16,
}

/// World units per raw unit of a campaign map, horizontally and vertically.
#[derive(Debug, Clone, Copy, PartialEq, CopyGetters)]
#[getset(get_copy = "pub")]
pub struct MapScale {

    /// World units per raw unit, horizontally.
    x: f32,

    /// World units per raw unit, vertically.
    y: f32,

    /// World units per cell, horizontally.
    cell_width: f32,
}

/// A piece covering some edges of a hex cell (a road or a coast), as a shape and a rotation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, CopyGetters)]
#[getset(get_copy = "pub")]
pub struct EdgePiece {

    /// Edge mask of the piece before rotating it.
    shape: u8,

    /// Edges the shape is rotated by, in the game's direction order.
    rotation: u8,
}

//---------------------------------------------------------------------------//
//                              Implementations
//---------------------------------------------------------------------------//

impl HexCell {

    /// Creates a cell from its column and row.
    pub fn new(x: u16, y: u16) -> Self {
        Self { x, y }
    }

    /// Returns the existing neighbours of the cell, in the game's direction order.
    ///
    /// # Returns
    ///
    /// Up to six cells; neighbours that would fall outside the `u16` range are skipped.
    pub fn neighbours(&self) -> impl Iterator<Item = HexCell> + '_ {
        (0..HEX_EDGES).filter_map(|direction| self.neighbour(direction))
    }

    /// Returns the neighbour in a direction (0 to 5, in the game's direction order).
    ///
    /// # Returns
    ///
    /// `None` if the neighbour would fall outside the `u16` range, or the direction is over 5.
    pub fn neighbour(&self, direction: u8) -> Option<HexCell> {
        let offsets = if self.x % 2 == 1 { &ODD_COLUMN_NEIGHBOURS } else { &EVEN_COLUMN_NEIGHBOURS };
        let (dx, dy) = offsets.get(usize::from(direction))?;
        let x = u16::try_from(i32::from(self.x) + dx).ok()?;
        let y = u16::try_from(i32::from(self.y) + dy).ok()?;
        Some(HexCell::new(x, y))
    }

    /// Returns the edge mask of the neighbours matching a predicate: bit `n` stands for the `n`-th neighbour in the
    /// game's direction order. Neighbours outside the `u16` range never match.
    pub fn neighbour_mask(&self, mut predicate: impl FnMut(HexCell) -> bool) -> u8 {
        (0..HEX_EDGES)
            .filter(|&direction| self.neighbour(direction).is_some_and(&mut predicate))
            .fold(0, |mask, direction| mask | 1 << direction)
    }

    /// Returns the cell followed by its neighbours, in the order the game stores slot footprints.
    pub fn footprint(&self) -> Vec<HexCell> {
        std::iter::once(*self).chain(self.neighbours()).collect()
    }
}

impl MapScale {

    /// Returns the scale of a map.
    ///
    /// # Arguments
    ///
    /// * `cells` - Columns and rows of the map's hex grid.
    /// * `world_size` - Size of the map in world units.
    pub fn new(cells: (u32, u32), world_size: (f32, f32)) -> Self {
        let width = f64::from(cells.0.saturating_sub(1)) * f64::from(CELL_RAW_WIDTH);
        let height = f64::from(cells.1) * f64::from(CELL_RAW_HEIGHT) + f64::from(CELL_RAW_HEIGHT / 2.0);
        let raw_per_world = (width / f64::from(world_size.0)) as f32;
        Self {
            x: (f64::from(world_size.0) / width) as f32,
            y: (f64::from(world_size.1) / height) as f32,
            cell_width: CELL_RAW_WIDTH / raw_per_world,
        }
    }

    /// Returns the cell containing a world position, as the game finds it.
    ///
    /// Odd columns are shifted half a cell down, so their rows start half a cell height later. Cells are hexagons
    /// wider than their column: the first third of a column holds the slanted edges shared with the previous column,
    /// where positions above or below the edge belong to the previous column's cells.
    pub fn cell_at(&self, x: f32, y: f32) -> HexCell {
        let (raw_x, raw_y) = self.world_to_raw(x, y);
        let columns = raw_x / CELL_RAW_WIDTH;
        let mut column = columns.floor() as i32;
        let row_offset = if column % 2 == 1 { CELL_RAW_HEIGHT / 2.0 } else { 0.0 };
        let rows = (raw_y - row_offset) / CELL_RAW_HEIGHT;
        let mut row = rows.floor() as i32;

        // Distance into the column in thirds, and height from the middle of the row in rows.
        let into_column = (columns - column as f32) * 3.0;
        let from_middle = rows - row as f32 - 0.5;
        if into_column < 1.0 {
            let odd = column & 1;
            if into_column <= from_middle * 2.0 {
                (column, row) = (column - 1, row + odd);
            } else if into_column <= from_middle * -2.0 {
                (column, row) = (column - 1, row + odd - 1);
            }
        }
        HexCell::new(column.max(0) as u16, row.max(0) as u16)
    }

    /// Returns the world position of a cell's top-left corner, where the game places characters given by cell.
    ///
    /// The game multiplies in double precision by single precision scales, and adds the half-cell shift of odd
    /// columns as a separate single precision term, so the position is computed the same way.
    pub fn world_position(&self, cell: HexCell) -> (f32, f32) {
        let x = (f64::from(cell.x) * f64::from(self.cell_width)) as f32;
        let y = (f64::from(cell.y) * f64::from(CELL_RAW_HEIGHT) * f64::from(self.y)) as f32;
        let row_offset = if cell.x % 2 == 1 { (f64::from(CELL_RAW_HEIGHT / 2.0) * f64::from(self.y)) as f32 } else { 0.0 };
        (x, y + row_offset)
    }

    /// Converts a world position to raw map units.
    pub fn world_to_raw(&self, x: f32, y: f32) -> (f32, f32) {
        (x / self.x + RAW_OFFSET, y / self.y + RAW_OFFSET)
    }

    /// Converts raw map units to a world position.
    pub fn raw_to_world(&self, x: f32, y: f32) -> (f32, f32) {
        ((x - RAW_OFFSET) * self.x, (y - RAW_OFFSET) * self.y)
    }

    /// Converts a raw offset (a vector, no translation) to world units.
    ///
    /// Map files store offsets at 100 times the raw scale.
    pub fn raw_offset_to_world(&self, x: i16, y: i16) -> (f32, f32) {
        (f32::from(x) * self.x / 100.0, f32::from(y) * self.y / 100.0)
    }
}

impl EdgePiece {

    /// Splits an edge mask into a piece shape and a rotation.
    ///
    /// The shape is the smallest rotation of the mask with its first two edges set, or the smallest rotation if
    /// none has them (so a straight road is `0b1001` and a bend is `0b11`). The rotation is the smallest one turning
    /// the shape into the mask.
    pub fn from_mask(mask: u8) -> Self {
        let mask = mask & ALL_EDGES;
        let rotations = (0..HEX_EDGES).map(|rotation| rotate_edges(mask, rotation));
        let shape = rotations.clone().filter(|rotated| rotated & FIRST_TWO_EDGES == FIRST_TWO_EDGES).min()
            .or_else(|| rotations.min())
            .unwrap_or_default();
        let rotation = (0..HEX_EDGES).find(|&rotation| rotate_edges(shape, rotation) == mask).unwrap_or_default();
        Self { shape, rotation }
    }
}

/// Rotates an edge mask by some edges, in the game's direction order.
fn rotate_edges(mask: u8, edges: u8) -> u8 {
    ((mask << edges) | (mask >> ((HEX_EDGES - edges) % HEX_EDGES))) & ALL_EDGES
}