Struct screeps::Position

#[repr(transparent)]
pub struct Position { /* fields omitted */ }

Represents a position in a particular room in Screeps.

Note: This is analagous to the RoomPosition JavaScript type.

We've renamed this type to Position in screeps-game-api to reflect the fact that it's implemented entirely as a local type, and does represent a position located within an entire shard, not only within a single room.

This should be a very efficient type to use in most if not all situations. It's represented by a single u32, all math operations are implemented in pure-Rust code, and uploading to / downloading from JavaScript only requires transferring a single i32.

Using Position

You can retrieve a Position by getting the position of a game object using HasPosition::pos, or by creating one from coordinates with Position::new.

You can use any of the math methods available on this page to manipulate Position, and you can pass it to any game methods expecting a position or something with a position.

Serialization

Position implements both serde::Serialize and serde::Deserialize.

When serializing, it will use the format {roomName: String, x: u32, y: u32} in "human readable" formats like JSON, and will serialize as a single i32 in "non-human readable" formats like bincode.

You can also pass Position into JavaScript using the js!{} macro provided by stdweb, or helper methods using the same code like MemoryReference::set. It will be serialized the same as in JSON, as an object with roomName, x and y properties.

Note: serializing using js!{} or MemoryReference::set will not create a JavaScript RoomPosition, only something with the same properties.

If you need a reference to a RoomPosition in JavaScript to use manually, you have two options:

• Use .remote() to get a stdweb::Reference, and then use that reference in JavaScript

• Convert the room position to an integer with Position::packed_repr, send that to JS, and use the pos_from_packed JavaScript function provided by this library:

  use stdweb::js;
  use screeps::Position;
  
  let pos = Position::new(20, 21, "E5N6".parse().unwrap());
  let result = js! {
      let pos = pos_from_packed(@{pos.packed_repr()});
      pos.roomName
  };

Methods

impl Position

pub fn offset(&mut self, x: i32, y: i32)

Returns a new position offset from this position by the specified x coords and y coords.

This function operates on world coordinates, and will wrap between rooms if necessary.

To return a new position rather than modifying in place, use pos + (x, y). See the implementation of Add<(i32, i32)> for Position further down on this page.

Panics

Will panic if the new position overflows the world. See Position::from_world_coords.

Example

use screeps::Position;

let e21s21 = "E21S21".parse().unwrap();
let e21s22 = "E21S22".parse().unwrap();

let mut pos = Position::new(21, 21, e21s21);
pos.offset(5, 5);
assert_eq!(pos, Position::new(26, 26, e21s21));

pos.offset(0, 49);
assert_eq!(pos, Position::new(26, 25, e21s22));

impl Position

pub fn get_direction_to<T: ?Sized>(self, target: &T) -> Option<Direction> where
    T: HasPosition, 

pub fn get_range_to<T: ?Sized>(self, target: &T) -> u32 where
    T: HasPosition, 

pub fn in_range_to<T: ?Sized>(self, target: &T, range: u32) -> bool where
    T: HasPosition, 

pub fn is_equal_to<T: ?Sized>(self, target: &T) -> bool where
    T: HasPosition, 

pub fn is_near_to<T: ?Sized>(self, target: &T) -> bool where
    T: HasPosition, 

True if this position is in the same room as the target, and the range is at most 1.

impl Position

pub fn create_construction_site(self, ty: StructureType) -> ReturnCode

pub fn create_named_construction_site(
    self,
    ty: StructureType,
    name: &str
) -> ReturnCode

pub fn create_flag(
    self,
    name: &str,
    main_color: Color,
    secondary_color: Color
) -> Result<String, ReturnCode>

pub fn find_closest_by_range<T>(self, ty: T) -> Option<T::Item> where
    T: FindConstant, 

pub fn find_in_range<T>(self, ty: T, range: u32) -> Vec<T::Item> where
    T: FindConstant, 

pub fn find_path_to<'a, F, T: ?Sized>(
    self,
    target: &T,
    opts: FindOptions<'a, F>
) -> Path where
    F: Fn(RoomName, CostMatrix) -> Option<CostMatrix<'a>> + 'a,
    T: HasPosition, 

pub fn find_path_to_xy<'a, F>(
    self,
    x: u32,
    y: u32,
    opts: FindOptions<'a, F>
) -> Path where
    F: Fn(RoomName, CostMatrix) -> Option<CostMatrix<'a>> + 'a, 

pub fn look(self) -> Vec<LookResult>

pub fn look_for<T>(self, ty: T) -> Vec<T::Item> where
    T: LookConstant, 

impl Position

pub fn coords(&self) -> (u32, u32)

Returns this position's in-room coordinates as a pair of unsigned integers.

pub fn coords_signed(&self) -> (i32, i32)

Returns this position's in-room coordinates as a pair of signed integers.

impl Position

pub fn world_x(self) -> i32

Returns this position's horizontal "world coordinate".

The value is equal to 50 * room_x + x, where room_x is defined as room_x = -xx - 1 for Wxx rooms and as room_x = xx for Exx rooms.

pub fn world_y(self) -> i32

Returns this position's vertical "world coordinate".

The value is equal to 50 * room_y + y, where room_y is defined as room_y = -yy - 1 for Nyy rooms and as room_y = yy for Syy rooms.

pub fn world_coords(self) -> (i32, i32)

Returns this position's "world coordinates".

The first value is equal to 50 * room_x + x, where room_x is defined as room_x = -xx - 1 for Wxx rooms and as room_x = xx for Exx rooms.

