LuaSurface

class LuaSurface - sort
get_pollution(position) → double Get the pollution for a given position.
can_place_entity{name=…, position=…, direction=…, force=…} → boolean Check for collisions with terrain or other entities.
find_entity(entity, position) → LuaEntity Find a specific entity at a specific position.
find_entities(area) → array of LuaEntity Find entities in a given area.
find_entities_filtered{area=…, position=…, name=…, type=…, force=…, limit=…} → array of LuaEntity Find entities of given type or name in a given area.
count_entities_filtered{area=…, position=…, name=…, type=…, force=…, limit=…} → uint Count entities of given type or name in a given area.
find_non_colliding_position(name, center, radius, precision) → Position Find a non-colliding possition within a given rectangle.
spill_item_stack(position, items, enable_looted) Spill items on the ground centered at a given location.
find_enemy_units(center, radius, force) → array of LuaEntity Find units enemy of a given force within an area.
find_nearest_enemy{position=…, max_distance=…, force=…} → LuaEntity Find the enemy closest to the given position.
set_multi_command{command=…, unit_count=…, force=…, unit_search_distance=…} → uint Give a command to multiple units.
create_entity{name=…, position=…, direction=…, force=…, target=…, source=…, fast_replace=…, player=…, spill=…} → LuaEntity Create an entity on this surface.
create_unit_group{position=…, force=…} → LuaUnitGroup Create a new unit group at a given position.
build_enemy_base(position, unit_count, force) Send a group to build a new base.
get_tile(x, y) → LuaTile Get the tile at a given position.
set_tiles(tiles, correct_tiles) Set tiles at specified locations.
pollute(source, amount) Spawn pollution at the given position.
get_chunks() → LuaChunkIterator Get an iterator going over every chunk on this surface.
is_chunk_generated(position) → boolean Is a given chunk generated?
request_to_generate_chunks(position, radius) Request that the game's map generator generate chunks at the given position for the given radius on this surface.
set_chunk_generated_status(position, status) Set generated status of a chunk.
find_logistic_network_by_position(position, force) → LuaLogisticNetwork Find the logistic network that covers a given position.
find_logistic_networks_by_construction_area(position, force) → array of LuaLogisticNetwork Finds all of the logistics networks whos construction area intersects with the given position.
deconstruct_area{area=…, force=…} Place a deconstruction request.
cancel_deconstruct_area{area=…, force=…} Cancel a deconstruction order.
get_hidden_tile(position) The hidden tile name or nil if there isn't one for the given position.
get_connected_tiles(position, tiles) → array of Position Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position.
delete_chunk(position)
regenerate_entity(entitites, chunks) Regenerate autoplacement of some entities on this surface.
regenerate_decorative(decoratives, chunks) Regenerate autoplacement of some decoratives on this surface.
print(message) Print text to the chat console of all players on this surface.
destroy_decoratives(area) Removes all decoratives from the given area.
create_decoratives{check_collision=…, decoratives=…} Adds the given decoratives to the surface.
get_trains(force) → array of LuaTrain
name :: string [R] The name of this surface.
index :: uint [R] Unique ID associated with this surface.
map_gen_settings :: MapGenSettings [R] Gets the generation settings for the surface.
always_day :: boolean [RW] When set to true, the sun will always shine.
daytime :: float [RW] Current time of day, as a number in range [0, 1).
darkness :: float [R] Amount of darkness at the current time.
wind_speed :: float [RW] Current wind speed.
wind_orientation :: float [RW] Current wind direction.
wind_orientation_change :: float [RW] Change in wind orientation per tick.
peaceful_mode :: boolean [RW] Is peaceful mode enabled on this surface?
freeze_daytime :: boolean [RW] True if daytime is currently frozen.
valid :: boolean [R] Is this object valid?
help() → string All methods, and properties that this object supports.

A "domain" of the world. Surfaces can only be created through the API and can not be deleted. However, it is planned to allow deletion of a surface in the future. Surfaces are uniquely identified by their name. Every game contains at least the surface "nauvis".

get_pollution(position) → double

Get the pollution for a given position.

Parameters
position :: Position
Example
game.surfaces[1].get_pollution({1,2})
can_place_entity{name=…, position=…, direction=…, force=…} → boolean

Check for collisions with terrain or other entities.

Parameters
Table with the following fields:
  • name :: string: Name of the entity to check
  • position :: Position: Where the entity would be placed
  • direction :: defines.direction (optional): Direction the entity would be placed
  • force :: string or LuaForce (optional): The force that would place the entity. If not specified, the enemy force is assumed.
