Table of Contents

Class BlockPos

Namespace
Vintagestory.API.MathTools
Assembly
VintagestoryAPI.dll

A useful data structure when operating with block postions.
Valuable Hint: Make use of Copy() or the XXXCopy() variants where needed. A common pitfall is writing code like: BlockPos abovePos = pos.Up(); - with this code abovePos and pos will reference to the same object!

[ProtoContract]
public class BlockPos : IEquatable<BlockPos>, IVec3
Inheritance
BlockPos
Implements
Derived
Inherited Members
Extension Methods

Constructors

BlockPos() 

[Obsolete("Not dimension-aware. Use new BlockPos(dimensionId) where possible")]
public BlockPos()

BlockPos(int) 

public BlockPos(int dim)

Parameters

dim int

BlockPos(int, int, int) 

[Obsolete("Not dimension-aware. Use overload with a dimension parameter instead")]
public BlockPos(int x, int y, int z)

Parameters

x int
y int
z int

BlockPos(int, int, int, int) 

public BlockPos(int x, int y, int z, int dim)

Parameters

x int
y int
z int
dim int

BlockPos(Vec3i) 

[Obsolete("Not dimension-aware. Use overload with a dimension parameter instead")]
public BlockPos(Vec3i vec)

Parameters

vec Vec3i

BlockPos(Vec3i, int) 

public BlockPos(Vec3i vec, int dim)

Parameters

vec Vec3i
dim int

BlockPos(Vec4i)

Note - for backwards compatibility, this is not dimension-aware; explicitly set the dimension in the resulting BlockPos if you need to

public BlockPos(Vec4i vec)

Parameters

vec Vec4i

Fields

DimensionBoundary 

public const int DimensionBoundary = 32768

Field Value

int

X 

[ProtoMember(1)]
public int X

Field Value

int

Y 

public int Y

Field Value

int

Z 

[ProtoMember(3)]
public int Z

Field Value

int

dimension 

public int dimension

Field Value

int

Properties

AsVec3i 

[JsonIgnore]
public Vec3i AsVec3i { get; }

Property Value

Vec3i

InternalY 

[ProtoMember(2)]
public int InternalY { get; set; }

Property Value

int

this[int]

0 = x, 1 = y, 2 = z

public int this[int i] { get; set; }

Parameters

i int

Property Value

int

Methods

Add(int, int, int)

Offsets the position by given xyz

public BlockPos Add(int dx, int dy, int dz)

Parameters

dx int
dy int
dz int

Returns

BlockPos

Add(float, float, float)

Offsets the position by given xyz

public BlockPos Add(float dx, float dy, float dz)

Parameters

dx float
dy float
dz float

Returns

BlockPos

Add(BlockFacing, int)

Offsets the position into the direction of given block face

public BlockPos Add(BlockFacing facing, int length = 1)

Parameters

facing BlockFacing
length int

Returns

BlockPos

Add(BlockPos)

Offsets the position by given xyz vector

public BlockPos Add(BlockPos pos)

Parameters

pos BlockPos

Returns

BlockPos

Add(FastVec3i)

Offsets the position by given xyz vector

public BlockPos Add(FastVec3i vector)

Parameters

vector FastVec3i

Returns

BlockPos

Add(Vec3i)

Offsets the position by given xyz vector

public BlockPos Add(Vec3i vector)

Parameters

vector Vec3i

Returns

BlockPos

AddCopy(int)

Creates a copy of this blocks position and offsets it by given xyz

public BlockPos AddCopy(int xyz)

Parameters

xyz int

Returns

BlockPos

AddCopy(int, int, int)

Creates a copy of this blocks position and offsets it by given xyz

public BlockPos AddCopy(int dx, int dy, int dz)

Parameters

dx int
dy int
dz int

Returns

BlockPos

AddCopy(float, float, float)

Creates a copy of this blocks position and offsets it by given xyz

public BlockPos AddCopy(float dx, float dy, float dz)

Parameters

dx float
dy float
dz float

Returns

BlockPos

AddCopy(BlockFacing)

Creates a copy of this blocks position and offsets it in the direction of given block face

public BlockPos AddCopy(BlockFacing facing)

Parameters

facing BlockFacing

Returns

BlockPos

AddCopy(BlockFacing, int)

Creates a copy of this blocks position and offsets it in the direction of given block face

public BlockPos AddCopy(BlockFacing facing, int length)

Parameters

facing BlockFacing
length int

Returns

BlockPos

AddCopy(Vec3i)

Creates a copy of this blocks position and offsets it by given xyz

public BlockPos AddCopy(Vec3i vector)

Parameters

vector Vec3i

Returns

BlockPos

Copy()

Creates a copy of this blocks position

public virtual BlockPos Copy()

Returns

BlockPos

CopyAndCorrectDimension()

Creates a copy of this blocks position, obtaining the correct dimension value from the Y value

public virtual BlockPos CopyAndCorrectDimension()

Returns

BlockPos

CreateFromBytes(BinaryReader) 

public static BlockPos CreateFromBytes(BinaryReader reader)

