LuaSurface

A "domain" of the world. Surfaces can only be created and deleted through the API. Surfaces are uniquely identified by their name. Every game contains at least the surface "nauvis".

class LuaSurface - sort
get_pollution(position) → double Get the pollution for a given position.
can_place_entity{name=…, position=…, direction=…, force=…, build_check_type=…, forced=…} → boolean Check for collisions with terrain or other entities.
can_fast_replace{name=…, position=…, direction=…, force=…} → boolean If there exists an entity at the given location that can be fast-replaced with the given entity parameters.
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=…, radius=…, name=…, type=…, ghost_name=…, ghost_type=…, direction=…, collision_mask=…, force=…, to_be_upgraded=…, limit=…, invert=…} → array of LuaEntity Find entities of given type or name in a given area.
find_tiles_filtered{area=…, position=…, radius=…, name=…, limit=…, has_hidden_tile=…, collision_mask=…} → array of LuaTile Find tiles of a given name in a given area.
count_entities_filtered{area=…, position=…, radius=…, name=…, type=…, ghost_name=…, ghost_type=…, direction=…, collision_mask=…, force=…, limit=…, invert=…} → uint Count entities of given type or name in a given area.
count_tiles_filtered{area=…, position=…, radius=…, name=…, limit=…, has_hidden_tile=…, collision_mask=…} → uint Count tiles of a given name in a given area.
find_non_colliding_position(name, center, radius, precision, force_to_tile_center) → Position Find a non-colliding position within a given radius.
find_non_colliding_position_in_box(name, search_space, precision, force_to_tile_center) → Position Find a non-colliding position within a given rectangle.
spill_item_stack(position, items, enable_looted, force, allow_belts) → array of LuaEntity Spill items on the ground centered at a given location.
find_enemy_units(center, radius, force) → array of LuaEntity Find enemy units (entities with type "unit") of a given force within an area.
find_units{area=…, force=…, condition=…} → array of LuaEntity Find units (entities with type "unit") of a given force and force condition within a given area.
find_nearest_enemy{position=…, max_distance=…, force=…} → LuaEntity Find the enemy entity-with-force (military entity) 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=…, raise_built=…, create_build_effect_smoke=…} → LuaEntity Create an entity on this surface.
create_trivial_smoke{name=…, position=…}
create_particle{name=…, position=…, movement=…, height=…, vertical_speed=…, frame_speed=…} Creates a particle at the given location
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.
force_generate_chunk_requests() Blocks and generates all chunks that have been requested using all available threads.
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 whose construction area intersects with the given position.
deconstruct_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} Place a deconstruction request.
cancel_deconstruct_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} Cancel a deconstruction order.
upgrade_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} Place an upgrade request.
cancel_upgrade_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} Cancel a upgrade order.
get_hidden_tile(position) → string The hidden tile name or nil if there isn't one for the given position.
set_hidden_tile(position, tile)
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(entities, chunks) Regenerate autoplacement of some entities on this surface.
regenerate_decorative(decoratives, chunks) Regenerate autoplacement of some decoratives on this surface.
print(message, color) Print text to the chat console of all players on this surface.
destroy_decoratives{area=…, position=…, name=…, limit=…, invert=…} Removes all decoratives from the given area.
create_decoratives{check_collision=…, decoratives=…} Adds the given decoratives to the surface.
find_decoratives_filtered{area=…, position=…, name=…, limit=…, invert=…} → array of DecorativeResult Find decoratives of a given name in a given area.
get_trains(force) → array of LuaTrain
clear_pollution() Clears all pollution on this surface.
play_sound{path=…, position=…, volume_modifier=…} → boolean Plays a sound on this surface.
get_resource_counts() → dictionary stringuint Gets the resource amount of all resources on this surface
get_random_chunk() → ChunkPosition Gets a random generated chunk position or 0,0 if no chunks have been generated on this surface.
clone_area{source_area=…, destination_area=…, destination_surface=…, destination_force=…, clone_tiles=…, clone_entities=…, clone_decoratives=…, clear_destination_entities=…, clear_destination_decoratives=…, expand_map=…} Clones the given area.
clone_brush{source_offset=…, destination_offset=…, source_positions=…, destination_surface=…, destination_force=…, clone_tiles=…, clone_entities=…, clone_decoratives=…, clear_destination_entities=…, clear_destination_decoratives=…, expand_map=…, manual_collision_mode=…} Clones the given area.
clone_entities{entities=…, destination_offset=…, destination_surface=…, destination_force=…, snap_to_grid=…} Clones the given entities.
clear(ignore_characters) Clears this surface deleting all entities and chunks on it.
request_path{bounding_box=…, collision_mask=…, start=…, goal=…, force=…, radius=…, pathfind_flags=…, can_open_gates=…, path_resolution_modifier=…, entity_to_ignore=…} → uint Starts a path find request without actually ordering a unit to move.
get_script_areas(name) → array of ScriptArea Gets the script areas that match the given name or if no name is given all areas are returned.
get_script_positions(name) → array of ScriptPosition Gets the script positions that match the given name or if no name is given all positions are returned.
get_map_exchange_string() → string Gets the map exchange string for the current map generation settings of this surface.
get_starting_area_radius() → double Gets the starting area radius of this surface.
get_closest(position, entities) → LuaEntity Gets the closest entity in the list to this position.
get_train_stops(opts) → array of LuaEntity Gets train stops matching the given filters.
get_total_pollution() → double Gets the total amount of pollution on the surface by iterating over all of the chunks containing pollution.
entity_prototype_collides(prototype, position, use_map_generation_bounding_box, direction)
decorative_prototype_collides(prototype, position)
calculate_tile_properties(property_names, positions) → dictionary stringarray of double
get_entities_with_force(position, force) → array of LuaEntity Returns all the entities with force on this chunk for the given force.
name :: string [RW] The name of this surface.
index :: uint [R] Unique ID associated with this surface.
map_gen_settings :: MapGenSettings [RW] 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.
ticks_per_day :: uint [RW] The number of ticks per day for this surface.
dusk :: double [RW] The daytime when dusk starts.
dawn :: double [RW] The daytime when dawn starts.
evening :: double [RW] The daytime when evening starts.
morning :: double [RW] The daytime when morning starts.
solar_power_multiplier :: double [RW] The multiplier of solar power on this surface.
min_brightness :: double [RW] The minimal brightness during the night.
brightness_visual_weights :: ColorModifier [RW] Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT).
valid :: boolean [R] Is this object valid?
help() → string All methods, and properties that this object supports.
get_pollution(position) → double