find_entity(entity, position) → LuaEntity

Find a specific entity at a specific position.

Parameters
entity :: string: Entity to look for
position :: Position: Coordinates to look at
Return value
Will be nil if no such entity is found.
Example
game.player.selected.surface.find_entity('filter-inserter',{0,0})
find_entities(area) → array of LuaEntity

Find entities in a given area.

Parameters
area :: BoundingBox (optional): Where to search. If not given all entities on the surface are returned.
Example
Will evaluate to a list of all entities within given area.
game.surfaces["nauvis"].find_entities({{-10, -10}, {10, 10}})
find_entities_filtered{area=…, position=…, name=…, type=…, force=…, limit=…} → array of LuaEntity

Find entities of given type or name in a given area.

If no filters (name, type, or force) are given, returns all entities in the search area. If multiple filters are specified, returns only entities matching all given filters.

Parameters
Table with the following fields:
  • area :: BoundingBox (optional): Search area. If not given and position is not given then the entire surface is searched.
  • position :: Position (optional): Search position. if not given and area is not given the entire surface is searched. If both area and position are given position is used.
  • name :: string (optional)
  • type :: string (optional)
  • force :: string or LuaForce (optional)
  • limit :: uint (optional)
Example
game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, type= "resource"} -- gets all resources in the rectangle
game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, name= "iron-ore"} -- gets all iron ores in the rectangle
game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, force= "player"}  -- gets player owned entities in the rectangle
game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, limit= 5}  -- gets the first 5 entities in the rectangle
count_entities_filtered{area=…, position=…, name=…, type=…, force=…, limit=…} → uint

Count entities of given type or name in a given area. Works just like LuaSurface::find_entities_filtered, except this only returns the count. As it doesn't construct all the wrapper objects, this is more efficient if one is only interested in the number of entities.

Parameters
Table with the following fields:
  • area :: BoundingBox (optional): Search area. If not given and position is not given then the entire surface is searched.
  • position :: Position (optional): Search position. if not given and area is not given the entire surface is searched. If both area and position are given position is used.
  • name :: string (optional)
  • type :: string (optional)
  • force :: string or LuaForce (optional)
  • limit :: uint (optional)
find_non_colliding_position(name, center, radius, precision) → Position

Find a non-colliding possition within a given rectangle.

Parameters
name :: string: Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.)
center :: Position: Center of the search area.
radius :: double: Max distance from center to search in. 0 for infinitely-large search area.
precision :: double: The step length from the given position as it searches, in tiles.
Return value
The non-colliding position. May be nil if no suitable position was found.
spill_item_stack(position, items, enable_looted)

Spill items on the ground centered at a given location.

Parameters
position :: Position: Center of the spillage
items :: LuaItemStack or SimpleItemStack: Items to spill
enable_looted :: boolean (optional): When true, each created item will be flagged with the LuaEntity::to_be_looted flag.
find_enemy_units(center, radius, force) → array of LuaEntity

Find units enemy of a given force within an area.

Parameters
center :: Position: Center of the search area
radius :: double: Radius of the circular search area
force :: LuaForce or string (optional): Force to find enemies of. If not given, uses the player force.
Note: This is more efficient than LuaSurface::find_entities.
Example
Find all entities who would be interested to attack the player, within 100-tile area.
local enemies = game.player.surface.find_enemy_units(game.player.character.position, 100)
find_nearest_enemy{position=…, max_distance=…, force=…} → LuaEntity

Find the enemy closest to the given position.

Parameters
Table with the following fields:
  • position :: Position: Center of the search area.
  • max_distance :: double: Radius of the circular search area.
  • force :: string or LuaForce (optional): The force the result will be an enemy of. Uses the player force if not specified.
Return value
The nearest enemy unit or nil if no enemy could be found within the given area.
set_multi_command{command=…, unit_count=…, force=…, unit_search_distance=…} → uint

Give a command to multiple units. This will automatically select suitable units for the task.

Parameters
Table with the following fields:
  • command :: Command
  • unit_count :: uint: Number of units to give the command to.
  • force :: string or LuaForce (optional): Force of the units this command is to be given to. If not specified, uses the enemy force.
  • unit_search_distance :: uint (optional): Radius to search for units. The search area is centered on the destination of the command.
Return value
Number of units actually sent. May be less than count if not enough units were available.
create_entity{name=…, position=…, direction=…, force=…, target=…, source=…, fast_replace=…, player=…, spill=…} → LuaEntity

Create an entity on this surface.