Parameters

reader BinaryReader

Returns

BlockPos

DistanceSqTo(double, double, double)

Returns the squared Euclidean distance to between this and given position. Dimension aware

public float DistanceSqTo(double x, double y, double z)

Parameters

x double
y double
z double

Returns

float

DistanceSqToNearerEdge(double, double, double)

Returns the squared Euclidean distance between the nearer edge of this blockpos (assumed 1 x 0.75 x 1 cube) and given position The 0.75 offset is because the "heat source" is likely to be above the base position of this block: it's approximate Note this is dimension unaware

public double DistanceSqToNearerEdge(double x, double y, double z)

Parameters

x double
y double
z double

Returns

double

DistanceTo(double, double, double)

Returns the Euclidean distance to between this and given position. Note this is dimension unaware

public float DistanceTo(double x, double y, double z)

Parameters

x double
y double
z double

Returns

float

DistanceTo(BlockPos)

Returns the Euclidean distance to between this and given position. Note if dimensions are different returns maximum value (i.e. infinite)

public float DistanceTo(BlockPos pos)

Parameters

pos BlockPos

Returns

float

DivCopy(int)

Creates a copy of this blocks position and divides it by given factor

public BlockPos DivCopy(int factor)

Parameters

factor int

Returns

BlockPos

Down(int)

Move the position vertically down

public BlockPos Down(int dy = 1)

Parameters

dy int

Returns

BlockPos

DownCopy(int)

Creates a copy of this blocks position with the y-position adjusted by -length

public BlockPos DownCopy(int length = 1)

Parameters

length int

Returns

BlockPos

East() 

public BlockPos East()

Returns

BlockPos

EastCopy(int)

Creates a copy of this blocks position with the x-position adjusted by +length

public BlockPos EastCopy(int length = 1)

Parameters

length int

Returns

BlockPos

Equals(int, int, int) 

public bool Equals(int x, int y, int z)

Parameters

x int
y int
z int

Returns

bool

Equals(object)

Determines whether the specified object is equal to the current object.