Get the pollution for a given position.

Parameters
position :: Position
Note: Pollution is stored per chunk, so this will return the same value for all positions in one chunk.
Example
game.surfaces[1].get_pollution({1,2})
can_place_entity{name=…, position=…, direction=…, force=…, build_check_type=…, forced=…} → 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 :: ForceSpecification (optional): The force that would place the entity. If not specified, the enemy force is assumed.
  • build_check_type :: defines.build_check_type (optional): What check type should be done.
  • forced :: boolean (optional): If defines.build_check_type is "ghost_place" and this is true things that can be marked for deconstruction are ignored.
can_fast_replace{name=…, position=…, direction=…, force=…} → boolean

If there exists an entity at the given location that can be fast-replaced with the given entity parameters.

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 :: ForceSpecification (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.

If no area is given all entities on the surface are returned.

Parameters
area :: BoundingBox (optional)
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=…, radius=…, name=…, type=…, ghost_name=…, ghost_type=…, direction=…, collision_mask=…, force=…, to_be_upgraded=…, limit=…, invert=…} → 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.

If no area and no position are given, then the entire surface is searched. If both area and position are specified, returns only entities matching the position. If position and radius are given, returns only entities within that radius of the position.

Parameters
Table with the following fields:
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}}, name = {"iron-ore", "copper-ore"}} -- gets all iron ore and copper ore 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
game.surfaces[1].find_entities_filtered{position = {0, 0}, radius = 10}  -- gets all entities within 10 tiles of the position [0,0].
find_tiles_filtered{area=…, position=…, radius=…, name=…, limit=…, has_hidden_tile=…, collision_mask=…} → array of LuaTile

Find tiles of a given name in a given area.

If no filters are given returns all tiles in the search area.

If no area is given, then the entire surface is searched. If position and radius are given, only tiles within the radius of the position are included.

Parameters
Table with the following fields:
count_entities_filtered{area=…, position=…, radius=…, name=…, type=…, ghost_name=…, ghost_type=…, direction=…, collision_mask=…, force=…, limit=…, invert=…} → 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.

If no area and no position are given, then the entire surface is searched. If both area and position are specified, counts only entities matching the position. If position and radius are given, counts only entities within that radius of the position.

Parameters
Table with the following fields:
count_tiles_filtered{area=…, position=…, radius=…, name=…, limit=…, has_hidden_tile=…, collision_mask=…} → uint