Parameters
Table with the following fields:
  • name :: string: The entity prototype name to create.
  • position :: Position: Where to create the entity.
  • direction :: defines.direction (optional): Desired orientation of the entity after creation.
  • force :: string or LuaForce (optional): Force of the entity, default is enemy.
  • target :: LuaEntity (optional): Entity with health for the new entity to target.
  • source :: LuaEntity (optional): Source entity. Used for beams.
  • fast_replace :: boolean (optional): If true, building will attempt to simulate fast-replace building.
  • player :: PlayerSpecification (optional): If given along with fast_replace being true, fast-replace will simulate using this player.
  • spill :: boolean (optional): If false while fast_replace is true any excess items from fast-replacing will be deleted instead of dropped on the ground.
  • Additional entity-specific parameters
    • assembling-machine
    • container
      • bar :: uint (optional): Inventory index where the red limiting bar should be set.
    • flying-text
      • text :: string: The string to show.
      • color :: Color: Color of the displayed text.
    • entity-ghost
      • inner_name :: string: The prototype name of the entity contained in the ghost.
      • expires :: boolean (optional): If false the ghost entity will not expire. Default is true.
    • fire
      • initial_ground_flame_count :: uint: With how many small flames should the fire on ground be created.
    • inserter
    • item-entity
      • stack :: SimpleItemStack: The stack of items to create. This must be a table, i.e. a single string is not allowed here.
    • item-request-proxy
      • modules :: dictionary stringuint: The stacks of items to be delivered to target entity from logistic network. Each stack must be table. If empty, the item request proxy won't be created.
    • logistic-container
      • request_filters :: array of Filter (optional)
    • particle
    • projectile
    • resource
    • underground-belt
      • type :: string (optional): "output" or "input"; default is "input".
    • programmable-speaker
    • character-corpse
      • inventory_size :: uint (optional)
      • player_index :: uint (optional)
Return value
The created entity or nil if the creation failed.
Example
asm = game.surfaces[1].create_entity{name = "assembling-machine-1", position = {15, 3}, force=game.forces.player, recipe = "iron-stick"}
Example
Creates a smart inserter with circuit conditions and a filter
game.surfaces[1].create_entity{
  name = "filter-inserter", position = {20, 15}, force=game.player.force,
  conditions={red={name="wood", count=3, operator=">"},
              green={name="iron-ore", count=1, operator="<"},
  logistics={name="wood", count=3, operator="="}},
  filters={ {index=1, name="iron-ore"} }
}
Example
Creates a requester chest already set to request 128 iron plates.
game.surfaces[1].create_entity{
  name = "logistic-chest-requester", position = {game.player.position.x+3, game.player.position.y},
  force=game.player.force, request_filters={ {index=1, name="iron-plate", count=128} }
}
Example
game.surfaces[1].create_entity{name = "big-biter", position= {15, 3}, force = game.forces.player} -- Friendly biter
game.surfaces[1].create_entity{name = "medium-biter", position= {15, 3}, force = game.forces.enemy} -- Enemy biter
Example
Creates a basic inserter at the player's location facing north
game.surfaces[1].create_entity{name = "inserter", position = game.player.position, direction = defines.direction.north}
create_unit_group{position=…, force=…} → LuaUnitGroup

Create a new unit group at a given position.

Parameters
Table with the following fields:
  • position :: Position: Initial position of the new unit group.
  • force :: string or LuaForce (optional): Force of the new unit group. Defaults to "enemy".
build_enemy_base(position, unit_count, force)

Send a group to build a new base.

Parameters
position :: Position: Location of the new base.
unit_count :: uint: Number of biters to send for the base-building task.
force :: string or LuaForce (optional): Force the new base will belong to. Defaults to enemy.
Note: The specified force must be AI-controlled; i.e. force.ai_controllable must be true.
get_tile(x, y) → LuaTile

Get the tile at a given position.

Parameters
x :: int
y :: int
Note: The input position params can also be a single tile position.
set_tiles(tiles, correct_tiles)

Set tiles at specified locations. Automatically corrects the edges around modified tiles.

Parameters
tiles :: array of Tile: Each Tile is a table:
correct_tiles :: boolean (optional): If false, the correction logic is not done on the changed tiles. Defaults to true.
Note: It is recommended to call this method once for all the tiles you want to change rather than calling it individually for every tile. As the tile correction is used after every step, calling it one by one could cause the tile correction logic to redo some of the changes, and it is also much performance heavy.
pollute(source, amount)

Spawn pollution at the given position.

Parameters
source :: Position: Where to spawn the pollution.
amount :: double: How much pollution to add.
get_chunks() → LuaChunkIterator