The second value is equal to 50 * room_y + y, where room_y is defined as room_y = -yy - 1 for Nyy rooms and as room_y = yy for Syy rooms.

See also Position::world_x and Position::world_y.

pub fn from_world_coords(x: i32, y: i32) -> Self

Creates a room position from world coords.

Panics

Panics if either x or y is out of the range -128 * 50 .. +128 * 50.

See Position::world_coords.

impl Position

pub fn remote(self) -> Reference

impl Position

pub fn new(x: u32, y: u32, room_name: RoomName) -> Self

Create a new Position

Panics

Will panic if either x or y is larger than 49, or if room_name is outside of the range E127N127 - W127S127.

pub fn packed_repr(self) -> i32

pub fn from_packed(packed: i32) -> Self

pub fn x(self) -> u32

Gets this position's in-room x coordinate.

pub fn y(self) -> u32

Gets this position's in-room y coordinate.

pub fn room_name(self) -> RoomName

pub fn set_x(&mut self, x: u32)

pub fn set_y(&mut self, y: u32)

pub fn set_room_name(&mut self, room_name: RoomName)

pub fn with_x(self, x: u32) -> Self

pub fn with_y(self, y: u32) -> Self

pub fn with_room_name(self, room_name: RoomName) -> Self

Trait Implementations

impl HasPosition for Position

fn pos(&self) -> Position

impl FromExpectedType<Reference> for Position

fn from_expected_type(reference: Reference) -> Result<Self, ConversionError>

impl Clone for Position

fn clone(&self) -> Position

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Into<(u8, u8)> for Position

fn into(self) -> (u8, u8)

Performs the conversion.

impl Into<(u16, u16)> for Position

fn into(self) -> (u16, u16)

Performs the conversion.

impl Into<(u32, u32)> for Position

fn into(self) -> (u32, u32)

Performs the conversion.

impl Into<(u64, u64)> for Position

fn into(self) -> (u64, u64)

Performs the conversion.

impl Into<(i8, i8)> for Position

fn into(self) -> (i8, i8)

Performs the conversion.

impl Into<(i16, i16)> for Position

fn into(self) -> (i16, i16)

Performs the conversion.

impl Into<(i32, i32)> for Position

fn into(self) -> (i32, i32)

Performs the conversion.

impl Into<(i64, i64)> for Position

fn into(self) -> (i64, i64)

Performs the conversion.

impl PartialEq<Position> for Position

fn eq(&self, other: &Position) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Position) -> bool

This method tests for !=.

impl Copy for Position

impl Eq for Position

impl Display for Position

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Debug for Position

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Add<(i32, i32)> for Position

type Output = Position

The resulting type after applying the + operator.

fn add(self, (x, y): (i32, i32)) -> Self

Adds an (x, y) pair to this room position's world coordinates.

Will change rooms if necessary.

Panics

Will panic if the new position's room is outside bounds. See Position::from_world_coords.

Example

use screeps::Position;

let w5s6 = "W5S6".parse().unwrap();
let w5s5 = "W5S5".parse().unwrap();

let pos1 = Position::new(42, 42, w5s6);
let pos2 = pos1 + (7, 7);
assert_eq!(pos2, Position::new(49, 49, w5s6));

let pos3 = pos2 + (0, -59);
assert_eq!(pos3, Position::new(49, 40, w5s5));

let pos4 = pos3 - (49, 0);
assert_eq!(pos4, Position::new(0, 40, w5s5));

impl Sub<(i32, i32)> for Position

type Output = Position

The resulting type after applying the - operator.

fn sub(self, (x, y): (i32, i32)) -> Self

See the implementation of Add<(i32, i32)> for Position.

impl Sub<Position> for Position

type Output = (i32, i32)

The resulting type after applying the - operator.

fn sub(self, other: Position) -> (i32, i32)

Subtracts the other room position from this one, extracting the difference as the output.

Example

use screeps::Position;

let e5n5 = "E5N5".parse().unwrap();
let e5n6 = "E5N6".parse().unwrap();

let pos1 = Position::new(40, 40, e5n5);
let pos2 = Position::new(0, 20, e5n6);
assert_eq!(pos1 - pos2, (40, 70));

impl Hash for Position

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl JsSerialize for Position

fn _into_js<'x>(&'x self) -> SerializedValue<'x>

impl TryFrom<Value> for Position

type Error = <Value as TryInto<String>>::Error

The type returned in the event of a conversion error.

fn try_from(v: Value) -> Result<Position, Self::Error>

Performs the conversion.

impl TryFrom<Position> for Value

type Error = ConversionError

The type returned in the event of a conversion error.

fn try_from(value: Position) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_a> TryFrom<&'_a Position> for Value

type Error = ConversionError

The type returned in the event of a conversion error.

fn try_from(value: &'_a Position) -> Result<Self, Self::Error>

Performs the conversion.

impl<'_a> TryFrom<&'_a mut Position> for Value

type Error = ConversionError

The type returned in the event of a conversion error.

fn try_from(value: &'_a mut Position) -> Result<Self, Self::Error>

Performs the conversion.

impl JsSerializeOwned for Position

fn into_js_owned<'_a>(value: &'_a mut Option<Self>) -> SerializedValue<'_a>

impl<'_r> JsSerializeOwned for &'_r Position

fn into_js_owned<'_a>(value: &'_a mut Option<Self>) -> SerializedValue<'_a>

impl Serialize for Position

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<'de> Deserialize<'de> for Position

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.