StdLib.Area

Tools for working with bounding boxes.

Methods61

function Area.__call(_: any, ...: any) -> nil

function Area.new(area: BoundingBox) -> StdLib.Area

Converts an area in either array or table format to an area with a metatable. Returns itself if it already has a metatable

function Area.construct(...: number) -> StdLib.Area

Creates an area from number parameters.

function Area.load(area: BoundingBox) -> StdLib.Area

Loads the metatable into the passed Area without creating a new one.

function Area.from_string(area_string: string) -> StdLib.Area

Converts an area string to an area.

function Area.from_key(area_string: string) -> StdLib.Area

Converts a string key area to an area.

function Area.store(area: BoundingBox) -> BoundingBox

Stores the area for recall later, not deterministic. Only the last area stored is saved.

function Area.recall(area: BoundingBox) -> BoundingBox

Recalls the stored area.

Parameters

areaBoundingBox

Returns

BoundingBox: the stored area

function Area.normalize(area: BoundingBox) -> BoundingBox

Normalizes the given area. <ul> <li>Swaps the values between right_bottom.x & left_top.x IF right_bottom.x < left_top.x <li>Swaps the values between right_bottom.y & left_top.y IF right_bottom.y < left_top.y </ul>

Parameters

areaBoundingBox: the area to normalize

Returns

BoundingBox: a new normalized area

function Area.normalized(area: BoundingBox) -> area BoundingBox

Normalize an area in place.

Parameters

areaBoundingBox: the area to normalize

Returns

areaBoundingBox: The area normalized in place

function Area.from_pixels(area: BoundingBox) -> BoundingBox

Convert area from pixels.

function Area.to_pixels(area: BoundingBox) -> BoundingBox

Convert area to pixels.

function Area.round(area: BoundingBox) -> BoundingBox

Rounds an areas points to its closest integer.

function Area.ceil(area: BoundingBox) -> BoundingBox

Ceils an area by increasing the size of the area outwards

Parameters

areaBoundingBox: the area to round

Returns

BoundingBox

function Area.floor(area: BoundingBox) -> BoundingBox

Floors an area by decreasing the size of the area inwards.

Parameters

areaBoundingBox: the area to round

Returns

BoundingBox

function Area.center_points(area: BoundingBox) -> BoundingBox

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

Parameters

areaBoundingBox

Returns

BoundingBox: the area with its two positions at the center of the tiles in which they reside

function Area.corners(area: BoundingBox) -> area StdLib.Area.BoundingBoxCorners

Adds the left-bottom and right-top corner positions to a bounding box.

function Area.flip(area: BoundingBox) -> BoundingBox

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

Parameters

areaBoundingBox: the area to flip

Returns

BoundingBox: the fliped area

function Area.non_zero(area: BoundingBox, amount: number | Vector) -> the BoundingBox

Return a non zero sized area by expanding if needed

Parameters

areaBoundingBox: the area to check
amountnumber | Vector: the amount to expand

Returns

theBoundingBox: area

function Area.to_diameter(area: BoundingBox, diameter: number) -> BoundingBox

Returns the area to the diameter from left_top

function Area.min(area: BoundingBox, area2: BoundingBox) -> the BoundingBox

Returns the smallest sized area.

Parameters

areaBoundingBox
area2BoundingBox

Returns

theBoundingBox: smallest area

function Area.max(area: BoundingBox, area2: BoundingBox) -> the BoundingBox

Returns the largest sized area.

Parameters

areaBoundingBox
area2BoundingBox

Returns

theBoundingBox: largest area

function Area.shrink(area: BoundingBox, amount: number | Vector) -> the BoundingBox

Shrinks the area inwards by the given amount. The area shrinks inwards from top-left towards the bottom-right, and from bottom-right towards the top-left.

Parameters

areaBoundingBox: the area to shrink
amountnumber | Vector: the amount to shrink

Returns

theBoundingBox: area reduced by amount

function Area.expand(area: BoundingBox, amount: number | Vector) -> the BoundingBox

Expands the area outwards by the given amount.

Parameters

areaBoundingBox: the area
amountnumber | Vector: to expand each edge of the area outwards by

Returns

theBoundingBox: area expanded by amount @see Area.shrink

function Area.adjust(area: BoundingBox, amount: number | Vector) -> BoundingBox

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. @usage local area = Area.adjust({{-2, -2}, {2, 2}}, {4, -1}) -- returns {lefttop = {x = -6, y = -1}, rightbottom = {x = 6, y = 1}}

Parameters

areaBoundingBox: the area to adjust
amountnumber | Vector: the vectors to use

Returns

BoundingBox: adjusted bounding box

function Area.offset(area: BoundingBox, pos: MapPosition) -> BoundingBox

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

function Area.translate(area: BoundingBox, direction: defines.direction, distance: number) -> BoundingBox

Translates an area in the given direction.

Parameters

areaBoundingBox: the area to translate
directiondefines.direction: the direction of translation
distancenumber: the distance of the translation

Returns

BoundingBox: the area translated

function Area.to_surface_size(area: BoundingBox, surface: LuaSurface) -> BoundingBox

Set an area to the whole size of the surface.

function Area.shrink_to_surface_size(area: BoundingBox, surface: LuaSurface) -> BoundingBox

Shrinks an area to the size of the surface if it is bigger.

function Area.to_chunk_coords(area: BoundingBox) -> BoundingBox

Return the chunk coordinates from an area.

Parameters

areaBoundingBox

Returns

BoundingBox: Chunk position coordinates

