steel_utils/

direction.rs

//! Direction enum representing the six cardinal directions in Minecraft.
//!
//! This is moved from `steel-registry::blocks::properties::Direction`.

use std::io::{self, Cursor};

use glam::IVec3;
use steel_math::{DEGREE_90, DEGREE_180, DEGREE_270};

use crate::{axis::Axis, codec::VarInt, serial::ReadFrom, types::BlockPos};

/// The six cardinal directions in Minecraft.
#[derive(Clone, Copy, Debug)]
#[derive_const(PartialEq)]
pub enum Direction {
    /// Negative Y direction.
    Down,
    /// Positive Y direction.
    Up,
    /// Negative Z direction.
    North,
    /// Positive Z direction.
    South,
    /// Negative X direction.
    West,
    /// Positive X direction.
    East,
}

impl ReadFrom for Direction {
    fn read(data: &mut Cursor<&[u8]>) -> io::Result<Self> {
        let id = VarInt::read(data)?.0;
        if (0..6).contains(&id) {
            Ok(Direction::from_3d_data_value(id))
        } else {
            Err(io::Error::other("Invalid Direction id"))
        }
    }
}

impl Direction {
    /// Vanilla `Direction.get3DDataValue()` like Down=0,…,East=5.
    #[must_use]
    pub const fn get_3d_data_value(self) -> i32 {
        match self {
            Direction::Down => 0,
            Direction::Up => 1,
            Direction::North => 2,
            Direction::South => 3,
            Direction::West => 4,
            Direction::East => 5,
        }
    }

    /// Vanilla `Direction.from3DDataValue(int)`.
    /// Uses Java remainder semantics (toward zero) then absolute value
    /// `BY_3D_DATA`[Mth.abs(data % 6)].
    #[must_use]
    pub const fn from_3d_data_value(data: i32) -> Direction {
        let rem = data % 6;
        let idx = if rem < 0 {
            (-rem) as usize
        } else {
            rem as usize
        };
        Direction::ALL[idx]
    }

    /// Returns the block position offset for this direction.
    #[must_use]
    pub const fn offset(self) -> (i32, i32, i32) {
        match self {
            Direction::Down => (0, -1, 0),
            Direction::Up => (0, 1, 0),
            Direction::North => (0, 0, -1),
            Direction::South => (0, 0, 1),
            Direction::West => (-1, 0, 0),
            Direction::East => (1, 0, 0),
        }
    }

    /// Returns the XZ offset for this direction, treating the vertical directions as no movement.
    ///
    /// For `Down` and `Up` the result is `(0, 0)`.
    #[must_use]
    pub const fn offset_xz(self) -> (i32, i32) {
        match self {
            Direction::Down | Direction::Up => (0, 0),
            Direction::North => (0, -1),
            Direction::South => (0, 1),
            Direction::West => (-1, 0),
            Direction::East => (1, 0),
        }
    }

    /// Returns the block position offset for this direction as an [`IVec3`].
    #[must_use]
    pub const fn offset_vec(self) -> IVec3 {
        let (x, y, z) = self.offset();
        IVec3::new(x, y, z)
    }

    /// Returns the block position relative to the given position in this direction.
    #[must_use]
    pub fn relative(self, pos: BlockPos) -> BlockPos {
        BlockPos(pos.0 + self.offset_vec())
    }

    /// Returns the axis this direction is on.
    #[must_use]
    pub const fn get_axis(self) -> Axis {
        match self {
            Direction::Down | Direction::Up => Axis::Y,
            Direction::North | Direction::South => Axis::Z,
            Direction::West | Direction::East => Axis::X,
        }
    }

    /// Returns the opposite direction.
    #[must_use]
    pub const fn opposite(self) -> Direction {
        match self {
            Direction::Down => Direction::Up,
            Direction::Up => Direction::Down,
            Direction::North => Direction::South,
            Direction::South => Direction::North,
            Direction::West => Direction::East,
            Direction::East => Direction::West,
        }
    }

    /// Returns the horizontal direction from a yaw rotation.
    #[must_use]
    pub fn from_yaw(yaw: f32) -> Direction {
        match ((f64::from(yaw) / f64::from(DEGREE_90) + 0.5).floor() as i32) & 3 {
            0 => Direction::South,
            1 => Direction::West,
            2 => Direction::North,
            _ => Direction::East,
        }
    }

    /// Returns the yaw rotation for this direction.
    ///
    /// Only meaningful for horizontal directions.
    /// Vertical directions return 0.
    #[must_use]
    pub const fn to_yaw(self) -> f32 {
        match self {
            Direction::North => DEGREE_180,
            Direction::South | Direction::Up | Direction::Down => 0.0,
            Direction::West => DEGREE_90,
            Direction::East => DEGREE_270,
        }
    }