Count tiles of a given name in a given area. Works just like LuaSurface::find_tiles_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 tiles.

If no area is given, then the entire surface is searched. If position and radius are given, only tiles within the radius of the position are counted.

Parameters
Table with the following fields:
find_non_colliding_position(name, center, radius, precision, force_to_tile_center) → Position

Find a non-colliding position within a given radius.

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. Minimum value is 0.01.
force_to_tile_center :: boolean (optional): Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Default false.
Return value
The non-colliding position. May be nil if no suitable position was found.
find_non_colliding_position_in_box(name, search_space, precision, force_to_tile_center) → Position

Find a non-colliding position 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.)
search_space :: BoundingBox: The rectangle to search inside.
precision :: double: The step length from the given position as it searches, in tiles. Minimum value is 0.01.
force_to_tile_center :: boolean (optional): Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Default false.
Return value
The non-colliding position. May be nil if no suitable position was found.
spill_item_stack(position, items, enable_looted, force, allow_belts) → array of LuaEntity

Spill items on the ground centered at a given location.

Parameters
position :: Position: Center of the spillage
items :: ItemStackSpecification: Items to spill
enable_looted :: boolean (optional): When true, each created item will be flagged with the LuaEntity::to_be_looted flag.
force :: LuaForce or string (optional): When provided (and not nil) the items will be marked for deconstruction by this force.
allow_belts :: boolean (optional): Whether items can be spilled onto belts. Defaults to true.
Return value
The created item-on-ground entities.
find_enemy_units(center, radius, force) → array of LuaEntity

Find enemy units (entities with type "unit") 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 units who would be interested to attack the player, within 100-tile area.
local enemies = game.player.surface.find_enemy_units(game.player.position, 100)
find_units{area=…, force=…, condition=…} → array of LuaEntity

Find units (entities with type "unit") of a given force and force condition within a given area.

Parameters
Table with the following fields:
  • area :: BoundingBox: Box to find units within.
  • force :: LuaForce or string: Force performing the search.
  • condition :: ForceCondition: Only forces which meet the condition will be included in the search.
Note: This is more efficient than LuaSurface::find_entities.
Example
Find friendly units to "player" force
local friendly_units = game.player.surface.find_units({area = {{-10, -10},{10, 10}}, force = "player", condition = "friend")
Example
Find units of "player" force
local units = game.player.surface.find_units({area = {{-10, -10},{10, 10}}, force = "player", condition = "same"})
find_nearest_enemy{position=…, max_distance=…, force=…} → LuaEntity

Find the enemy entity-with-force (military entity) 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 :: ForceSpecification (optional): The force the result will be an enemy of. Uses the player force if not specified.
Return value
The nearest enemy entity-with-force 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 :: ForceSpecification (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=…, raise_built=…, create_build_effect_smoke=…} → 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 :: ForceSpecification (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 set the last_user to this player. If fast_replace is true simulate fast replace using this player.
  • spill :: boolean (optional): If false while fast_replace is true and player is nil any items from fast-replacing will be deleted instead of dropped on the ground.
  • raise_built :: boolean (optional): If true; defines.events.script_raised_built will be fired on successful entity creation.
  • create_build_effect_smoke :: boolean (optional): If false, the building effect smoke will not be shown around the new entity.
  • Additional entity-specific parameters
    • assembling-machine
    • beam
      • target_position :: Position (optional): Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined).
      • source_position :: Position (optional): Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined).
      • max_length :: uint (optional): If set, beam will be destroyed when distance between source and target is greater than this value.
      • duration :: uint (optional): If set, beam will be destroyed after this value of ticks.
      • source_offset :: Vector (optional): Source position will be offset by this value when rendering the beam.
    • container
      • bar :: uint (optional): Inventory index where the red limiting bar should be set.
    • cliff
      • cliff_orientation :: CliffOrientation (optional): If not specified, direction will be used instead.
    • flying-text
      • text :: LocalisedString: The string to show.
      • color :: Color (optional): Color of the displayed text.
      • render_player_index :: uint (optional)
    • 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 false.
    • fire
      • initial_ground_flame_count :: uint8 (optional): With how many small flames should the fire on ground be created. Defaults to the initial flame count of the prototype.
    • inserter
    • item-entity
    • item-request-proxy
      • target :: LuaEntity: The target items are to be delivered to.
      • modules :: dictionary stringuint: The stacks of items to be delivered to target entity from logistic network.
    • locomotive
      • snap_to_train_stop :: boolean (optional): Whether the locomotive should snap to an adjacent train stop. Defaults to true.
    • logistic-container
      • request_filters :: array of Filter (optional)
    • particle
    • projectile
    • resource
      • amount :: uint
      • enable_tree_removal :: boolean (optional): If colliding trees are removed normally for this resource entity based off the prototype tree removal values. Default is true.
      • enable_cliff_removal :: boolean (optional): If colliding cliffs are removed. Default is true.
    • underground-belt
      • type :: string (optional): "output" or "input"; default is "input".
    • programmable-speaker
    • character-corpse
      • inventory_size :: uint (optional)
      • player_index :: uint (optional)
    • highlight-box
    • speech-bubble
    • simple-entity-with-owner & simple-entity-with-force
      • render_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 filter 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_trivial_smoke{name=…, position=…}