Get an iterator going over every chunk on this surface.

is_chunk_generated(position) → boolean

Is a given chunk generated?

Parameters
position :: ChunkPosition: The chunk's position.
request_to_generate_chunks(position, radius)

Request that the game's map generator generate chunks at the given position for the given radius on this surface.

Parameters
position :: Position: Where to generate the new chunks.
radius :: uint: Radius from position to generate new chunks in.
set_chunk_generated_status(position, status)

Set generated status of a chunk. Useful when copying chunks.

Parameters
position :: Position: The chunk's position.
status :: defines.chunk_generated_status: The chunk's new status.
find_logistic_network_by_position(position, force) → LuaLogisticNetwork

Find the logistic network that covers a given position.

Parameters
position :: Position
force :: string or LuaForce: Force the logistic network should belong to.
Return value
The found network or nil if no such network was found.
find_logistic_networks_by_construction_area(position, force) → array of LuaLogisticNetwork

Finds all of the logistics networks whos construction area intersects with the given position.

Parameters
position :: Position
force :: string or LuaForce: Force the logistic networks should belong to.
deconstruct_area{area=…, force=…}

Place a deconstruction request.

Parameters
Table with the following fields:
  • area :: BoundingBox: The area to mark for deconstruction
  • force :: string or LuaForce: The force whose bots should perform the deconstruction.
cancel_deconstruct_area{area=…, force=…}

Cancel a deconstruction order.

Parameters
Table with the following fields:
  • area :: BoundingBox: The are to cancel deconstruction orders in.
  • force :: string or LuaForce: The force whose deconstruction orders to cancel.
get_hidden_tile(position)

The hidden tile name or nil if there isn't one for the given position.

Parameters
position :: Position: The tile position.
get_connected_tiles(position, tiles) → array of Position

Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position.

Parameters
position :: Position: The tile position to start at.
tiles :: array of string: The tiles to search for.
Return value
The resulting set of tiles.
Note: This won't find tiles in non-generated chunks.
delete_chunk(position)

Parameters
position :: Position: The chunk position to delete
Note: This won't delete the chunk immediately. Chunks are deleted at the end of the current tick.
regenerate_entity(entitites, chunks)

Regenerate autoplacement of some entities on this surface. This can be used to autoplace newly-added entities.

Parameters
entitites :: string or array of string: Prototype names of entity or entities to autoplace.
chunks :: array of Position (optional): The chunk positions to regenerate the entities on. If not given all chunks are regenerated. Note chunks with status < entities are ignored.
Note: All specified entity prototypes must be autoplacable.
regenerate_decorative(decoratives, chunks)

Regenerate autoplacement of some decoratives on this surface. This can be used to autoplace newly-added decoratives.

Parameters
decoratives :: string or array of string: Prototype names of decorative or decoratives to autoplace.
chunks :: array of Position (optional): The chunk positions to regenerate the entities on. If not given all chunks are regenerated. Note chunks with status < entities are ignored.
Note: All specified decorative prototypes must be autoplacable.
print(message)

Print text to the chat console of all players on this surface.

Parameters
message :: LocalisedString
destroy_decoratives(area)

Removes all decoratives from the given area.

Parameters
area :: BoundingBox
create_decoratives{check_collision=…, decoratives=…}

Adds the given decoratives to the surface.

Each Decorative is

Parameters
Table with the following fields:
  • check_collision :: boolean (optional): If collision should be checked against entities/tiles.
  • decoratives :: array of Decorative
Note: This will merge decoratives of the same type that alreaday exist effectivly increasing the "amount" field.
get_trains(force) → array of LuaTrain

Parameters
force :: string or LuaForce (optional): If given only trains matching this force are returned.
name :: string [Read-only]

The name of this surface. Names are unique among surfaces.

index :: uint [Read-only]

Unique ID associated with this surface.

map_gen_settings :: MapGenSettings [Read-only]

Gets the generation settings for the surface.

always_day :: boolean [Read-Write]

When set to true, the sun will always shine.

daytime :: float [Read-Write]

Current time of day, as a number in range [0, 1).

darkness :: float [Read-only]

Amount of darkness at the current time.

wind_speed :: float [Read-Write]

Current wind speed.

wind_orientation :: float [Read-Write]

Current wind direction.

wind_orientation_change :: float [Read-Write]

Change in wind orientation per tick.

peaceful_mode :: boolean [Read-Write]

Is peaceful mode enabled on this surface?

freeze_daytime :: boolean [Read-Write]

True if daytime is currently frozen.