    /// Returns the axis this direction is on.
    #[must_use]
    pub const fn axis(self) -> Axis {
        self.get_axis()
    }

    /// Returns vanilla `Direction.get(AxisDirection.POSITIVE, axis)`.
    #[must_use]
    pub const fn positive_for_axis(axis: Axis) -> Direction {
        match axis {
            Axis::X => Direction::East,
            Axis::Y => Direction::Up,
            Axis::Z => Direction::South,
        }
    }

    /// Returns whether this direction is horizontal (not up or down).
    #[must_use]
    pub const fn is_horizontal(self) -> bool {
        matches!(
            self,
            Direction::North | Direction::South | Direction::East | Direction::West
        )
    }

    /// Rotates this direction 90 degrees clockwise around the Y axis.
    ///
    /// Vertical directions are unchanged.
    #[must_use]
    pub const fn rotate_y_clockwise(self) -> Direction {
        match self {
            Direction::North => Direction::East,
            Direction::East => Direction::South,
            Direction::South => Direction::West,
            Direction::West => Direction::North,
            other => other,
        }
    }

    /// Rotates this direction 90 degrees counter-clockwise around the Y axis.
    ///
    /// Vertical directions are unchanged.
    #[must_use]
    pub const fn rotate_y_counter_clockwise(self) -> Direction {
        match self {
            Direction::North => Direction::West,
            Direction::West => Direction::South,
            Direction::South => Direction::East,
            Direction::East => Direction::North,
            other => other,
        }
    }

    /// The order in which neighbor shape updates are processed.
    /// This matches vanilla's `BlockBehavior.UPDATE_SHAPE_ORDER`.
    pub const UPDATE_SHAPE_ORDER: [Direction; 6] = [
        Direction::West,
        Direction::East,
        Direction::North,
        Direction::South,
        Direction::Down,
        Direction::Up,
    ];

    /// Vanilla: `LiquidBlock.POSSIBLE_FLOW_DIRECTIONS` mapped through `getOpposite()`.
    /// Used by `LiquidBlock.shouldSpreadLiquid()` to check neighbors for lava-water interactions.
    pub const FLOW_NEIGHBOR_CHECK: [Direction; 5] = [
        Direction::Up,
        Direction::North,
        Direction::South,
        Direction::West,
        Direction::East,
    ];

    /// Vanilla `Direction.Plane.HORIZONTAL` order.
    pub const HORIZONTAL: [Direction; 4] = [
        Direction::North,
        Direction::East,
        Direction::South,
        Direction::West,
    ];

    /// Vanilla `Direction.values()` order.
    pub const ALL: [Direction; 6] = [
        Direction::Down,
        Direction::Up,
        Direction::North,
        Direction::South,
        Direction::West,
        Direction::East,
    ];

    /// Returns all directions ordered by how closely they match the player's look direction.
    ///
    /// This matches vanilla's `Direction.orderedByNearest(Entity)`.
    /// - `yaw`: Player's yaw rotation in degrees (0 = South, 90 = West, 180 = North, 270 = East)
    /// - `pitch`: Player's pitch rotation in degrees (negative = looking up, positive = looking down)
    #[must_use]
    pub fn ordered_by_nearest(yaw: f32, pitch: f32) -> [Direction; 6] {
        // Convert to radians and negate yaw to match vanilla's coordinate system
        let pitch_rad = pitch.to_radians();
        let yaw_rad = (-yaw).to_radians();

        let pitch_sin = pitch_rad.sin();
        let pitch_cos = pitch_rad.cos();
        let yaw_sin = yaw_rad.sin();
        let yaw_cos = yaw_rad.cos();

        // Determine which direction on each axis the player is looking
        let x_pos = yaw_sin > 0.0;
        let y_pos = pitch_sin < 0.0; // Negative pitch = looking up
        let z_pos = yaw_cos > 0.0;

        // Calculate magnitude of look direction on each axis
        let x_yaw = if x_pos { yaw_sin } else { -yaw_sin };
        let y_mag = if y_pos { -pitch_sin } else { pitch_sin };
        let z_yaw = if z_pos { yaw_cos } else { -yaw_cos };
        let x_mag = x_yaw * pitch_cos;
        let z_mag = z_yaw * pitch_cos;

        // Determine the primary direction on each axis
        let axis_x = if x_pos {
            Direction::East
        } else {
            Direction::West
        };
        let axis_y = if y_pos {
            Direction::Up
        } else {
            Direction::Down
        };
        let axis_z = if z_pos {
            Direction::South
        } else {
            Direction::North
        };

        // Sort axes by magnitude and build the direction array
        if x_yaw > z_yaw {
            if y_mag > x_mag {
                Self::make_direction_array(axis_y, axis_x, axis_z)
            } else if z_mag > y_mag {
                Self::make_direction_array(axis_x, axis_z, axis_y)
            } else {
                Self::make_direction_array(axis_x, axis_y, axis_z)
            }
        } else if y_mag > z_mag {
            Self::make_direction_array(axis_y, axis_z, axis_x)
        } else if x_mag > y_mag {
            Self::make_direction_array(axis_z, axis_x, axis_y)
        } else {
            Self::make_direction_array(axis_z, axis_y, axis_x)
        }
    }