Parameters
Table with the following fields:
  • name :: string: The smoke prototype name to create.
  • position :: Position: Where to create the smoke.
create_particle{name=…, position=…, movement=…, height=…, vertical_speed=…, frame_speed=…}

Creates a particle at the given location

Parameters
Table with the following fields:
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 :: ForceSpecification (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 :: ForceSpecification (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: The chunk radius from position to generate new chunks in.
force_generate_chunk_requests()

Blocks and generates all chunks that have been requested using all available threads.

set_chunk_generated_status(position, status)

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

Parameters
position :: ChunkPosition: 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 :: ForceSpecification: 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 whose construction area intersects with the given position.

Parameters
position :: Position
force :: ForceSpecification: Force the logistic networks should belong to.
deconstruct_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…}

Place a deconstruction request.

Parameters
Table with the following fields:
  • area :: BoundingBox: The area to mark for deconstruction.
  • force :: ForceSpecification: The force whose bots should perform the deconstruction.
  • player :: PlayerSpecification (optional): The player to set the last_user to if any.
  • skip_fog_of_war :: boolean (optional): If chunks covered by fog-of-war are skipped.
  • item :: LuaItemStack (optional): The deconstruction item to use if any.
cancel_deconstruct_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…}

Cancel a deconstruction order.

Parameters
Table with the following fields:
  • area :: BoundingBox: The area to cancel deconstruction orders in.
  • force :: ForceSpecification: The force whose deconstruction orders to cancel.
  • player :: PlayerSpecification (optional): The player to set the last_user to if any.
  • skip_fog_of_war :: boolean (optional): If chunks covered by fog-of-war are skipped.
  • item :: LuaItemStack (optional): The deconstruction item to use if any.
upgrade_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…}

Place an upgrade request.

Parameters
Table with the following fields:
  • area :: BoundingBox: The area to mark for upgrade.
  • force :: ForceSpecification: The force whose bots should perform the upgrade.
  • player :: PlayerSpecification (optional): The player to set the last_user to if any.
  • skip_fog_of_war :: boolean (optional): If chunks covered by fog-of-war are skipped.
  • item :: LuaItemStack: The upgrade item to use.
cancel_upgrade_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…}

Cancel a upgrade order.

Parameters
Table with the following fields:
  • area :: BoundingBox: The area to cancel upgrade orders in.
  • force :: ForceSpecification: The force whose upgrade orders to cancel.
  • player :: PlayerSpecification (optional): The player to set the last_user to if any.
  • skip_fog_of_war :: boolean (optional): If chunks covered by fog-of-war are skipped.
  • item :: LuaItemStack (optional): The upgrade item to use if any.
get_hidden_tile(position) → string

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

Parameters
position :: TilePosition: The tile position.
set_hidden_tile(position, tile)

Parameters
position :: TilePosition: The tile position.
tile :: string or LuaTilePrototype: The new hidden tile or nil to clear the hidden tile.
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 :: ChunkPosition: 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(entities, chunks)

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