public override bool Equals(object obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

Equals(BlockPos)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(BlockPos other)

Parameters

other BlockPos

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

FacingFrom(BlockPos)

Returns the direction moved from the other blockPos, to get to this BlockPos

public BlockFacing FacingFrom(BlockPos other)

Parameters

other BlockPos

Returns

BlockFacing

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

HorDistanceSqTo(double, double)

Returns the squared Euclidean horizontal distance to between this and given position Note this is dimension unaware

public float HorDistanceSqTo(double x, double z)

Parameters

x double
z double

Returns

float

HorizontalManhattenDistance(BlockPos)

Returns the manhatten distance to given position

public int HorizontalManhattenDistance(BlockPos pos)

Parameters

pos BlockPos

Returns

int

InRangeHorizontally(int, int, int)

Returns true if the specified x,z is within a box the specified range around this position Note this is dimension unaware

public bool InRangeHorizontally(int x, int z, int range)

Parameters

x int
z int
range int

Returns

bool

ManhattenDistance(int, int, int)

Returns the manhatten distance to given position Note this is dimension unaware

public int ManhattenDistance(int x, int y, int z)

Parameters

x int
y int
z int

Returns

int

ManhattenDistance(BlockPos)

Returns the manhatten distance to given position

public int ManhattenDistance(BlockPos pos)

Parameters

pos BlockPos

Returns

int

North() 

public BlockPos North()

Returns

BlockPos

NorthCopy(int)

Creates a copy of this blocks position with the z-position adjusted by -length

public BlockPos NorthCopy(int length = 1)

Parameters

length int

Returns

BlockPos

Offset(BlockFacing)

Offsets the position into the direction of given block face

public BlockPos Offset(BlockFacing facing)

Parameters

facing BlockFacing

Returns

BlockPos

Set(int, int, int)

Sets XYZ to new values - not dimension aware (but existing dimension will be preserved) - use SetAndCorrectDimension() for dimension awareness

public BlockPos Set(int x, int y, int z)

Parameters

x int
y int
z int

Returns

BlockPos

Set(float, float, float) 

public BlockPos Set(float x, float y, float z)

Parameters

x float
y float
z float

Returns

BlockPos

Set(BlockPos) 

public BlockPos Set(BlockPos blockPos)

Parameters

blockPos BlockPos

Returns

BlockPos

Set(FastVec3i) 

public BlockPos Set(FastVec3i pos)

Parameters

pos FastVec3i

Returns

BlockPos

Set(Vec3d)

Not dimension aware (but existing dimension in this BlockPos will be preserved) - use SetAndCorrectDimension() for dimension awareness

public BlockPos Set(Vec3d origin)

Parameters

origin Vec3d

Returns

BlockPos

Set(Vec3i) 

public BlockPos Set(Vec3i pos)

Parameters

pos Vec3i

Returns

BlockPos

SetAndCorrectDimension(int, int, int)

Dimension aware version of Set() - use this if there is a dimension embedded in the y coordinate (e.g. y == 65536+ for dimension 2)

public BlockPos SetAndCorrectDimension(int x, int y, int z)

Parameters

x int
y int
z int

Returns

BlockPos

SetAndCorrectDimension(Vec3d)

Dimension aware version of Set() - use this if the Vec3d has the dimension embedded in the Y coordinate (e.g. Y == 65536+ for dimension 2)

public BlockPos SetAndCorrectDimension(Vec3d origin)

Parameters

origin Vec3d

Returns

BlockPos

SetAndEquals(int, int, int)

Sets this BlockPos to the x,y,z values given, and returns a boolean stating if the existing values were already equal to x,y,z

public bool SetAndEquals(int x, int y, int z)

Parameters

x int
y int
z int

Returns

bool

Returns true if the BlockPos already held these exact x, y, z values (the .Set operation has not changed anything)
Returns false if the .Set operation caused a change to the BlockPos

SetDimension(int) 

public BlockPos SetDimension(int dim)

Parameters

dim int

Returns

BlockPos

South() 

public BlockPos South()

Returns

BlockPos

SouthCopy(int)

Creates a copy of this blocks position with the z-position adjusted by +length

public BlockPos SouthCopy(int length = 1)

Parameters

length int

Returns

BlockPos

Sub(int, int, int)

Substract a position => you'll have the manhatten distance

public BlockPos Sub(int x, int y, int z)

Parameters

x int
y int
z int

Returns

BlockPos

Sub(BlockPos)

Substract a position => you'll have the manhatten distance

public BlockPos Sub(BlockPos pos)

Parameters

pos BlockPos

Returns

BlockPos

SubCopy(int, int, int) 

public BlockPos SubCopy(int x, int y, int z)

Parameters

x int
y int
z int

Returns

BlockPos

SubCopy(BlockPos)

Substract a position => you'll have the manhatten distance

public BlockPos SubCopy(BlockPos pos)

Parameters

pos BlockPos

Returns

BlockPos

ToBytes(BinaryWriter) 

public void ToBytes(BinaryWriter writer)

Parameters

writer BinaryWriter

ToLocalPosition(ICoreAPI)

Convert a block position to coordinates relative to the world spawn position. Note this is dimension unaware

public Vec3i ToLocalPosition(ICoreAPI api)

Parameters

api ICoreAPI

Returns

Vec3i

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

ToVec3d()

Creates a new instance of a Vec3d initialized with this position Note this is dimension unaware

public Vec3d ToVec3d()

Returns

Vec3d

ToVec3f() 

public Vec3f ToVec3f()

Returns

Vec3f

ToVec3i()

Creates a new instance of a Vec3i initialized with this position Note this is dimension unaware

public Vec3i ToVec3i()

Returns

Vec3i

Up(int)

Move the position vertically up

public BlockPos Up(int dy = 1)

Parameters

dy int

Returns

BlockPos

UpCopy(int)

Creates a copy of this blocks position with the y-position adjusted by +length

public BlockPos UpCopy(int length = 1)

Parameters

length int

Returns

BlockPos

Walk(BlockPos, BlockPos, Vec3i, Action<int, int, int>) 

public static void Walk(BlockPos startPos, BlockPos untilPos, Vec3i mapSizeForClamp, Action<int, int, int> onpos)

Parameters

startPos BlockPos
untilPos BlockPos
mapSizeForClamp Vec3i
onpos Action<int, int, int>

West() 

public BlockPos West()

Returns

BlockPos

WestCopy(int)

Creates a copy of this blocks position with the x-position adjusted by -length

public BlockPos WestCopy(int length = 1)

Parameters

length int

Returns

BlockPos

Operators

operator +(BlockPos, int) 

public static BlockPos operator +(BlockPos left, int right)

Parameters

left BlockPos
right int

Returns

BlockPos

operator +(BlockPos, BlockPos) 

public static BlockPos operator +(BlockPos left, BlockPos right)

Parameters

left BlockPos
right BlockPos

Returns

BlockPos

operator /(BlockPos, int) 

public static BlockPos operator /(BlockPos left, int right)

Parameters

left BlockPos
right int

Returns

BlockPos

operator ==(BlockPos, BlockPos) 

public static bool operator ==(BlockPos left, BlockPos right)

Parameters

left BlockPos
right BlockPos

Returns

bool

operator !=(BlockPos, BlockPos) 

public static bool operator !=(BlockPos left, BlockPos right)

Parameters

left BlockPos
right BlockPos

Returns

bool

operator *(int, BlockPos) 

public static BlockPos operator *(int left, BlockPos right)

Parameters

left int
right BlockPos

Returns

BlockPos

operator *(BlockPos, int) 

public static BlockPos operator *(BlockPos left, int right)

Parameters

left BlockPos
right int

Returns

BlockPos

operator -(BlockPos, int) 

public static BlockPos operator -(BlockPos left, int right)

Parameters

left BlockPos
right int

Returns

BlockPos

operator -(BlockPos, BlockPos) 

public static BlockPos operator -(BlockPos left, BlockPos right)

Parameters

left BlockPos
right BlockPos

Returns

BlockPos