    /// Creates an array of all 6 directions ordered by magnitude.
    ///
    /// The order is: 3 primary directions by magnitude, then their opposites in reverse order.
    /// This matches vanilla's `Direction.makeDirectionArray()`.
    const fn make_direction_array(
        axis1: Direction,
        axis2: Direction,
        axis3: Direction,
    ) -> [Direction; 6] {
        [
            axis1,
            axis2,
            axis3,
            axis3.opposite(),
            axis2.opposite(),
            axis1.opposite(),
        ]
    }

    /// Returns the direction name as a string (for `PropertyEnum` compatibility).
    #[must_use]
    pub const fn as_str(&self) -> &str {
        match self {
            Direction::Down => "down",
            Direction::Up => "up",
            Direction::North => "north",
            Direction::South => "south",
            Direction::West => "west",
            Direction::East => "east",
        }
    }

    /// Returns whether this direction is facing the given yaw angle
    #[must_use]
    pub fn is_facing_yaw(self, yaw: f32) -> bool {
        let radians = yaw.to_radians();
        let dx = -radians.sin();
        let dz = radians.cos();

        let (nx, nz) = self.offset_xz();

        (nx as f32) * dx + (nz as f32) * dz > 0.0
    }

    /// Returns a random direction
    #[must_use]
    pub fn random() -> Self {
        match rand::random_range(0..6) {
            1 => Self::Up,
            2 => Self::North,
            3 => Self::South,
            4 => Self::West,
            5 => Self::East,
            _ => Self::Down,
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::axis::Axis;

    use super::Direction;

    #[test]
    fn horizontal_dirs_matches_vanilla_plane_horizontal_order() {
        assert_eq!(
            Direction::HORIZONTAL,
            [
                Direction::North,
                Direction::East,
                Direction::South,
                Direction::West,
            ]
        );
    }

    #[test]
    fn all_dirs_matches_vanilla_values_order() {
        assert_eq!(
            Direction::ALL,
            [
                Direction::Down,
                Direction::Up,
                Direction::North,
                Direction::South,
                Direction::West,
                Direction::East,
            ]
        );
    }

    #[test]
    fn three_d_data_value_round_trips_vanilla_ids() {
        for direction in Direction::ALL {
            let id = direction.get_3d_data_value();
            assert_eq!(Direction::from_3d_data_value(id), direction);
        }
    }

    #[test]
    fn from_yaw_matches_vanilla_from_y_rot_boundaries() {
        let cases = [
            (0.0, Direction::South),
            (44.999, Direction::South),
            (45.0, Direction::West),
            (134.999, Direction::West),
            (135.0, Direction::North),
            (224.999, Direction::North),
            (225.0, Direction::East),
            (314.999, Direction::East),
            (315.0, Direction::South),
            (-44.999, Direction::South),
            (-45.0, Direction::South),
            (-45.001, Direction::East),
            (-135.0, Direction::East),
            (-225.0, Direction::North),
            (-315.0, Direction::West),
            (405.0, Direction::West),
        ];

        for (yaw, direction) in cases {
            assert_eq!(Direction::from_yaw(yaw), direction, "yaw {yaw}");
        }
    }

    #[test]
    fn from_3d_data_value_matches_java_abs_mod_wrap() {
        // Vanilla is "BY_3D_DATA[Mth.abs(data % 6)]".
        assert_eq!(Direction::from_3d_data_value(6), Direction::Down);
        assert_eq!(Direction::from_3d_data_value(7), Direction::Up);
        assert_eq!(Direction::from_3d_data_value(-1), Direction::Up);
        assert_eq!(Direction::from_3d_data_value(-7), Direction::Up);
        assert_eq!(Direction::from_3d_data_value(-6), Direction::Down);
    }

    #[test]
    fn from_yaw_preserves_vanilla_double_precision_for_large_angles() {
        // Vanilla widens yaw to double; preserving that precision selects East here.
        assert_eq!(Direction::from_yaw(193_273_528_320.0), Direction::East);
    }

    #[test]
    fn positive_for_axis_matches_vanilla_axis_direction_positive() {
        assert_eq!(Direction::positive_for_axis(Axis::X), Direction::East);
        assert_eq!(Direction::positive_for_axis(Axis::Y), Direction::Up);
        assert_eq!(Direction::positive_for_axis(Axis::Z), Direction::South);
    }
}