area module

Functions for manipulating areas.

NOTE: All functions assume that BoundingBox and Position objects contain named keys - x and y for Position, and left_top and right_bottom for BoundingBox. Attempting to use these functions with the shorthand forms of these objects will result in a crash.

Usage

local area = require("__flib__.area")

Functions

ceil(self) Expand an area to its outer tile edges.
center(self) Calculate the centerpoint of the area.
center_on(self, center_point) Re-center the area on the given position.
contains_area(self, area) Check if the given area is within the area.
contains_position(self, position) Check if the given position is within the area.
corners(self) Add left-bottom and right-top corners to the area.
distance_to_nearest_edge(self, position) Find the distance between a point and the nearest edge of the given area.
expand(self, delta) Expand the given area by the given amount.
expand_to_contain_area(self, area) Expand the given area to contain the other area.
expand_to_contain_position(self, position) Expand the given area to contain the given position.
floor(self) Shrink an area to its inner tile edges.
from_position(position[, snap]) Create a 1x1 tile area from the given position.
from_shorthand(area) Create a proper area from a shorthanded area.
height(self) Calculate the height of the area.
iterate(self[, step=1]) Create an iterator of positions in the area from the left-top to the right-bottom.
load(area) Create an area object from a plain area.
move(self, delta) Move the given area by the given delta.
rotate(self) Rotate an area 90 degrees around its center.
strip(self) Create a new area table from the given area, removing any extra fields and metatables.
to_shorthand(self) Remove keys from the area to create a shorthanded area.
width(self) Calculate the width of an area.

Functions

# ceil(self)

Expand an area to its outer tile edges.

Parameters:
# center(self)

Calculate the centerpoint of the area.

Parameters: Returns:
  • (Position) The centerpoint of the area.
# center_on(self, center_point)

Re-center the area on the given position.

Parameters:
  • self : (BoundingBox) The area to modify.
  • center_point : (Position) The position to center the area on.
Returns:
# contains_area(self, area)

Check if the given area is within the area.

Parameters: Returns:
  • (boolean) Whether or not area is contained withing self.
# contains_position(self, position)

Check if the given position is within the area.

Parameters: Returns:
  • (boolean) Whether or not the position is contained within the area.
# corners(self)

Add left-bottom and right-top corners to the area.

Parameters: Returns:
  • (BoundingBox) The area with added left_bottom and right_top subtables.
# distance_to_nearest_edge(self, position)

Find the distance between a point and the nearest edge of the given area.

Parameters: Returns:
  • (double) The distance to the nearest edge of the area from the given position.
# expand(self, delta)

Expand the given area by the given amount.

Parameters:
  • self : (BoundingBox) The area to expand.
  • delta : (number) How far to expand the edges of the area.
Returns:
# expand_to_contain_area(self, area)

Expand the given area to contain the other area.

Parameters: Returns:
  • (BoundingBox) The modified area, containing the second area.
# expand_to_contain_position(self, position)

Expand the given area to contain the given position.

Parameters: Returns:
  • (BoundingBox) The modified area, containing the given position.
# floor(self)

Shrink an area to its inner tile edges.

Parameters: Returns:
# from_position(position[, snap])

Create a 1x1 tile area from the given position.

Parameters:
  • position : (Position)
  • snap : (boolean) If true, snap the created area to the tile edges the position is contained in (optional)
# from_shorthand(area)

Create a proper area from a shorthanded area.

Parameters: Returns:
# height(self)

Calculate the height of the area.

Parameters: Returns:
  • (number) The height of the area.
# iterate(self[, step=1])

Create an iterator of positions in the area from the left-top to the right-bottom.

The iterator function, when called, will return a Position that is within the area.

Parameters:
  • self : (BoundingBox) The area to iterate.
  • step : (number) The distance to move on each iteration. (default: 1)
Returns: Usage:
-- standard area
for position in area.iterate(my_area) do
  log(serpent.line(position))
end
-- area object
for position in MyArea:iterate() do
  log(serpent.line(position))
end
# load(area)

Create an area object from a plain area.

Doing this allows one to use area methods directly on an area "object" via the : operator. The area will be passed in as self to each function automatically.

Metatables do not persist across save/load, so when using area objects, this function must be called on them whenever they are retrieved from global or during on_load.

This function will also call area.from_shorthand if needed, to ensure that the returned area is properly defined.

Parameters: Returns: Usage:
-- create the area object
local MyArea = area.load(event_data.area)
-- use module methods directly on the object
local center_position = MyArea:center()
for position in MyArea:iterate(0.5) do
  log(serpent.line(position))
end
# move(self, delta)

Move the given area by the given delta.

Parameters:
  • self : (BoundingBox) The area to move.
  • delta : (Position) How far to move the area in each dimension.
Returns:
# rotate(self)

Rotate an area 90 degrees around its center.

Parameters: Returns:
# strip(self)

Create a new area table from the given area, removing any extra fields and metatables.

Parameters: Returns:
# to_shorthand(self)

Remove keys from the area to create a shorthanded area.

Parameters: Returns:
# width(self)

Calculate the width of an area.

Parameters: Returns:
  • (number) The width of the area.