Area.Surface module

For working with surfaces.

Surfaces are the “domain” of the world.

See also

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: Returns:
# 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: 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:
# 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)