function Area.center(area: BoundingBox) -> StdLib.Area.Position

Calculates the center of the area and returns the position.

function Area.to_key(area: BoundingBox) -> string

Return a suitable string for using as a table key

function Area.to_string(area: BoundingBox) -> string

Converts an area to a string.

Parameters

areaBoundingBox: the area to convert

Returns

string: the string representation of the area

function Area.to_string_xy(area: BoundingBox) -> the string

Converts an area to an ltx, lty / rbx, rby string.

Parameters

areaBoundingBox: the area to convert

Returns

thestring: string representation of the area

function Area.is_zero(area: BoundingBox) -> boolean

Is this a non zero sized area

function Area.is_normalized(area: BoundingBox) -> boolean

Is the area normalized.

function Area.valid(area: BoundingBox) -> boolean

Is the area non-zero and normalized.

function Area.is_simple_area(area: BoundingBox) -> boolean

Is this a simple area. {{num, num}, {num, num}}

function Area.is_complex_area(area: BoundingBox) -> boolean

Is this a complex area {lefttop = {x = num, y = num}, rightbottom = {x = num, y = num}}

function Area.is_area(area: BoundingBox) -> boolean

Is this and area of any kind.

function Area.is_Area(area: BoundingBox) -> boolean

Does the area have the class attached

function Area.unpack(area: BoundingBox) -> (lt.x number, lt.y number, rb.x number, rb.y number, orientation float)

Unpack an area into a tuple.

function Area.unpack_positions(area: BoundingBox) -> (left_top MapPosition, right_bottom MapPosition)

Unpack an area into a tuple of position tables.

function Area.pack(area: BoundingBox) -> array BoundingBox

Pack an area into an array.

function Area.pack_positions(area: BoundingBox) -> BoundingBox

Pack an area into a simple bounding box array

Parameters

areaBoundingBox

Returns

BoundingBox: simple array

function Area.size(area: BoundingBox) -> (the number, the number, the number, the number)

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

Parameters

areaBoundingBox: the area from which to get the size

Returns

thenumber: size of the area — (width × height)
thenumber: width of the area
thenumber: height of the area
thenumber: perimeter of the area — (2 × (width + height))

function Area.rectangle(area: BoundingBox) -> (left_top.x number, left_top.y number, width number, height number)

Return the rectangle.

function Area.width(area: BoundingBox) -> width number

The width of the area.

function Area.height(area: BoundingBox) -> width number

The height of an area.

function Area.dimensions(area: BoundingBox) -> (width number, height number)

The dimensions of an area.

function Area.perimeter(area: BoundingBox) -> width number

The Perimiter of an area.

function Area.equals(area1: BoundingBox, area2: BoundingBox) -> boolean

Returns true if two areas are the same.

Parameters

area1BoundingBox
area2BoundingBox

Returns

boolean: true if areas are the same

function Area.less_than(area1: BoundingBox, area2: BoundingBox) -> boolean

Is area1 smaller in size than area2

Parameters

area1BoundingBox
area2BoundingBox

Returns

boolean: is area1 less than area2 in size

function Area.less_than_eq(area1: BoundingBox, area2: BoundingBox) -> boolean

Is area1 smaller or equal in size to area2.

Parameters

area1BoundingBox
area2BoundingBox

Returns

boolean: is area1 less than or equal to area2 in size @local

function Area.collides(area1: BoundingBox, area2: BoundingBox) -> boolean

Does either area overlap/collide with the other area.

function Area.contains_positions(area: BoundingBox, positions: MapPosition.struct[]) -> boolean

Are the passed positions all located in an area.

function Area.contains_areas(area: BoundingBox, areas: BoundingBox[]) -> boolean

Are all passed areas completly inside an area.

Parameters

areaBoundingBox
areasBoundingBox[]: array of BoundingBox

Returns

boolean

function Area.collides_areas(area: BoundingBox, areas: BoundingBox[]) -> boolean

Do all passed areas collide with an area.

Parameters

areaBoundingBox
areasBoundingBox[]: array of BoundingBox

Returns

boolean

function Area.iterate(area: BoundingBox, as_position: nil | boolean, inside: nil | boolean, step: nil | number) -> function

Iterates an area. @usage local area = {{0, -5}, {3, -3}} for x,y in Area.iterate(area) do -- return x, y values end for position in Area.iterate(area, true) do -- returns a position object end -- Iterates from lefttop.x to rightbottom.x then goes down y until right_bottom.y

Parameters

areaBoundingBox: the area to iterate
as_positionnil | boolean: [opt=false] return a position object
insidenil | boolean: [opt=false] only return values that contain the areas tiles
stepnil | number: [opt=1] size to increment

Returns

function: an iterator

function Area.spiral_iterate(area: BoundingBox, as_position: nil | boolean) -> (fun(state: BoundingBox, control: any) -> ...number | StdLib.Area.Position | nil, area BoundingBox, control number)

Iterates the given area in a spiral as depicted below, from innermost to the outermost location. <p>! @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)

Parameters

areaBoundingBox: The area to iterate.
as_positionnil | boolean: Return a position object instead of x and y coordinates.

Returns

fun(state: BoundingBox, control: any) -> ...number | StdLib.Area.Position | nil
areaBoundingBox
controlnumber

function Area.Positions(area, inside, step) -> table

Fields5

Area.left_top : StdLib.Area.Position

Area.right_bottom : StdLib.Area.Position

Area.orientation : RealOrientation | nil

Area.__class: string = "Area"

Area.__index : StdLib.Core