Area.Surface module

For working with surfaces.

Surfaces are the “domain” of the world.

See also

• LuaSurface

Usage

local Surface = require('__stdlib__/stdlib/area/surface')

Functions

lookup(surface)	Flexible and safe lookup function for surfaces.
find_all_entities(search_criteria)	Given a search criteria, find all entities that match the criteria.
get_surface_bounds(surface)	Gets the area which covers the entirety of a given surface.
set_daytime_thresholds(surface, morning, dawn, dusk, evening)	Sets the daytime transition thresholds on a given surface

Tables

search_criteria	This table should be passed into find_all_entities function to find entities that match the criteria.

Functions

# lookup(surface)

Flexible and safe lookup function for surfaces.

• May be given a single surface name or an array of surface names in string.
• May be given a single surface object or an array of surface objects in LuaSurface.
• May also be given a nil.
• Returns an array of surface objects of all valid and existing surfaces.
• Returns an empty array if no surfaces are given or if they are not found.

Parameters:

• surface : (nil, string, {string,...}, LuaSurface or {LuaSurface,...}) the surfaces to look up

Returns:

• ({nil or LuaSurface,...}) an array of all valid surfaces or nil otherwise

# find_all_entities(search_criteria)

Given a search criteria, find all entities that match the criteria.

• If search_criteria.name is not supplied, search for entities with any name.
• If search_criteria.type is not supplied, search for entities of any type.
• If search_criteria.force is not supplied, search for entities owned by any force.
• If search_criteria.surface is not supplied, search for entities on all surfaces.
• If search_criteria.area is not supplied, search the entire specified surface.

Parameters:

• search_criteria : (search_criteria) a table used to search for entities

Returns:

• ({nil or LuaEntity,...}) an array of all entities that matched the criteria OR nil if there were no matches

Usage:

surface.find_all_entities({ type = 'unit', surface = 'nauvis', area = {{-1000,20},{-153,2214}})
-- returns a list containing all unit entities on the nauvis surface in the given area

# get_surface_bounds(surface)

Gets the area which covers the entirety of a given surface.

This function is useful if you wish to compare the total number of chunks against the number of chunks within the entire area of a given surface.

Parameters:

• surface : (LuaSurface) the surface for which to get the area

Returns:

• (BoundingBox) the area of a given surface

# set_daytime_thresholds(surface, morning, dawn, dusk, evening)

Sets the daytime transition thresholds on a given surface

Parameters:

• surface : (LuaSurface) the surface for which to set the thresholds
• morning : (number) daytime to begin transition from dark to light
• dawn : (number) daytime to finish transition from dark to light
• dusk : (number) daytime to begin transition from light to dark
• evening : (number) daytime to finish transition from light to dark

Returns:

• (boolean) true if the thresholds were set, false if there was an error
• the raised error, if any

Tables

# search_criteria

This table should be passed into find_all_entities function to find entities that match the criteria.

Fields:

• name : (string) internal name of an entity — (example: “locomotive”) (optional)
• type : (string) type of an entity — (example: “unit”) (optional)
• force : (string or LuaForce) the force of an entity — (examples: “neutral”, “enemy”) (optional)
• surface : (nil, string, {string,...}, LuaSurface or {LuaSurface,...}) the surface to search — (example: “nauvis”) (optional)
• area : (BoundingBox) the area to search (optional)