Factorio Stdlib

Area module

Tools for working with bounding boxes.

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

See also

• Position
• Concepts.BoundingBox
• Concepts.Position

Usage

local Area = require('stdlib/area/area')

Functions

Tables

Fields

Functions

# adjust (area, vector)

Adjust an area by shrinking or expanding.

Imagine pinching & holding with fingers the top-left & bottom-right corners of a 2D box and pulling outwards to expand and pushing inwards to shrink the box.

Parameters:

• area : (BoundingBox) the area to adjust
• vector : (Vector) the vectors to use

Returns:

• (BoundingBox) the adjusted bounding box

Usage:

local area = Area.adjust({{-2, -2}, {2, 2}}, {4, -1})
 -- returns {left_top = {x = -6, y = -1}, right_bottom = {x = 6, y = 1}}

# center (area)

Calculates the center of the area and returns the position.

Parameters:

• area : (BoundingBox) the area

Returns:

• (Position) the center of the area

# compare (area1, area2)

Returns true if two areas are the same.

Parameters:

• area1 : (BoundingBox)
• area2 : (BoundingBox)

Returns:

• (boolean) true if areas are the same

# construct (x1, y1, x2, y2)

Creates an area from the two positions p1 and p2.

Parameters:

• x1 : (number) x-position of left_top, first position
• y1 : (number) y-position of left_top, first position
• x2 : (number) x-position of right_bottom, second position
• y2 : (number) y-position of right_bottom, second position

Returns:

• (BoundingBox) the area in a table format

# copy (area)

Creates an area that is a copy of the given area.

Parameters:

• area : (BoundingBox) the position to copy

Returns:

• (BoundingBox) a new area that is a copy of the passed area

# equals (area1, area2)

Compares the size of two areas.

note: The shame of either area is not taking into consideration, see Area.compare

Parameters:

• area1 : (BoundingBox)
• area2 : (BoundingBox)

Returns:

• (boolean) is area1 the same size as area2

# expand (area, amount)

Expands the size of an area by the given amount.

Parameters:

• area : (BoundingBox) the area
• amount : (number or Vector) to expand each edge of the area outwards by

Returns:

• (BoundingBox) the area expanded by amount

See also:

• Area.shrink

# inside (area, pos)

Tests if a position {x, y} is located in an area (including the border).

Parameters:

• area : (BoundingBox) the search area
• pos : (Position) the position to check

Returns:

• (boolean) true if the position is located in the area

# iterate (area)

Iterates an area.

Parameters:

• area : (BoundingBox) the area to iterate

Returns:

• (function) an iterator

Usage:

for x,y in Area.iterate({{0, -5}, {3, -3}}) do
...
end

# less_than (area1, area2)

Is area1 smaller in size than area2

Parameters:

• area1 : (BoundingBox)
• area2 : (BoundingBox)

Returns:

• (boolean) is area1 less than area2 in size

# new (area_arr, copy)

Converts an area in either array or table format to an area with a metatable.

Returns itself if it already has a metatable

Parameters:

• area_arr : (BoundingBox) the area to convert
• copy : (boolean)

Returns:

• (BoundingBox) a converted area

# normalize (area)

Normalizes the given area.

• Swaps the values between right_bottom.x & left_top.x IF right_bottom.x < left_top.x
• Swaps the values between right_bottom.y & left_top.y IF right_bottom.y < left_top.y

Essentially, the normalization process constructs a new area out of the swapped coordinates.

Parameters:

• area : (BoundingBox) the area to normalize

Returns:

• (BoundingBox) the normalized area

# offset (area, pos)

Offsets the area by the {x, y} values.

Parameters:

• area : (BoundingBox) the area to offset
• pos : (Position) the position to which the area will offset

Returns:

• (BoundingBox) the area offset by the position

# rotate (area)

Rotate an area such that its value of the width becomes the height, and its value of the height becomes the width.

Parameters:

• area : (BoundingBox) the area to rotate

Returns:

• (BoundingBox) the rotated area

# round_to_integer (area)

Rounds down the xy-values in area.left_top and rounds up the xy-values in area.right_bottom.

Parameters:

• area : (BoundingBox) the area to round

Returns:

• (BoundingBox) the area with rounded positions

Usage:

local position1 = {x = 1.5, y = 1.5}
local position2 = {x = 1.5, y = 1.5}
local area = {left_top = position1, right_bottom = position2}
Area.round_to_integer(area) --> {left_top = {x = 1, y = 1}, right_bottom = {x = 2, y = 2}}

# shrink (area, amount)

Shrinks the area by the given amount.

The area shrinks inwards from top-left towards the bottom-right, and from bottom-right towards the top-left.

Parameters:

• area : (BoundingBox) the area to shrink
• amount : (number or Vector) the amount to shrink

Returns:

• (BoundingBox) the area reduced by amount

# size (area)

Gets the properties of the given area.

This function returns a total of four values that represent the properties of the given area.

Parameters:

• area : (BoundingBox) the area from which to get the size

Returns:

• (number) the size of the area — (width × height)
• (number) the width of the area
• (number) the height of the area
• (number) the perimeter of the area — (2 × (width + height))

# spiral_iterate (area)

Iterates the given area in a spiral as depicted below, from innermost to the outermost location.

Parameters:

• area : (BoundingBox) the area on which to perform a spiral iteration

Returns:

• (function) an iterator

Usage:

for x, y in Area.spiral_iterate({{-2, -1}, {2, 1}}) do
print('(' .. x .. ', ' .. y .. ')')
end
prints: (0, 0) (1, 0) (1, 1) (0, 1) (-1, 1) (-1, 0) (-1, -1) (0, -1) (1, -1) (2, -1) (2, 0) (2, 1) (-2, 1) (-2, 0) (-2, -1)

# tile_center_points (area)

Gets the center positions of the tiles where the given area's two positions reside.

Parameters:

• area : (BoundingBox) the area to examine

Returns:

• (BoundingBox) the area with its two positions at the center of the tiles in which they reside

# to_collision_area (entity)

Deprecated see LuaEntity.bounding_box
Converts an entity and its collision_box to the area around it.

Parameters:

• entity : (LuaEntity) the entity to convert to an area

Returns:

• (BoundingBox)

# to_selection_area (entity)

Converts an entity and its selection_box to the area around it.

Parameters:

• entity : (LuaEntity) to convert to an area

Returns:

• (BoundingBox)

# to_table ()

Deprecated

See also:

• Area.new

# tostring (area)

Converts an area to a string.

Parameters:

• area : (BoundingBox) the area to convert

Returns:

• (string) the string representation of the area

# translate (area, direction, distance)

Translates an area in the given direction.

Parameters:

• area : (BoundingBox) the area to translate
• direction : (defines.direction) the direction of translation
• distance : (number) the distance of the translation

Returns:

• (BoundingBox) the area translated

Tables

# Metamethods

Area tables are returned with these Metamethods attached.

Fields:

• __index : If key is not found, see if there is one availble in the Area module.
• __add : Will expand the area by the number or vector on the RHS.
• __sub : Will shrink the area by the number or vector on the RHS.
• __tostring : Will print a string representation of the area.
• __eq : Is the size of area1 the same as area2.
• __lt : is the size of area1 less than area2.
• __len : The size of the area.
• __concat : calls tostring on both sides of concact.

Fields

# immutable

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