Parameters
entities :: string or array of string (optional): Prototype names of entity or entities to autoplace. When nil all entities with an autoplace are used.
chunks :: array of ChunkPosition (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. If nothing is given all entities are generated on all chunks.
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 (optional): Prototype names of decorative or decoratives to autoplace. When nil all decoratives with an autoplace are used.
chunks :: array of ChunkPosition (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. If nothing is given all decoratives are generated on all chunks.
print(message, color)

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

Parameters
message :: LocalisedString
color :: Color (optional)
Note: Messages that are identical to a message sent in the last 60 ticks are not printed again.
destroy_decoratives{area=…, position=…, name=…, limit=…, invert=…}

Removes all decoratives from the given area.

If no area and no position are given, then the entire surface is searched.

Parameters
Table with the following fields:
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 already exist effectively increasing the "amount" field.
find_decoratives_filtered{area=…, position=…, name=…, limit=…, invert=…} → array of DecorativeResult

Find decoratives of a given name in a given area.

If no filters are given, returns all decoratives in the search area. If multiple filters are specified, returns only decoratives matching all given filters.

If no area and no position are given, then the entire surface is searched.

Each DecorativeResult is a table:

Parameters
Table with the following fields:
Example
game.surfaces[1].find_decoratives_filtered{area = {{-10, -10}, {10, 10}}, name = "sand-decal"} -- gets all sand-decals in the rectangle
game.surfaces[1].find_decoratives_filtered{area = {{-10, -10}, {10, 10}}, limit = 5}  -- gets the first 5 decoratives in the rectangle
get_trains(force) → array of LuaTrain

Parameters
force :: ForceSpecification (optional): If given only trains matching this force are returned.
clear_pollution()

Clears all pollution on this surface.

play_sound{path=…, position=…, volume_modifier=…} → boolean

Plays a sound on this surface.

Parameters
Table with the following fields:
  • path :: SoundPath: The sound to play
  • position :: Position (optional): Where the sound should be played. If not given it's played 'everywhere'.
  • volume_modifier :: double (optional): Must be between 0 and 1 inclusive.
get_resource_counts() → dictionary stringuint

Gets the resource amount of all resources on this surface

get_random_chunk() → ChunkPosition

Gets a random generated chunk position or 0,0 if no chunks have been generated on this surface.

clone_area{source_area=…, destination_area=…, destination_surface=…, destination_force=…, clone_tiles=…, clone_entities=…, clone_decoratives=…, clear_destination_entities=…, clear_destination_decoratives=…, expand_map=…}

Clones the given area.

Parameters
Table with the following fields:
  • source_area :: BoundingBox
  • destination_area :: BoundingBox
  • destination_surface :: SurfaceSpecification (optional)
  • destination_force :: LuaForce or string (optional)
  • clone_tiles :: boolean (optional): If tiles should be cloned
  • clone_entities :: boolean (optional): If entities should be cloned
  • clone_decoratives :: boolean (optional): If decoratives should be cloned
  • clear_destination_entities :: boolean (optional): If the destination entities should be cleared
  • clear_destination_decoratives :: boolean (optional): If the destination decoratives should be cleared
  • expand_map :: boolean (optional): If the destination surface should be expanded when destination_area is outside current bounds. Default false.
Note: defines.events.on_entity_cloned is raised for each entity, and then defines.events.on_area_cloned is raised.
Note: Entities are cloned in an order such that they can always be created, eg rails before trains.
clone_brush{source_offset=…, destination_offset=…, source_positions=…, destination_surface=…, destination_force=…, clone_tiles=…, clone_entities=…, clone_decoratives=…, clear_destination_entities=…, clear_destination_decoratives=…, expand_map=…, manual_collision_mode=…}

Clones the given area.

Parameters
Table with the following fields:
  • source_offset :: TilePosition
  • destination_offset :: TilePosition
  • source_positions :: array of TilePosition
  • destination_surface :: SurfaceSpecification (optional)
  • destination_force :: LuaForce or string (optional)
  • clone_tiles :: boolean (optional): If tiles should be cloned
  • clone_entities :: boolean (optional): If entities should be cloned
  • clone_decoratives :: boolean (optional): If decoratives should be cloned
  • clear_destination_entities :: boolean (optional): If the destination entities should be cleared
  • clear_destination_decoratives :: boolean (optional): If the destination decoratives should be cleared
  • expand_map :: boolean (optional): If the destination surface should be expanded when destination_area is outside current bounds. Default false.
  • manual_collision_mode :: boolean (optional): If manual-style collision checks should be done.
Note: defines.events.on_entity_cloned is raised for each entity, and then defines.events.on_area_cloned is raised.
Note: Entities are cloned in an order such that they can always be created, eg rails before trains.
clone_entities{entities=…, destination_offset=…, destination_surface=…, destination_force=…, snap_to_grid=…}

Clones the given entities.

Parameters
Table with the following fields:
Note: defines.events.on_entity_cloned is raised for each entity.
Note: Entities are cloned in an order such that they can always be created, eg rails before trains.
clear(ignore_characters)

Clears this surface deleting all entities and chunks on it.

Parameters
ignore_characters :: boolean (optional): Whether characters on this surface that are connected to or associated with players should be ignored (not destroyed).
Note: This won't clear the surface immediately. It will be cleared at the end of the current tick.
request_path{bounding_box=…, collision_mask=…, start=…, goal=…, force=…, radius=…, pathfind_flags=…, can_open_gates=…, path_resolution_modifier=…, entity_to_ignore=…} → uint

Starts a path find request without actually ordering a unit to move. Result is ultimately returned asynchronously via defines.events.on_script_path_request_finished.

Parameters
Table with the following fields:
  • bounding_box :: BoundingBox
  • collision_mask :: CollisionMask or array of string
  • start :: Position
  • goal :: Position
  • force :: LuaForce or string
  • radius :: double (optional): How close we need to get to the goal. Default 1.
  • pathfind_flags :: PathFindFlags (optional): Flags to affect the pathfinder.
  • can_open_gates :: boolean (optional): If the path request can open gates. Default false.
  • path_resolution_modifier :: int (optional): The resolution modifier of the pathing. Defaults to 0.
  • entity_to_ignore :: LuaEntity (optional): If given, the pathfind will ignore collisions with this entity.
Return value
A unique handle to identify this call when defines.events.on_script_path_request_finished fires.
get_script_areas(name) → array of ScriptArea

Gets the script areas that match the given name or if no name is given all areas are returned.

Parameters
name :: string (optional)
get_script_positions(name) → array of ScriptPosition

Gets the script positions that match the given name or if no name is given all positions are returned.

Parameters
name :: string (optional)
get_map_exchange_string() → string

Gets the map exchange string for the current map generation settings of this surface.

get_starting_area_radius() → double

Gets the starting area radius of this surface.

get_closest(position, entities) → LuaEntity

Gets the closest entity in the list to this position.

Parameters
position :: Position
entities :: array of LuaEntity: The Entities to check
get_train_stops(opts) → array of LuaEntity

Gets train stops matching the given filters.

Parameters
opts (optional): Table with the following fields:
get_total_pollution() → double

Gets the total amount of pollution on the surface by iterating over all of the chunks containing pollution.

entity_prototype_collides(prototype, position, use_map_generation_bounding_box, direction)

Parameters
prototype :: EntityPrototypeSpecification: The entity prototype to check
position :: Position: The position to check
use_map_generation_bounding_box :: boolean: If the map generation bounding box should be used instead of the collision bounding box
direction :: defines.direction (optional)
decorative_prototype_collides(prototype, position)

Parameters
prototype :: string: The decorative prototype to check
position :: Position: The position to check
calculate_tile_properties(property_names, positions) → dictionary stringarray of double

Parameters
property_names :: array of string: Names of properties (e.g. "elevation") to calculate
positions :: array of Position: Positions for which to calculate property values
Return value
Table of property value lists, keyed by property name
get_entities_with_force(position, force) → array of LuaEntity

Returns all the entities with force on this chunk for the given force.

Parameters
position :: ChunkPosition: The chunk's position.
force :: LuaForce or string: Entities of this force will be returned.
name :: string [Read-Write]

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

Note: the default surface can't be renamed.
index :: uint [Read-only]

Unique ID associated with this surface.

map_gen_settings :: MapGenSettings [Read-Write]

The generation settings for the surface.

can be used to adjust the surface after changing generation settings.

Note: When changing settings runtime the game will not retroactively change anything.
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.

ticks_per_day :: uint [Read-Write]

The number of ticks per day for this surface.

dusk :: double [Read-Write]

The daytime when dusk starts.

dawn :: double [Read-Write]

The daytime when dawn starts.

evening :: double [Read-Write]

The daytime when evening starts.

morning :: double [Read-Write]

The daytime when morning starts.

solar_power_multiplier :: double [Read-Write]

The multiplier of solar power on this surface. Cannot be less than 0.

Note: Solar equipment is still limited to its maximum power output.
min_brightness :: double [Read-Write]

The minimal brightness during the night. Default is 0.15. The value has an effect on the game simalution only, it doesn't have any effect on rendering.

brightness_visual_weights :: ColorModifier [Read-Write]

Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT).

The LUT is multiplied by ((1 - weight) + brightness * weight) and result is clamped to range [0, 1].

Default is {0, 0, 0}, which means no influence.

Example
Makes night on the surface pitch black, assuming LuaSurface::min_brightness being set to default value 0.15.
game.surfaces[1].brightness_visual_weights = { 1 / 0.85, 1 / 0.85, 1 / 0.85 }