Position module

Tools for working with <x,y> coordinates.

The tables passed into the Position functions are mutated in-place.

See also

• Area
• Concepts.Position
• defines.direction

Usage

local Position = require('stdlib/area/position')

Functions

add (pos1, pos2)	Adds two positions.
center (pos)	Gets the center position of a tile where the given position resides.
construct (x, y)	Creates a table representing the position from x and y.
copy (pos)	Creates a position that is a copy of the given position.
distance (pos1, pos2)	Calculates the Euclidean distance between two positions.
distance_squared (pos1, pos2)	Calculates the Euclidean distance squared between two positions, useful when sqrt is not needed.
equals (pos1, pos2)	Tests whether or not the two given positions are equal.
expand_to_area (pos, radius)	Expands a position to a square area.
increment (pos[, inc_x=0][, inc_y=0])	Increment a position each time it is called.
increment_closure ([new_inc_x=0][, new_inc_y=0])
manhattan_distance (pos1, pos2)	Calculates the manhatten distance between two positions.
new (pos_arr[, copy=false])	Returns a correctly formated position object.
next_direction (direction[, reverse=false][, eight_way=false])	Returns the next direction.
offset (pos, x, y)	Creates a position that is offset by x,y coordinates.
opposite_direction (direction)	Returns the opposite direction — adapted from Factorio util.lua.
subtract (pos1, pos2)	Subtracts two positions.
to_table ()	Deprecated
tostring (pos)	Converts a position to a string.
translate (pos, direction, distance)	Translates a position in the given direction.

Tables

Metamethods	Position tables are returned with these metamethods attached

Fields

epsilon	Machine Epsilon
immutable	By default position tables are mutated in place set this to true to make the tables immutable.

Functions

# add (pos1, pos2)

Adds two positions.

Parameters:

• pos1 : (Position) the first position
• pos2 : (Position) the second position

Returns:

• (Position) a new position → { x = pos1.x + pos2.x, y = pos1.y + pos2.y}

# center (pos)

Gets the center position of a tile where the given position resides.

Parameters:

• pos : (Position) the position which resides somewhere on a tile

Returns:

• (Position) the position at the center of the tile

# construct (x, y)

Creates a table representing the position from x and y.

Parameters:

• x : (number) x-position
• y : (number) y-position

Returns:

• (Position)

# copy (pos)

Creates a position that is a copy of the given position.

Parameters:

• pos : (Position) the position to copy

Returns:

• (Position) a new position with values identical to the given position

# distance (pos1, pos2)

Calculates the Euclidean distance between two positions.

Parameters:

• pos1 : (Position) the first position
• pos2 : (Position) the second position

Returns:

• (number) the euclidean distance

# distance_squared (pos1, pos2)

Calculates the Euclidean distance squared between two positions, useful when sqrt is not needed.

Parameters:

• pos1 : (Position) the first position
• pos2 : (Position) the second position

Returns:

• (number) the square of the euclidean distance

# equals (pos1, pos2)

Tests whether or not the two given positions are equal.

Parameters:

• pos1 : (Position) the first position
• pos2 : (Position) the second position

Returns:

• (boolean) true if positions are equal

# expand_to_area (pos, radius)

Expands a position to a square area.

Parameters:

• pos : (Position) the position to expand into an area
• radius : (number) half of the side length of the area

Returns:

• (BoundingBox) the area

# increment (pos[, inc_x=0][, inc_y=0])

Increment a position each time it is called.

This can be used to increment or even decrement a position quickly.

Do not store function closures in the global object; use them in the current tick.

Parameters:

• pos : (Position) the position to start with
• inc_x : (number) optional increment x by this amount (default: 0)
• inc_y : (number) optional increment y by this amount (default: 0)

Returns:

• (function) increment_closure a function closure that returns an incremented position

Usage:

local next_pos = Position.increment({0,0})
for i = 1, 5 do next_pos(0,1) -- returns {x = 0, y = 1} {x = 0, y = 2} {x = 0, y = 3} {x = 0, y = 4} {x = 0, y = 5}

local next_pos = Position.increment({0, 0}, 1)
next_pos() -- returns {1, 0}
next_pos(0, 5) -- returns {1, 5}
next_pos(nil, 5) -- returns {2, 10}

local next_pos = Position.increment({0, 0}, 0, 1)
surface.create_entity{name = 'flying-text', text = 'text', position = next_pos()}
surface.create_entity{name = 'flying-text', text = 'text', position = next_pos()} -- creates two flying text entities 1 tile apart

# increment_closure ([new_inc_x=0][, new_inc_y=0])

A closure which the increment function returns.

Do not call this directly and do not store this in the global object.

Parameters:

• new_inc_x : (number) (default: 0)
• new_inc_y : (number) (default: 0)

Returns:

• (Position) the incremented position

See also:

• increment

# manhattan_distance (pos1, pos2)

Calculates the manhatten distance between two positions.

Parameters:

• pos1 : (Position) the first position
• pos2 : (Position) the second position

Returns:

• (number) the manhatten distance

See also:

• Taxicab geometry (manhatten distance)

# new (pos_arr[, copy=false])

Returns a correctly formated position object.

Parameters:

• pos_arr : (array) the position to convert
• copy : (boolean) return a new copy (default: false)

Returns:

• (Position) itself or a new correctly formated position with metatable

Usage:

Position.new({0, 0}) -- returns {x = 0, y = 0}

# next_direction (direction[, reverse=false][, eight_way=false])

Returns the next direction.

For entities that only support two directions, see opposite_direction.

Parameters:

• direction : (defines.direction) the starting direction
• reverse : (boolean) true to get the next direction in counter-clockwise fashion, false otherwise (default: false)
• eight_way : (boolean) true to get the next direction in 8-way (note: not many prototypes support 8-way) (default: false)

Returns:

• (defines.direction) the next direction

# offset (pos, x, y)

Creates a position that is offset by x,y coordinates.

Parameters:

• pos : (Position) the position to offset
• x : (number) the amount to offset the position on the x-axis
• y : (number) the amount to offset the position on the y-axis

Returns:

• (Position) a new position, offset by the x,y coordinates

# opposite_direction (direction)

Returns the opposite direction — adapted from Factorio util.lua.

Parameters:

• direction : (defines.direction) the direction

Returns:

• (defines.direction) the opposite direction

# subtract (pos1, pos2)

Subtracts two positions.

Parameters:

• pos1 : (Position) the first position
• pos2 : (Position) the second position

Returns:

• (Position) a new position → { x = pos1.x - pos2.x, y = pos1.y - pos2.y }

# to_table ()

Deprecated

See also:

• Position.new

# tostring (pos)

Converts a position to a string.

Parameters:

• pos : (Position) the position to convert

Returns:

• (string) string representation of the position

# translate (pos, direction, distance)

Translates a position in the given direction.

Parameters:

• pos : (Position) the position to translate
• direction : (defines.direction) the direction of translation
• distance : (number) distance of the translation

Returns:

• (Position) a new translated position

Tables

# Metamethods

Position tables are returned with these metamethods attached

Fields:

• __index : If key is not found, see if there is one availble in the Position module.
• __tostring : Returns a string representation of the position
• __add : Adds two position together.
• __sub : Subtracts one position from another.
• __eq : Are two positions the same.
• __lt : Is position1 less than position2.
• __le : Is position1 less than or equal to position2.
• __concat : calls tostring on both sides of concact.

Fields

# epsilon

Machine Epsilon

See also:

• Machine_epsilon

# immutable

By default position tables are mutated in place set this to true to make the tables immutable.