Factorio.com|Forums|Wiki|Mod Portal|API Docs

# Factorio Runtime Docs Version 2.0.77

# LuaSurface - Runtime Docs

## Class LuaSurface

A "domain" of the world, such as a planet or space platform. Surfaces are uniquely identified by their name. Every game contains at least the surface "nauvis".

## Members

get_pollution(position) | → double | Get the pollution for a given position. [...]
Get the pollution for a given position. [...]
set_pollution(position, amount) |  | Set the pollution for a given position. [...]
Set the pollution for a given position. [...]
can_place_entity{name=…, position=…, direction?=…, force?=…, build_check_type?=…, forced?=…, inner_name?=…} | → boolean | Check for collisions with terrain or other entities.
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.
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 an entity of the given name at the given position. [...]
Find an entity of the given name at the given position. [...]
find_entities(area?) | → array[LuaEntity] | Find entities in a given area. [...]
Find entities in a given area. [...]
find_entities_filtered(filter) | → array[LuaEntity] | Find all entities of the given type or name in the given area. [...]
Find all entities of the given type or name in the given area. [...]
find_tiles_filtered(filter) | → array[LuaTile] | Find all tiles of the given name in the given area. [...]
Find all tiles of the given name in the given area. [...]
count_entities_filtered(filter) | → uint32 | Count entities of given type or name in a given area. [...]
Count entities of given type or name in a given area. [...]
count_tiles_filtered(filter) | → uint32 | Count tiles of a given name in a given area. [...]
Count tiles of a given name in a given area. [...]
find_non_colliding_position(name, center, radius, precision, force_to_tile_center?) | → MapPosition? | Find a non-colliding position within a given radius. [...]
Find a non-colliding position within a given radius. [...]
find_non_colliding_position_in_box(name, search_space, precision, force_to_tile_center?) | → MapPosition? | Find a non-colliding position within a given rectangle.
Find a non-colliding position within a given rectangle.
spill_item_stack{position=…, stack=…, enable_looted?=…, force?=…, allow_belts?=…, max_radius?=…, use_start_position_on_failure?=…, drop_full_stack?=…} | → array[LuaEntity] | Spill items on the ground centered at a given location.
Spill items on the ground centered at a given location.
spill_inventory{position=…, inventory=…, enable_looted?=…, force?=…, allow_belts?=…, max_radius?=…, use_start_position_on_failure?=…, drop_full_stack?=…} | → array[LuaEntity] | Spill inventory on the ground centered at a given location.
Spill inventory on the ground centered at a given location.
find_enemy_units(center, radius, force?) | → array[LuaEntity] | Find enemy units (entities with type "unit") of a given force within an area. [...]
Find enemy units (entities with type "unit") of a given force within an area. [...]
find_units{area=…, force=…, condition=…} | → array[LuaEntity] | Find units (entities with type "unit") of a given force and force condition within a given area. [...]
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 military target (military entity) closest to the given position.
Find the enemy military target (military entity) closest to the given position.
find_nearest_enemy_entity_with_owner{position=…, max_distance=…, force?=…} | → LuaEntity | Find the enemy entity-with-owner closest to the given position.
Find the enemy entity-with-owner closest to the given position.
set_multi_command{command=…, unit_count=…, force?=…, unit_search_distance?=…} | → uint32 | Give a command to multiple units. [...]
Give a command to multiple units. [...]
create_entity{name=…, position=…, direction?=…, mirror?=…, quality?=…, force?=…, target?=…, source?=…, cause?=…, snap_to_grid?=…, fast_replace?=…, undo_index?=…, player?=…, character?=…, spill?=…, raise_built?=…, create_build_effect_smoke?=…, spawn_decorations?=…, move_stuck_players?=…, item?=…, preserve_ghosts_and_corpses?=…, register_plant?=…, burner_fuel_inventory?=…} | → LuaEntity? | Create an entity on this surface.
Create an entity on this surface.
create_segmented_unit{name=…, quality?=…, force?=…, territory?=…} | → LuaSegmentedUnit? | Create a segmented unit on the surface. [...]
Create a segmented unit on the surface. [...]
create_territory{chunks=…, patrol_path?=…} | → LuaTerritory? | Create a territory on the surface.
Create a territory on the surface.
create_trivial_smoke{name=…, position=…} |  |
create_particle{name=…, position=…, movement=…, height=…, vertical_speed=…, frame_speed=…} |  | Creates a particle at the given location
Creates a particle at the given location
create_unit_group{position=…, force?=…} | → LuaCommandable | Create a new unit group at a given position.
Create a new unit group at a given position.
build_enemy_base(position, unit_count, force?) |  | Send a group to build a new base. [...]
Send a group to build a new base. [...]
get_tile(x, y) | → LuaTile | Get the tile at a given position. [...]
Get the tile at a given position. [...]
set_tiles(tiles, correct_tiles?, remove_colliding_entities?, remove_colliding_decoratives?, raise_event?, player?, undo_index?) |  | Set tiles at specified locations. [...]
Set tiles at specified locations. [...]
pollute(source, amount, prototype?) |  | Spawn pollution at the given position.
Spawn pollution at the given position.
get_chunks() | → LuaChunkIterator | Get an iterator going over every chunk on this surface. [...]
Get an iterator going over every chunk on this surface. [...]
is_chunk_generated(chunk_position) | → boolean | Is a given chunk generated?
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. [...]
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.
Blocks and generates all chunks that have been requested using all available threads.
set_chunk_generated_status(chunk_position, status) |  | Set generated status of a chunk. [...]
Set generated status of a chunk. [...]
get_territories() | → array[LuaTerritory] | Get all territories on the surface.
Get all territories on the surface.
get_territory_for_chunk(chunk_position) | → LuaTerritory? | Get the territory that the given chunk is assigned to. [...]
Get the territory that the given chunk is assigned to. [...]
set_territory_for_chunks(chunk_positions, territory?) |  | Removes the given chunks from their current territories and adds them to the given territory if provided. [...]
Removes the given chunks from their current territories and adds them to the given territory if provided. [...]
clear_territory_for_chunks(chunk_positions) |  | Removes the chunk from the territory it is associated with (if any) and allows the map generator to potentially generate a new territory for the chunk in the future. [...]
Removes the chunk from the territory it is associated with (if any) and allows the map generator to potentially generate a new territory for the chunk in the future. [...]
get_segmented_units() | → array[LuaSegmentedUnit] | Get all segmented units that exist on the surface.
Get all segmented units that exist on the surface.
find_logistic_network_by_position(position, force) | → LuaLogisticNetwork? | Find the logistic network that covers a given position.
Find the logistic network that covers a given position.
find_closest_logistic_network_by_position(position, force) | → LuaLogisticNetwork? | Find the logistic network with a cell closest to a given position.
Find the logistic network with a cell closest to a given position.
find_logistic_networks_by_construction_area(position, force) | → array[LuaLogisticNetwork] | Finds all of the logistics networks whose construction area intersects with the given position.
Finds all of the logistics networks whose construction area intersects with the given position.
deconstruct_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item?=…, super_forced?=…} |  | Place a deconstruction request.
Place a deconstruction request.
cancel_deconstruct_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item?=…, undo_index?=…, super_forced?=…} |  | Cancel a deconstruction order.
Cancel a deconstruction order.
upgrade_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item=…} |  | Place an upgrade request.
Place an upgrade request.
cancel_upgrade_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item=…} |  | Cancel a upgrade order.
Cancel a upgrade order.
get_hidden_tile(position) | → string? | The hidden tile name.
The hidden tile name.
get_double_hidden_tile(position) | → string | The double hidden tile name or `nil` if there isn't one for the given position.
The double hidden tile name or `nil` if there isn't one for the given position.
set_hidden_tile(position, tile?) |  | Set the hidden tile for the specified position. [...]
Set the hidden tile for the specified position. [...]
set_double_hidden_tile(position, tile?) |  | Set double hidden tile for the specified position. [...]
Set double hidden tile for the specified position. [...]
get_connected_tiles(position, tiles, include_diagonal?, area?) | → array[TilePosition] | Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile 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(chunk_position) |  |
regenerate_entity(entities?, chunks?) |  | Regenerate autoplacement of some entities on this surface. [...]
Regenerate autoplacement of some entities on this surface. [...]
regenerate_decorative(decoratives?, chunks?) |  | Regenerate autoplacement of some decoratives on this surface. [...]
Regenerate autoplacement of some decoratives on this surface. [...]
print(message, print_settings?) |  | Print text to the chat console of all players on this surface. [...]
Print text to the chat console of all players on this surface. [...]
destroy_decoratives{area?=…, position?=…, name?=…, collision_mask?=…, from_layer?=…, to_layer?=…, exclude_soft?=…, limit?=…, invert?=…} |  | Removes all decoratives from the given area. [...]
Removes all decoratives from the given area. [...]
create_decoratives{check_collision?=…, decoratives=…} |  | Adds the given decoratives to the surface. [...]
Adds the given decoratives to the surface. [...]
find_decoratives_filtered{area?=…, position?=…, name?=…, collision_mask?=…, from_layer?=…, to_layer?=…, exclude_soft?=…, limit?=…, invert?=…} | → array[DecorativeResult] | Find decoratives of a given name in a given area. [...]
Find decoratives of a given name in a given area. [...]
clear_pollution() |  | Clears all pollution on this surface.
Clears all pollution on this surface.
play_sound(sound_specification) |  | Play a sound for every player on this surface. [...]
Play a sound for every player on this surface. [...]
get_resource_counts() | → dictionary[string → uint32] | Gets the resource amount of all resources on this surface
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.
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?=…, create_build_effect_smoke?=…} |  | Clones the given area. [...]
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?=…, create_build_effect_smoke?=…} |  | Clones the given area. [...]
Clones the given area. [...]
clone_entities{entities=…, destination_offset=…, destination_surface?=…, destination_force?=…, snap_to_grid?=…, create_build_effect_smoke?=…} |  | Clones the given entities. [...]
Clones the given entities. [...]
clear(ignore_characters?) |  | Clears this surface deleting all entities and chunks on it.
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?=…, max_gap_size?=…, max_attack_distance?=…, entity_to_ignore?=…} | → uint32 | Generates a path with the specified constraints (as an array of PathfinderWaypoints) using the unit pathfinding algorithm. [...]
Generates a path with the specified constraints (as an array of PathfinderWaypoints) using the unit pathfinding algorithm. [...]
get_script_areas(name?) | → array[ScriptArea] | Gets the script areas that match the given name or if no name is given all areas are returned.
Gets the script areas that match the given name or if no name is given all areas are returned.
get_script_area(key?) | → ScriptArea? | Gets the first script area by name or id.
Gets the first script area by name or id.
edit_script_area(id, area) |  | Sets the given script area to the new values.
Sets the given script area to the new values.
add_script_area(area) | → uint32 | Adds the given script area.
Adds the given script area.
remove_script_area(id) | → boolean | Removes the given script area.
Removes the given script area.
get_script_positions(name?) | → array[ScriptPosition] | Gets the script positions that match the given name or if no name is given all positions are returned.
Gets the script positions that match the given name or if no name is given all positions are returned.
get_script_position(key?) | → ScriptPosition? | Gets the first script position by name or id.
Gets the first script position by name or id.
edit_script_position(id, position) |  | Sets the given script position to the new values.
Sets the given script position to the new values.
add_script_position(position) | → uint32 | Adds the given script position.
Adds the given script position.
remove_script_position(id) | → boolean | Removes the given script position.
Removes the given script position.
get_map_exchange_string() | → string | Gets the map exchange string for the current map generation settings of this surface.
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.
Gets the starting area radius of this surface.
get_closest(position, entities) | → LuaEntity? | Gets the closest entity in the list to this position.
Gets the closest entity in the list to this position.
get_total_pollution() | → double | Gets the total amount of pollution on the surface by iterating over all the chunks containing pollution.
Gets the total amount of pollution on the surface by iterating over all the chunks containing pollution.
entity_prototype_collides(prototype, position, use_map_generation_bounding_box, direction?) | → boolean | Whether the given entity prototype collides at the given position and direction.
Whether the given entity prototype collides at the given position and direction.
decorative_prototype_collides(prototype, position) | → boolean | Whether the given decorative prototype collides at the given position and direction.
Whether the given decorative prototype collides at the given position and direction.
calculate_tile_properties(property_names, positions) | → dictionary[string → array[double]] | Calculate values for a list of tile properties at a list of positions. [...]
Calculate values for a list of tile properties at a list of positions. [...]
get_entities_with_force(chunk_position, force) | → array[LuaEntity] | Returns all the military targets (entities with force) on this chunk for the given force.
Returns all the military targets (entities with force) on this chunk for the given force.
create_entities_from_blueprint_string{string=…, position=…, force?=…, direction?=…, flip_horizontal?=…, flip_vertical?=…, by_player?=…} | → int32? | This method only works when used in simulations. [...]
This method only works when used in simulations. [...]
build_checkerboard(area) |  | Sets the given area to the checkerboard lab tiles.
Sets the given area to the checkerboard lab tiles.
get_property(property) | → double | Gets the value of surface property on this surface.
Gets the value of surface property on this surface.
set_property(property, value) |  | Sets the value of surface property on this surface.
Sets the value of surface property on this surface.
create_global_electric_network() |  | Creates a global electric network for this surface, if one doesn't exist already.
Creates a global electric network for this surface, if one doesn't exist already.
destroy_global_electric_network() |  | Destroys the global electric network for this surface, if it exists.
Destroys the global electric network for this surface, if it exists.
execute_lightning{name=…, position=…} |  | Creates lightning. [...]
Creates lightning. [...]
clear_hidden_tiles() |  | Completely removes hidden and double hidden tiles data on this surface.
Completely removes hidden and double hidden tiles data on this surface.
get_default_cover_tile(force, tile) | → LuaTilePrototype? | Gets the cover tile for the given force and tile on this surface if one is set.
Gets the cover tile for the given force and tile on this surface if one is set.
set_default_cover_tile(force, from_tile, to_tile) |  | Sets the cover tile for the given force and tile on this surface.
Sets the cover tile for the given force and tile on this surface.
name | :: RW string | The name of this surface. [...]
The name of this surface. [...]
index | :: R uint32 | This surface's index in LuaGameScript::surfaces (unique ID). [...]
This surface's index in LuaGameScript::surfaces (unique ID). [...]
map_gen_settings | :: RW MapGenSettings | The generation settings for this surface. [...]
The generation settings for this surface. [...]
generate_with_lab_tiles | :: RW boolean | When set to true, new chunks will be generated with lab tiles, instead of using the surface's map generation settings.
When set to true, new chunks will be generated with lab tiles, instead of using the surface's map generation settings.
always_day | :: RW boolean | When set to true, the sun will always shine.
When set to true, the sun will always shine.
daytime | :: RW double | Current time of day, as a number in range `[0, 1)`.
Current time of day, as a number in range `[0, 1)`.
darkness | :: R float | Amount of darkness at the current time, as a number in range `[0, 1]`.
Amount of darkness at the current time, as a number in range `[0, 1]`.
wind_speed | :: RW double | Current wind speed in tiles per tick.
Current wind speed in tiles per tick.
wind_orientation | :: RW RealOrientation | Current wind direction.
Current wind direction.
wind_orientation_change | :: RW double | Change in wind orientation per tick.
Change in wind orientation per tick.
peaceful_mode | :: RW boolean | Is peaceful mode enabled on this surface?
Is peaceful mode enabled on this surface?
no_enemies_mode | :: RW boolean | Is no-enemies mode enabled on this surface?
Is no-enemies mode enabled on this surface?
freeze_daytime | :: RW boolean | True if daytime is currently frozen.
True if daytime is currently frozen.
ticks_per_day | :: RW uint32 | The number of ticks per day for this surface.
The number of ticks per day for this surface.
dusk | :: RW double | The daytime when dusk starts.
The daytime when dusk starts.
dawn | :: RW double | The daytime when dawn starts.
The daytime when dawn starts.
evening | :: RW double | The daytime when evening starts.
The daytime when evening starts.
morning | :: RW double | The daytime when morning starts.
The daytime when morning starts.
daytime_parameters | :: RW table | Parameters of daytime. [...]
Parameters of daytime. [...]
solar_power_multiplier | :: RW double | The multiplier of solar power on this surface. [...]
The multiplier of solar power on this surface. [...]
min_brightness | :: RW double | The minimal brightness during the night. [...]
The minimal brightness during the night. [...]
brightness_visual_weights | :: RW ColorModifier | Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT). [...]
Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT). [...]
show_clouds | :: RW boolean | If clouds are shown on this surface. [...]
If clouds are shown on this surface. [...]
has_global_electric_network | :: R boolean | Whether this surface currently has a global electric network.
Whether this surface currently has a global electric network.
platform | :: R LuaSpacePlatform? |
planet | :: R LuaPlanet? | The planet associated with this surface, if there is one. [...]
The planet associated with this surface, if there is one. [...]
deletable | :: R boolean | If this surface can be deleted.
If this surface can be deleted.
global_effect | :: RW ModuleEffects? | Surface-wide effects applied to entities with effect receivers. [...]
Surface-wide effects applied to entities with effect receivers. [...]
pollutant_type | :: R LuaAirbornePollutantPrototype? | The type of pollutant enabled on the surface, or `nil` if no pollutant is enabled.
The type of pollutant enabled on the surface, or `nil` if no pollutant is enabled.
localised_name | :: RW LocalisedString? | Localised name of this surface. [...]
Localised name of this surface. [...]
ignore_surface_conditions | :: RW boolean | If surface condition checks should not be performed on this surface.
If surface condition checks should not be performed on this surface.
pollution_statistics | :: R LuaFlowStatistics | The pollution statistics for this surface.
The pollution statistics for this surface.
global_electric_network_statistics | :: R LuaFlowStatistics? | The global electric network statistics for this surface.
The global electric network statistics for this surface.
valid | :: R boolean | Is this object valid? [...]
Is this object valid? [...]
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]

## Methods

### get_pollution(position) → double

Get the pollution for a given position.

Pollution is stored per chunk, so this will return the same value for all positions in one chunk.

#### Parameters

position | :: MapPosition | The position to poll the chunk's pollution
The position to poll the chunk's pollution

#### Example

    game.surfaces[1].get_pollution({1,2})

### set_pollution(position, amount)

Set the pollution for a given position.

Pollution changes by this are not included in pollution statistics and do not affect evolution factors (as opposed to LuaSurface::pollute).

#### Parameters

position | :: MapPosition | The position to set the chunk's pollution
The position to set the chunk's pollution
amount | :: double | New amount of pollution to be set on the chunk. Must be >= 0.
New amount of pollution to be set on the chunk. Must be >= 0.

### can_place_entity{name=…, position=…, direction?=…, force?=…, build_check_type?=…, forced?=…, inner_name?=…} → boolean

Check for collisions with terrain or other entities.

#### Parameters

Table with the following fields:

name | :: EntityID | Name of the entity prototype to check.
Name of the entity prototype to check.
position | :: MapPosition | Where the entity would be placed.
Where the entity would be placed.
direction | :: defines.direction? | Direction of the placed entity. Defaults to `north`.
Direction of the placed entity. Defaults to `north`.
force | :: ForceID? | The force that would place the entity. Defaults to the `"neutral"` force.
The force that would place the entity. Defaults to the `"neutral"` force.
build_check_type | :: defines.build_check_type? | Which type of check should be carried out. Defaults to `ghost_revive`.
Which type of check should be carried out. Defaults to `ghost_revive`.
forced | :: boolean? | If `true`, entities that can be marked for deconstruction are ignored. Only used if `build_check_type` is either `manual_ghost`, `script_ghost` or `blueprint_ghost`. Defaults to `false`.
If `true`, entities that can be marked for deconstruction are ignored. Only used if `build_check_type` is either `manual_ghost`, `script_ghost` or `blueprint_ghost`. Defaults to `false`.
inner_name | :: string? | The prototype name of the entity contained in the ghost. Only used if `name` is `entity-ghost`.
The prototype name of the entity contained in the ghost. Only used if `name` is `entity-ghost`.

### 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 | :: EntityID | Name of the entity to check.
Name of the entity to check.
position | :: MapPosition | Where the entity would be placed.
Where the entity would be placed.
direction | :: defines.direction? | Direction the entity would be placed. Defaults to `north`.
Direction the entity would be placed. Defaults to `north`.
force | :: ForceID? | The force that would place the entity. Defaults to the `"neutral"` force.
The force that would place the entity. Defaults to the `"neutral"` force.

### find_entity(entity, position) → LuaEntity?

Find an entity of the given name at the given position. This checks both the exact position and the bounding box of the entity.

#### Parameters

entity | :: EntityWithQualityID | Name of the entity to look for.
Name of the entity to look for.
position | :: MapPosition | Coordinates to look at.
Coordinates to look at.

#### Return values

→ LuaEntity? | `nil` if no such entity is found.

#### Example

    game.player.selected.surface.find_entity('filter-inserter', {0,0})

### find_entities(area?) → array[LuaEntity]

Find entities in a given area.

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

#### Parameters

area | :: BoundingBox? |

#### Example

    -- Will evaluate to a list of all entities within given area.
    game.surfaces["nauvis"].find_entities({{-10, -10}, {10, 10}})

### find_entities_filtered(filter) → array[LuaEntity]

Find all entities of the given type or name in the given area.

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

- If no `area` or `position` are given, the entire surface is searched.

- If `position` is given, this returns the entities colliding with that position (i.e the given position is within the entity's collision box).

- If `position` and `radius` are given, this returns the entities within the radius of the position. Looks for the center of entities.

- If `area` is specified, this returns the entities colliding with that area.

#### Parameters

filter | :: EntitySearchFilters |

#### 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(filter) → array[LuaTile]

Find all tiles of the given name in the given area.

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

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

#### Parameters

filter | :: TileSearchFilters |

### count_entities_filtered(filter) → uint32

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` or `position` are given, the entire surface is searched.

- If `position` is given, this returns the entities colliding with that position (i.e the given position is within the entity's collision box).

- If `position` and `radius` are given, this returns entities in the radius of the position.

- If `area` is specified, this returns entities colliding with that area.

#### Parameters

filter | :: EntitySearchFilters |

### count_tiles_filtered(filter) → uint32

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` or `position` and `radius` is given, the entire surface is searched. If `position` and `radius` are given, only tiles within the radius of the position are included.

#### Parameters

filter | :: TileSearchFilters |

### find_non_colliding_position(name, center, radius, precision, force_to_tile_center?) → MapPosition?

Find a non-colliding position within a given radius.

Special care needs to be taken when using a radius of `0`. The game will not stop searching until it finds a suitable position, so it is important to make sure such a position exists. One particular case where it would not be able to find a solution is running it before any chunks have been generated.

#### Parameters

name | :: EntityID | Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.)
Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.)
center | :: MapPosition | Center of the search area.
Center of the search area.
radius | :: double | Max distance from `center` to search in. A radius of `0` means an infinitely-large search area.
Max distance from `center` to search in. A radius of `0` means an infinitely-large search area.
precision | :: double | The step length from the given position as it searches, in tiles. Minimum value is `0.01`.
The step length from the given position as it searches, in tiles. Minimum value is `0.01`.
force_to_tile_center | :: boolean? | 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. Defaults to `false`.
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. Defaults to `false`.

#### Return values

→ MapPosition? | 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?) → MapPosition?

Find a non-colliding position within a given rectangle.

#### Parameters

name | :: EntityID | Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.)
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.
The rectangle to search inside.
precision | :: double | The step length from the given position as it searches, in tiles. Minimum value is 0.01.
The step length from the given position as it searches, in tiles. Minimum value is 0.01.
force_to_tile_center | :: boolean? | 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. Defaults to `false`.
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. Defaults to `false`.

#### Return values

→ MapPosition? | The non-colliding position. May be `nil` if no suitable position was found.

### spill_item_stack{position=…, stack=…, enable_looted?=…, force?=…, allow_belts?=…, max_radius?=…, use_start_position_on_failure?=…, drop_full_stack?=…} → array[LuaEntity]

Spill items on the ground centered at a given location.

#### Parameters

Table with the following fields:

position | :: MapPosition | Center of the spillage
Center of the spillage
stack | :: ItemStackIdentification | Stack of items to spill
Stack of items to spill
enable_looted | :: boolean? | When true, each created item will be flagged with the LuaEntity::to_be_looted flag. Defaults to `false`.
When true, each created item will be flagged with the LuaEntity::to_be_looted flag. Defaults to `false`.
force | :: ForceID? | When provided (and not `nil`) the items will be marked for deconstruction by this force.
When provided (and not `nil`) the items will be marked for deconstruction by this force.
allow_belts | :: boolean? | Whether items can be spilled onto belts. Defaults to `true`.
Whether items can be spilled onto belts. Defaults to `true`.
max_radius | :: double? | Max radius from the specified `position` to spill items.
Max radius from the specified `position` to spill items.
use_start_position_on_failure | :: boolean? | Allow spilling items at `position` if no non-colliding position is found. Note: Setting to false might cause some items not to be spilled. Defaults to `true`.
Allow spilling items at `position` if no non-colliding position is found. Note: Setting to false might cause some items not to be spilled. Defaults to `true`.
drop_full_stack | :: boolean? | If item on ground should be made out of an entire provided stack. Defaults to `false`.
If item on ground should be made out of an entire provided stack. Defaults to `false`.

#### Return values

→ array[LuaEntity] | The created item-on-ground entities.

### spill_inventory{position=…, inventory=…, enable_looted?=…, force?=…, allow_belts?=…, max_radius?=…, use_start_position_on_failure?=…, drop_full_stack?=…} → array[LuaEntity]

Spill inventory on the ground centered at a given location.

#### Parameters

Table with the following fields:

position | :: MapPosition | Center of the spillage
Center of the spillage
inventory | :: LuaInventory | Inventory to spill
Inventory to spill
enable_looted | :: boolean? | When true, each created item will be flagged with the LuaEntity::to_be_looted flag. Defaults to `false`.
When true, each created item will be flagged with the LuaEntity::to_be_looted flag. Defaults to `false`.
force | :: ForceID? | When provided (and not `nil`) the items will be marked for deconstruction by this force.
When provided (and not `nil`) the items will be marked for deconstruction by this force.
allow_belts | :: boolean? | Whether items can be spilled onto belts. Defaults to `true`.
Whether items can be spilled onto belts. Defaults to `true`.
max_radius | :: double? | Max radius from the specified `position` to spill items.
Max radius from the specified `position` to spill items.
use_start_position_on_failure | :: boolean? | Allow spilling items at `position` if no non-colliding position is found. Note: Setting to false might cause some items not to be spilled. Defaults to `true`.
Allow spilling items at `position` if no non-colliding position is found. Note: Setting to false might cause some items not to be spilled. Defaults to `true`.
drop_full_stack | :: boolean? | If item on ground should be made out of an entire provided stack. Defaults to `false`.
If item on ground should be made out of an entire provided stack. Defaults to `false`.

#### Return values

→ array[LuaEntity] | The created item-on-ground entities.

### find_enemy_units(center, radius, force?) → array[LuaEntity]

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

This is more efficient than LuaSurface::find_entities.

#### Parameters

center | :: MapPosition | Center of the search area
Center of the search area
radius | :: double | Radius of the circular search area
Radius of the circular search area
force | :: ForceID? | Force to find enemies of. If not given, uses the player force.
Force to find enemies of. If not given, uses the player force.

#### 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[LuaEntity]

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

This is more efficient than LuaSurface::find_entities.

#### Parameters

Table with the following fields:

area | :: BoundingBox | Box to find units within.
Box to find units within.
force | :: ForceID | Force performing the search.
Force performing the search.
condition | :: ForceCondition | Only forces which meet the condition will be included in the search.
Only forces which meet the condition will be included in the search.

#### Examples

    -- Find friendly units to "player" force
    local friendly_units = game.player.surface.find_units({area = {{-10, -10},{10, 10}}, force = "player", condition = "friend")

    -- 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 military target (military entity) closest to the given position.

#### Parameters

Table with the following fields:

position | :: MapPosition | Center of the search area.
Center of the search area.
max_distance | :: double | Radius of the circular search area.
Radius of the circular search area.
force | :: ForceID? | The force the result will be an enemy of. Uses the player force if not specified.
The force the result will be an enemy of. Uses the player force if not specified.

#### Return values

→ LuaEntity? | The nearest enemy military target or `nil` if no enemy could be found within the given area.

### find_nearest_enemy_entity_with_owner{position=…, max_distance=…, force?=…} → LuaEntity

Find the enemy entity-with-owner closest to the given position.

#### Parameters

Table with the following fields:

position | :: MapPosition | Center of the search area.
Center of the search area.
max_distance | :: double | Radius of the circular search area.
Radius of the circular search area.
force | :: ForceID? | The force the result will be an enemy of. Uses the player force if not specified.
The force the result will be an enemy of. Uses the player force if not specified.

#### Return values

→ LuaEntity | The nearest enemy entity-with-owner or `nil` if no enemy could be found within the given area.

### set_multi_command{command=…, unit_count=…, force?=…, unit_search_distance?=…} → uint32

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 | :: uint32 | Number of units to give the command to.
Number of units to give the command to.
force | :: ForceID? | Force of the units this command is to be given to. If not specified, uses the enemy force.
Force of the units this command is to be given to. If not specified, uses the enemy force.
unit_search_distance | :: uint32? | Radius to search for units. The search area is centered on the destination of the command. If not specified uses default value of 150.
Radius to search for units. The search area is centered on the destination of the command. If not specified uses default value of 150.

#### Return values

→ uint32 | Number of units actually sent. May be less than `count` if not enough units were available.

### create_entity{name=…, position=…, direction?=…, mirror?=…, quality?=…, force?=…, target?=…, source?=…, cause?=…, snap_to_grid?=…, fast_replace?=…, undo_index?=…, player?=…, character?=…, spill?=…, raise_built?=…, create_build_effect_smoke?=…, spawn_decorations?=…, move_stuck_players?=…, item?=…, preserve_ghosts_and_corpses?=…, register_plant?=…, burner_fuel_inventory?=…} → LuaEntity?

Create an entity on this surface.

#### Parameters

Table with the following fields:

name | :: EntityID | The entity prototype name to create.
The entity prototype name to create.
position | :: MapPosition | Where to create the entity.
Where to create the entity.
direction | :: defines.direction? | Desired orientation of the entity after creation.
Desired orientation of the entity after creation.
mirror | :: boolean? | Whether this entity is mirrored. Defaults to `false`.
Whether this entity is mirrored. Defaults to `false`.
quality | :: QualityID? | Quality of the entity to be created. Defaults to `normal`.
Quality of the entity to be created. Defaults to `normal`.
force | :: ForceID? | Force of the entity, default is enemy.
Force of the entity, default is enemy.
target | :: LuaEntity or MapPosition? | Entity with health for the new entity to target.
Entity with health for the new entity to target.
source | :: LuaEntity or MapPosition? | Source entity. Used for beams, projectiles, and highlight-boxes.
Source entity. Used for beams, projectiles, and highlight-boxes.
cause | :: LuaEntity or ForceID? | Cause entity / force. The entity or force that triggered the chain of events that led to this entity being created. Used for beams, projectiles, stickers, etc. so that the damage receiver can know which entity or force to retaliate against. Defaults to the value of `source`.
Cause entity / force. The entity or force that triggered the chain of events that led to this entity being created. Used for beams, projectiles, stickers, etc. so that the damage receiver can know which entity or force to retaliate against. Defaults to the value of `source`.
snap_to_grid | :: boolean? | If false the exact position given is used to instead of snapping to the normal entity grid. This only applies if the entity normally snaps to the grid.
If false the exact position given is used to instead of snapping to the normal entity grid. This only applies if the entity normally snaps to the grid.
fast_replace | :: boolean? | If true, building will attempt to simulate fast-replace building. Defaults to `false`.
If true, building will attempt to simulate fast-replace building. Defaults to `false`.
undo_index | :: uint32? | The index of the undo item to add this action to. An index of `0` creates a new undo item for it. Defaults to putting it into the appropriate undo item automatically if not specified.
The index of the undo item to add this action to. An index of `0` creates a new undo item for it. Defaults to putting it into the appropriate undo item automatically if not specified.
player | :: PlayerIdentification? | If given set the last_user to this player. If fast_replace is true simulate fast replace using this player. Also the player whose undo queue this action should be added to.
If given set the last_user to this player. If fast_replace is true simulate fast replace using this player. Also the player whose undo queue this action should be added to.
character | :: LuaEntity? | If fast_replace is true simulate fast replace using this character.
If fast_replace is true simulate fast replace using this character.
spill | :: boolean? | 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. Defaults to `true`.
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. Defaults to `true`.
raise_built | :: boolean? | If true; defines.events.script_raised_built will be fired on successful entity creation. Defaults to `false`.
If true; defines.events.script_raised_built will be fired on successful entity creation. Defaults to `false`.
create_build_effect_smoke | :: boolean? | If false, the building effect smoke will not be shown around the new entity. Defaults to `true`.
If false, the building effect smoke will not be shown around the new entity. Defaults to `true`.
spawn_decorations | :: boolean? | If true, entity types that have spawn_decoration property will apply triggers defined in the property. Defaults to `false`.
If true, entity types that have spawn_decoration property will apply triggers defined in the property. Defaults to `false`.
move_stuck_players | :: boolean? | If true, any characters that are in the way of the entity are teleported out of the way.
If true, any characters that are in the way of the entity are teleported out of the way.
item | :: LuaItemStack? | If provided, the entity will attempt to pull stored values from this item (for example; creating a spidertron from a previously named and mined spidertron)
If provided, the entity will attempt to pull stored values from this item (for example; creating a spidertron from a previously named and mined spidertron)
preserve_ghosts_and_corpses | :: boolean? | If true, colliding ghosts and corpses will not be removed by the creation of some entity types. Defaults to `false`.
If true, colliding ghosts and corpses will not be removed by the creation of some entity types. Defaults to `false`.
register_plant | :: boolean? | If true, plants created will register in any in-range agricultural towers.
If true, plants created will register in any in-range agricultural towers.
burner_fuel_inventory | :: BlueprintInventoryWithFilters? | Used by entities with a burner energy source.
Used by entities with a burner energy source.

Other attributes may be specified depending on the type of entity:

#### `accumulator`

control_behavior | :: AccumulatorBlueprintControlBehavior? |

#### `agricultural-tower`

control_behavior | :: AgriculturalTowerBlueprintControlBehavior? |

#### `ammo-turret`

priority-list | :: array[SlotFilter]? |
ignore-unprioritised | :: boolean? | Defaults to `false`.
Defaults to `false`.
control_behavior | :: TurretBlueprintControlBehavior? |

#### `arithmetic-combinator`

player_description | :: string? |
control_behavior | :: ArithmeticCombinatorBlueprintControlBehavior? |

#### `artillery-flare`

movement | :: Vector |
height | :: float |
vertical_speed | :: float |
frame_speed | :: float |

#### `artillery-projectile`

speed | :: double? | Defaults to 1.
Defaults to 1.

#### `artillery-turret`

artillery_auto_targeting | :: boolean? |
control_behavior | :: ArtilleryTurretBlueprintControlBehavior? |

#### `artillery-wagon`

enable_logistics_while_moving | :: boolean? |
grid | :: array[BlueprintEquipment]? |
orientation | :: RealOrientation? | The orientation of this rolling stock.
The orientation of this rolling stock.
color | :: Color? | The color of this rolling stock, if it supports colors.
The color of this rolling stock, if it supports colors.
copy_color_from_train_stop | :: boolean? |
artillery_auto_targeting | :: boolean? |

#### `assembling-machine`

recipe | :: string? |
recipe_quality | :: string? |
control_behavior | :: AssemblingMachineBlueprintControlBehavior? |

#### `asteroid`

velocity | :: Vector? |

#### `asteroid-collector`

result-inventory | :: BlueprintInventory? |
chunk-filter | :: array[SlotFilter]? |
control_behavior | :: AsteroidCollectorBlueprintControlBehavior? |

#### `beam`

target_position | :: MapPosition? | Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined).
Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined).
source_position | :: MapPosition? | Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined).
Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined).
max_length | :: uint32? | If set, beam will be destroyed when distance between source and target is greater than this value.
If set, beam will be destroyed when distance between source and target is greater than this value.
duration | :: uint32? | If set, beam will be destroyed after this value of ticks.
If set, beam will be destroyed after this value of ticks.
source_offset | :: Vector? | Source position will be offset by this value when rendering the beam.
Source position will be offset by this value when rendering the beam.

#### `car`

enable_logistics_while_moving | :: boolean? |
grid | :: array[BlueprintEquipment]? |
trunk_inventory | :: BlueprintInventoryWithFilters? |
ammo_inventory | :: BlueprintInventoryWithFilters? |
driver_is_main_gunner | :: boolean? |
selected_gun_index | :: ItemStackIndex? |
request_filters | :: BlueprintLogisticSections? |
orientation | :: RealOrientation? |

#### `cargo-landing-pad`

bar | :: uint32? |
request_filters | :: BlueprintLogisticSections? |
control_behavior | :: CargoLandingPadBlueprintControlBehavior? |

#### `cargo-wagon`

enable_logistics_while_moving | :: boolean? |
grid | :: array[BlueprintEquipment]? |
orientation | :: RealOrientation? | The orientation of this rolling stock.
The orientation of this rolling stock.
color | :: Color? | The color of this rolling stock, if it supports colors.
The color of this rolling stock, if it supports colors.
copy_color_from_train_stop | :: boolean? |
inventory | :: BlueprintInventoryWithFilters? |

#### `character-corpse`

inventory_size | :: uint32? |
player_index | :: uint32? |
color | :: Color? |

#### `cliff`

cliff_orientation | :: CliffOrientation? | If not specified, `direction` will be used instead.
If not specified, `direction` will be used instead.

#### `constant-combinator`

player_description | :: string? |
control_behavior | :: ConstantCombinatorBlueprintControlBehavior? |

#### `container`

bar | :: uint32? | Inventory index where the red limiting bar should be set.
Inventory index where the red limiting bar should be set.
control_behavior | :: ContainerBlueprintControlBehavior? |

#### `decider-combinator`

player_description | :: string? |
control_behavior | :: DeciderCombinatorBlueprintControlBehavior? |

#### `deconstructible-tile-proxy`

proxy_type | :: `"cover"` or `"foundation"`? |

#### `display-panel`

text | :: LocalisedString? |
icon | :: SignalID? |
always_show | :: boolean? |
show_in_chart | :: boolean? |
control_behavior | :: DisplayPanelBlueprintControlBehavior? |

#### `electric-energy-interface`

power_production | :: double? |
power_usage | :: double? |
buffer_size | :: double? |

#### `electric-pole`

auto_connect | :: boolean? | True by default. If set to false, created electric pole will not auto connect to neighbour electric poles.
True by default. If set to false, created electric pole will not auto connect to neighbour electric poles.

#### `electric-turret`

priority-list | :: array[SlotFilter]? |
ignore-unprioritised | :: boolean? | Defaults to `false`.
Defaults to `false`.
control_behavior | :: TurretBlueprintControlBehavior? |

#### `entity-ghost`

inner_name | :: string | The prototype name of the entity contained in the ghost.
The prototype name of the entity contained in the ghost.
tags | :: Tags? | The LuaEntity::tags associated with this entity ghost.
The LuaEntity::tags associated with this entity ghost.

#### `tile-ghost`

inner_name | :: string | The prototype name of the tile contained in the ghost.
The prototype name of the tile contained in the ghost.

#### `fire`

initial_ground_flame_count | :: uint8? | With how many small flames should the fire on ground be created. Defaults to the initial flame count of the prototype.
With how many small flames should the fire on ground be created. Defaults to the initial flame count of the prototype.

#### `fluid-turret`

priority-list | :: array[SlotFilter]? |
ignore-unprioritised | :: boolean? | Defaults to `false`.
Defaults to `false`.
control_behavior | :: TurretBlueprintControlBehavior? |

#### `fluid-wagon`

enable_logistics_while_moving | :: boolean? |
grid | :: array[BlueprintEquipment]? |
orientation | :: RealOrientation? | The orientation of this rolling stock.
The orientation of this rolling stock.
color | :: Color? | The color of this rolling stock, if it supports colors.
The color of this rolling stock, if it supports colors.
copy_color_from_train_stop | :: boolean? |

#### `furnace`

control_behavior | :: FurnaceBlueprintControlBehavior? |

#### `highlight-box`

bounding_box | :: BoundingBox? | The bounding box defining the highlight box using absolute map coordinates. If specified, the general `position` parameter still needs to be present, but will be ignored. If not specified, the game falls back to the `source` parameter first, then the `target` parameter second. One of these three parameters need to be specified.
The bounding box defining the highlight box using absolute map coordinates. If specified, the general `position` parameter still needs to be present, but will be ignored. If not specified, the game falls back to the `source` parameter first, then the `target` parameter second. One of these three parameters need to be specified.
box_type | :: CursorBoxRenderType? | Specifies the graphical appearance (color) of the highlight box. Defaults to `"electricity"`.
Specifies the graphical appearance (color) of the highlight box. Defaults to `"electricity"`.
render_player_index | :: uint32? | The player to render the highlight box for. If not provided, it will be rendered for all players.
The player to render the highlight box for. If not provided, it will be rendered for all players.
blink_interval | :: uint32? | The blink interval for this highlight box. Makes it be shown every `blink_interval` ticks. Defaults to `0` (constantly shown).
The blink interval for this highlight box. Makes it be shown every `blink_interval` ticks. Defaults to `0` (constantly shown).
time_to_live | :: uint32? | The amount of time in ticks that the highlight box will exist for. Defaults to existing forever.
The amount of time in ticks that the highlight box will exist for. Defaults to existing forever.

#### `infinity-cargo-wagon`

enable_logistics_while_moving | :: boolean? |
grid | :: array[BlueprintEquipment]? |
orientation | :: RealOrientation? | The orientation of this rolling stock.
The orientation of this rolling stock.
color | :: Color? | The color of this rolling stock, if it supports colors.
The color of this rolling stock, if it supports colors.
copy_color_from_train_stop | :: boolean? |
inventory | :: BlueprintInventoryWithFilters? |
infinity_settings | :: BlueprintInfinityInventorySettings? |

#### `infinity-container`

bar | :: uint32? |
request_filters | :: BlueprintLogisticSections? |
infinity_settings | :: BlueprintInfinityInventorySettings? |
control_behavior | :: LogisticContainerBlueprintControlBehavior? |

#### `infinity-pipe`

infinity_settings | :: InfinityPipeFilter? |

#### `inserter`

filters | :: array[BlueprintItemFilter]? |
filter_mode | :: `"blacklist"` or `"whitelist"`? |
use_filters | :: boolean? | Defaults to `false`.
Defaults to `false`.
drop_position | :: Vector? | Used only if InserterPrototype::allow_custom_vectors is true.
Used only if InserterPrototype::allow_custom_vectors is true.
pickup_position | :: Vector? | Used only if InserterPrototype::allow_custom_vectors is true.
Used only if InserterPrototype::allow_custom_vectors is true.
override_stack_size | :: uint8? |
spoil_priority | :: BlueprintSpoilPriority? |
control_behavior | :: InserterBlueprintControlBehavior? |

#### `item-entity`

stack | :: string or ItemStackDefinition | The stack of items to create. Either the name of an item, which will create a full stack, or a detailed item stack definition.
The stack of items to create. Either the name of an item, which will create a full stack, or a detailed item stack definition.

#### `item-request-proxy`

target | :: LuaEntity | The target items are to be delivered to.
The target items are to be delivered to.
modules | :: array[BlueprintInsertPlan] | The stacks of items to be delivered to target entity from logistic network.
The stacks of items to be delivered to target entity from logistic network.
removal_plan | :: array[BlueprintInsertPlan]? | Specification of items to be removed from the target entity by the logistic network.
Specification of items to be removed from the target entity by the logistic network.

#### `lamp`

color | :: Color? | Defaults to white.
Defaults to white.
always_on | :: boolean? | Defaults to false.
Defaults to false.
control_behavior | :: LampBlueprintControlBehavior? |

#### `lane-splitter`

filter | :: ItemFilter? |
input_priority | :: SplitterPriority? |
output_priority | :: SplitterPriority? |

#### `linked-belt`

type | :: BeltConnectionType? |

#### `linked-container`

link_id | :: uint32? |

#### `loader`

type | :: BeltConnectionType? | Defaults to `"input"`.
Defaults to `"input"`.
filters | :: array[SlotFilter]? |
filter_mode | :: PrototypeFilterMode? |
belt_stack_size_override | :: uint8? |
control_behavior | :: LoaderBlueprintControlBehavior? |

#### `loader-1x1`

type | :: BeltConnectionType? | Defaults to `"input"`.
Defaults to `"input"`.
filters | :: array[SlotFilter]? |
filter_mode | :: PrototypeFilterMode? |
belt_stack_size_override | :: uint8? |
control_behavior | :: LoaderBlueprintControlBehavior? |

#### `locomotive`

enable_logistics_while_moving | :: boolean? |
grid | :: array[BlueprintEquipment]? |
orientation | :: RealOrientation? | The orientation of this rolling stock.
The orientation of this rolling stock.
color | :: Color? | The color of this rolling stock, if it supports colors.
The color of this rolling stock, if it supports colors.
copy_color_from_train_stop | :: boolean? |
snap_to_train_stop | :: boolean? | Whether the locomotive should snap to an adjacent train stop. Defaults to true.
Whether the locomotive should snap to an adjacent train stop. Defaults to true.

#### `logistic-container`

bar | :: uint32? |
request_filters | :: array[SlotFilter]? |
control_behavior | :: LogisticContainerBlueprintControlBehavior? |

#### `mining-drill`

filter | :: BlueprintMiningDrillFilter? |
control_behavior | :: MiningDrillBlueprintControlBehavior? |

#### `particle`

movement | :: Vector |
height | :: float |
vertical_speed | :: float |
frame_speed | :: float |

#### `plant`

tick_grown | :: MapTick? | The tick the plant will be fully grown. If not specified, the plants normal growth time is used.
The tick the plant will be fully grown. If not specified, the plants normal growth time is used.

#### `power-switch`

switch_state | :: boolean? |
control_behavior | :: PowerSwitchBlueprintControlBehavior? |

#### `programmable-speaker`

parameters | :: ProgrammableSpeakerParameters? |
alert_parameters | :: ProgrammableSpeakerAlertParameters? |
control_behavior | :: ProgrammableSpeakerBlueprintControlBehavior? |

#### `projectile`

speed | :: double? | Defaults to 0.
Defaults to 0.
max_range | :: double? | Defaults to 1000.
Defaults to 1000.
base_damage_modifiers | :: TriggerModifierData? |
bonus_damage_modifiers | :: TriggerModifierData? |

#### `proxy-container`

control_behavior | :: ProxyContainerBlueprintControlBehavior? |

#### `pump`

fluid_filter | :: string? |
control_behavior | :: PumpBlueprintControlBehavior? |

#### `rail-chain-signal`

rail_layer | :: defines.rail_layer? | Defaults to defines.rail_layer.ground.
Defaults to defines.rail_layer.ground.
control_behavior | :: RailSignalBaseBlueprintControlBehavior? |

#### `rail-signal`

rail_layer | :: defines.rail_layer? | Defaults to defines.rail_layer.ground.
Defaults to defines.rail_layer.ground.
control_behavior | :: RailSignalBaseBlueprintControlBehavior? |

#### `reactor`

control_behavior | :: ReactorBlueprintControlBehavior? |

#### `resource`

amount | :: uint32? |
enable_tree_removal | :: boolean? | If colliding trees are removed normally for this resource entity based off the prototype tree removal values. Default is true.
If colliding trees are removed normally for this resource entity based off the prototype tree removal values. Default is true.
enable_cliff_removal | :: boolean? | If colliding cliffs are removed. Default is true.
If colliding cliffs are removed. Default is true.
snap_to_tile_center | :: boolean? | If true, the resource entity will be placed to center of a tile as map generator would place it, otherwise standard non-resource grid alignment rules will apply. Default is true.
If true, the resource entity will be placed to center of a tile as map generator would place it, otherwise standard non-resource grid alignment rules will apply. Default is true.

#### `roboport`

request_filters | :: BlueprintLogisticSections? |
control_behavior | :: RoboportBlueprintControlBehavior? |

#### `rocket-silo`

recipe | :: string? |
recipe_quality | :: string? |
use_transitional_requests | :: boolean? |
launch_to_orbit_automatically | :: boolean? |
control_behavior | :: RocketSiloBlueprintControlBehavior? |

#### `selector-combinator`

player_description | :: string? |
control_behavior | :: SelectorCombinatorParameters? |

#### `simple-entity-with-force`

render_player_index | :: uint32? |
color | :: Color? |
variation | :: uint8? |

#### `simple-entity-with-owner`

render_player_index | :: uint32? |
color | :: Color? |
variation | :: uint8? |

#### `space-platform-hub`

bar | :: ItemStackIndex? |
request_filters | :: BlueprintLogisticSections? |
request_missing_construction_materials | :: boolean? |
control_behavior | :: SpacePlatformHubBlueprintControlBehavior? |

#### `speech-bubble`

text | :: LocalisedString |
lifetime | :: uint32? |

#### `splitter`

filter | :: ItemFilter? |
input_priority | :: SplitterPriority? |
output_priority | :: SplitterPriority? |
control_behavior | :: SplitterBlueprintControlBehavior? |

#### `spider-vehicle`

enable_logistics_while_moving | :: boolean? |
grid | :: array[BlueprintEquipment]? |
trunk_inventory | :: BlueprintInventoryWithFilters? |
ammo_inventory | :: BlueprintInventoryWithFilters? |
driver_is_main_gunner | :: boolean? |
automatic_targeting_parameters | :: VehicleAutomaticTargetingParameters? |
selected_gun_index | :: ItemStackIndex? |
request_filters | :: BlueprintLogisticSections? |
color | :: Color? |
label | :: string? |

#### `storage-tank`

control_behavior | :: StorageTankBlueprintControlBehavior? |

#### `stream`

target_position | :: MapPosition? | Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined).
Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined).
source_position | :: MapPosition? | Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined).
Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined).

#### `train-stop`

color | :: Color? |
station | :: string? |
manual_trains_limit | :: uint32? |
priority | :: uint8? |
control_behavior | :: TrainStopBlueprintControlBehavior? |

#### `transport-belt`

control_behavior | :: TransportBeltBlueprintControlBehavior? |

#### `turret`

priority-list | :: array[SlotFilter]? |
ignore-unprioritised | :: boolean? | Defaults to `false`.
Defaults to `false`.
control_behavior | :: TurretBlueprintControlBehavior? |

#### `underground-belt`

type | :: BeltConnectionType? | Defaults to `"input"`.
Defaults to `"input"`.

#### `valve`

valve_threshold_override | :: float? |

#### `wall`

control_behavior | :: WallBlueprintControlBehavior? |

#### Return values

→ LuaEntity? | The created entity or `nil` if the creation failed.

#### Raised events

script_raised_built? instantly | Raised if the `raise_built` flag was set and the entity was successfully created.

#### Examples

    local asm = game.surfaces[1].create_entity{name = "assembling-machine-1", position = {15, 3}, force = game.forces.player, recipe = "iron-stick"}

    -- 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"}}
    }

    -- Creates a requester chest already set to request 128 iron plates.
    game.surfaces[1].create_entity{
      name = "requester-chest", position = {game.player.position.x+3, game.player.position.y},
      force = game.player.force, request_filters = {{index = 1, name = "iron-plate", count = 128}}
    }

    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

    -- 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_segmented_unit{name=…, quality?=…, force?=…, territory?=…} → LuaSegmentedUnit?

Create a segmented unit on the surface. This differs from creating an entity with type `"segmented-unit"` in that this method can create the entity in non-generated chunks and with any arbitrary body shape and pre-assigned to a territory.

#### Parameters

Table with the following fields:

name | :: EntityID | The segmented-unit prototype name to create. Must be of type `"segmented-unit"`.
The segmented-unit prototype name to create. Must be of type `"segmented-unit"`.
quality | :: QualityID? | Quality of the entity to be created. Defaults to `normal`.
Quality of the entity to be created. Defaults to `normal`.
force | :: ForceID? | Force of the segmented unit. Defaults to `enemy`.
Force of the segmented unit. Defaults to `enemy`.
territory | :: LuaTerritory? | The territory that the segmented unit is assigned to. If `nil`, the segmented unit will patrol around its spawn location. Must be located on this same surface.
The territory that the segmented unit is assigned to. If `nil`, the segmented unit will patrol around its spawn location. Must be located on this same surface.

These attributes provide different methods of specifying the unit's spawn location:

#### `position-and-direction`

position | :: MapPosition | The head position.
The head position.
direction | :: defines.direction? | The initial orientation of the head. Defaults to `defines.direction.north`.
The initial orientation of the head. Defaults to `defines.direction.north`.
extended | :: boolean? | If `true`, will create the segmented unit so that the entire body is stretches in a straight line behind the head. If `false`, then only the head segment will be created and the remainder of the body segments will be created over time as the head moves forward. Defaults to `false`.
If `true`, will create the segmented unit so that the entire body is stretches in a straight line behind the head. If `false`, then only the head segment will be created and the remainder of the body segments will be created over time as the head moves forward. Defaults to `false`.

#### `body-nodes`

body_nodes | :: array[MapPosition] | The body nodes that define the shape of the body. The array must contain at least one value and should have no more than SegmentEngineSpecification::max_body_nodes. The nodes should be about 1 tile apart from each other, but it is not strictly required.
The body nodes that define the shape of the body. The array must contain at least one value and should have no more than SegmentEngineSpecification::max_body_nodes. The nodes should be about 1 tile apart from each other, but it is not strictly required.

#### Return values

→ LuaSegmentedUnit? | The created segmented unit or `nil` if the creation failed or the unit was destroyed during creation.

#### Raised events

on_segmented_unit_created? instantly | Raised if the segmented unit was successfully created. cause will be set to script_created.

### create_territory{chunks=…, patrol_path?=…} → LuaTerritory?

Create a territory on the surface.

#### Parameters

Table with the following fields:

chunks | :: array[ChunkPosition] | The chunks to assign to the new territory. Must contain at least one generated chunk. Any chunks already assigned to existing territories will be removed from those territories. Any territories left with no generated chunks will be deleted from the surface as a result.
The chunks to assign to the new territory. Must contain at least one generated chunk. Any chunks already assigned to existing territories will be removed from those territories. Any territories left with no generated chunks will be deleted from the surface as a result.
patrol_path | :: array[MapPosition]? | The path that patrolling units will follow. If `nil` or empty, one will be generated for the new territory based on `chunks`.
The path that patrolling units will follow. If `nil` or empty, one will be generated for the new territory based on `chunks`.

#### Return values

→ LuaTerritory? | The created territory or `nil` if the creation failed or the territory was destroyed during creation.

#### Raised events

on_territory_created? instantly | Raised if the territory was successfully created.

### create_trivial_smoke{name=…, position=…}

#### Parameters

Table with the following fields:

name | :: TrivialSmokeID | The smoke prototype name to create.
The smoke prototype name to create.
position | :: MapPosition | Where to create the smoke.
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:

name | :: ParticleID | The particle name.
The particle name.
position | :: MapPosition | Where to create the particle.
Where to create the particle.
movement | :: Vector |
height | :: float |
vertical_speed | :: float |
frame_speed | :: float |

### create_unit_group{position=…, force?=…} → LuaCommandable

Create a new unit group at a given position.

#### Parameters

Table with the following fields:

position | :: MapPosition | Initial position of the new unit group.
Initial position of the new unit group.
force | :: ForceID? | Force of the new unit group. Defaults to `"enemy"`.
Force of the new unit group. Defaults to `"enemy"`.

#### Raised events

on_unit_group_created instantly |

### build_enemy_base(position, unit_count, force?)

Send a group to build a new base.

The specified force must be AI-controlled; i.e. `force.ai_controllable` must be `true`.

#### Parameters

position | :: MapPosition | Location of the new base.
Location of the new base.
unit_count | :: uint32 | Number of biters to send for the base-building task.
Number of biters to send for the base-building task.
force | :: ForceID? | Force the new base will belong to. Defaults to enemy.
Force the new base will belong to. Defaults to enemy.

### get_tile(x, y) → LuaTile

Get the tile at a given position. An alternative call signature for this method is passing it a single TilePosition.

Non-integer values will result in them being rounded down.

#### Parameters

x | :: int32 |
y | :: int32 |

### set_tiles(tiles, correct_tiles?, remove_colliding_entities?, remove_colliding_decoratives?, raise_event?, player?, undo_index?)

Set tiles at specified locations. Can automatically correct the edges around modified tiles.

Placing a mineable tile on top of a non-mineable or foundation one will turn the latter into the LuaTile::hidden_tile for that tile. Placing a mineable non-foundation tile on a mineable non-foundation one or a mineable foundation tile on a mineable foundation one will not modify the hidden tile. This restriction can however be circumvented by using LuaSurface::set_hidden_tile. Placing a non-foundation tile on top of a foundation one when there already exists a hidden tile will push hidden tile to double hidden, and foundation tile will turn into hidden. Placing a mineable foundation tile over a mineable non-foundation tile with hidden mineable foundation tile, the hidden tile will be replaced by previously double hidden tile and double hidden tile will be erased. Placing a non-mineable tile will erase hidden and double hidden tiles.

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. Also, many small API calls are generally more performance intensive than one big one.

#### Parameters

tiles | :: array[Tile] |
correct_tiles | :: boolean? | If `false`, the correction logic is not applied to the changed tiles. Defaults to `true`.
If `false`, the correction logic is not applied to the changed tiles. Defaults to `true`.
remove_colliding_entities | :: boolean or `"abort_on_collision"`? | Defaults to `true`.
Defaults to `true`.
remove_colliding_decoratives | :: boolean? | Defaults to `true`.
Defaults to `true`.
raise_event | :: boolean? | Defaults to `false`.
Defaults to `false`.
player | :: PlayerIdentification? | The player whose undo queue to add these actions to.
The player whose undo queue to add these actions to.
undo_index | :: uint32? | The index of the undo item to add this action to. An index of `0` creates a new undo item for it. Defaults to putting it into the appropriate undo item automatically if not specified.
The index of the undo item to add this action to. An index of `0` creates a new undo item for it. Defaults to putting it into the appropriate undo item automatically if not specified.

#### Raised events

script_raised_set_tiles? instantly | Raised if the `raise_event` flag was set.

### pollute(source, amount, prototype?)

Spawn pollution at the given position.

#### Parameters

source | :: MapPosition | Where to spawn the pollution.
Where to spawn the pollution.
amount | :: double | How much pollution to add.
How much pollution to add.
prototype | :: EntityID? | The entity prototype to attribute the pollution change to in statistics. If not defined, the pollution change will not show up in statistics.
The entity prototype to attribute the pollution change to in statistics. If not defined, the pollution change will not show up in statistics.

### get_chunks() → LuaChunkIterator

Get an iterator going over every chunk on this surface.

Chunks may or may not be generated; use LuaSurface::is_chunk_generated to check a chunk's state before accessing it.

### is_chunk_generated(chunk_position) → boolean

Is a given chunk generated?

#### Parameters

chunk_position | :: ChunkPosition | The chunk's position.
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. If the radius is `0`, then only the chunk at the given position is generated.

#### Parameters

position | :: MapPosition | Where to generate the new chunks.
Where to generate the new chunks.
radius | :: uint32? | The chunk radius from `position` to generate new chunks in. Defaults to `0`.
The chunk radius from `position` to generate new chunks in. Defaults to `0`.

### force_generate_chunk_requests()

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

### set_chunk_generated_status(chunk_position, status)

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

#### Parameters

chunk_position | :: ChunkPosition | The chunk's position.
The chunk's position.
status | :: defines.chunk_generated_status | The chunk's new status.
The chunk's new status.

### get_territories() → array[LuaTerritory]

Get all territories on the surface.

### get_territory_for_chunk(chunk_position) → LuaTerritory?

Get the territory that the given chunk is assigned to. If the chunk is not part of any territory or the territory for the chunk has not yet been generated, then this returns `nil`.

#### Parameters

chunk_position | :: ChunkPosition | The chunk's position. The chunk at this position does not need to exist.
The chunk's position. The chunk at this position does not need to exist.

### set_territory_for_chunks(chunk_positions, territory?)

Removes the given chunks from their current territories and adds them to the given territory if provided.

This does not affect the LuaTerritory::get_patrol_path. It is your responsibility to update the patrol path if needed.

It's recommended that territory chunks are connected to each other, but this is not required.

Territories that do not contain at least one generated chunk as a result of calling this method will be automatically deleted.

#### Parameters

chunk_positions | :: array[ChunkPosition] | The chunk positions. The chunks at these positions do not need to exist in order to be assigned to a territory.
The chunk positions. The chunks at these positions do not need to exist in order to be assigned to a territory.
territory | :: LuaTerritory? | The territory to associate the chunks with. If not `nil`, the territory must belong to this same surface or else an error will be produced. If `nil`, then the chunks get removed from the territory it is currently associated with and will prevent the map generator from automatically re-generate a new territory for the chunk in the future.
The territory to associate the chunks with. If not `nil`, the territory must belong to this same surface or else an error will be produced. If `nil`, then the chunks get removed from the territory it is currently associated with and will prevent the map generator from automatically re-generate a new territory for the chunk in the future.

#### Raised events

on_territory_destroyed? instantly | Raised for each territory that is destroyed as a result of calling this method.

### clear_territory_for_chunks(chunk_positions)

Removes the chunk from the territory it is associated with (if any) and allows the map generator to potentially generate a new territory for the chunk in the future. To prevent the game from generating a new territory for the chunk, use LuaSurface::set_chunk_territory to set the chunk's territory to `nil`.

Territories that do not contain at least one generated chunk as a result of calling this method will be automatically deleted.

#### Parameters

chunk_positions | :: array[ChunkPosition] | The chunk positions. The chunks at these positions does not need to exist.
The chunk positions. The chunks at these positions does not need to exist.

### get_segmented_units() → array[LuaSegmentedUnit]

Get all segmented units that exist on the surface.

### find_logistic_network_by_position(position, force) → LuaLogisticNetwork?

Find the logistic network that covers a given position.

#### Parameters

position | :: MapPosition |
force | :: ForceID | Force the logistic network should belong to.
Force the logistic network should belong to.

#### Return values

→ LuaLogisticNetwork? | The found network or `nil` if no such network was found.

### find_closest_logistic_network_by_position(position, force) → LuaLogisticNetwork?

Find the logistic network with a cell closest to a given position.

#### Parameters

position | :: MapPosition |
force | :: ForceID | Force the logistic network should belong to.
Force the logistic network should belong to.

#### Return values

→ LuaLogisticNetwork? | The found network or `nil` if no such network was found.

### find_logistic_networks_by_construction_area(position, force) → array[LuaLogisticNetwork]

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

#### Parameters

position | :: MapPosition |
force | :: ForceID | Force the logistic networks should belong to.
Force the logistic networks should belong to.

### deconstruct_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item?=…, super_forced?=…}

Place a deconstruction request.

#### Parameters

Table with the following fields:

area | :: BoundingBox | The area to mark for deconstruction.
The area to mark for deconstruction.
force | :: ForceID | The force whose bots should perform the deconstruction.
The force whose bots should perform the deconstruction.
player | :: PlayerIdentification? | The player to set the last_user to if any.
The player to set the last_user to if any.
skip_fog_of_war | :: boolean? | If chunks covered by fog-of-war are skipped. Defaults to `false`.
If chunks covered by fog-of-war are skipped. Defaults to `false`.
item | :: LuaItemStack? | The deconstruction item to use if any.
The deconstruction item to use if any.
super_forced | :: boolean? | If the deconstruction is super-forced. Defaults to `false`.
If the deconstruction is super-forced. Defaults to `false`.

#### Raised events

on_marked_for_deconstruction? instantly | Raised for every entity that has been successfully marked for deconstruction.

### cancel_deconstruct_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item?=…, undo_index?=…, super_forced?=…}

Cancel a deconstruction order.

#### Parameters

Table with the following fields:

area | :: BoundingBox | The area to cancel deconstruction orders in.
The area to cancel deconstruction orders in.
force | :: ForceID | The force whose deconstruction orders to cancel.
The force whose deconstruction orders to cancel.
player | :: PlayerIdentification? | The player to set the last_user to, if any. Also the player whose undo queue this action should be added to.
The player to set the last_user to, if any. Also the player whose undo queue this action should be added to.
skip_fog_of_war | :: boolean? | If chunks covered by fog-of-war are skipped. Defaults to `false`.
If chunks covered by fog-of-war are skipped. Defaults to `false`.
item | :: LuaItemStack? | The deconstruction item to use if any.
The deconstruction item to use if any.
undo_index | :: uint32? | The index of the undo item to add this action to. An index of `0` creates a new undo item for it. Defaults to putting it into the appropriate undo item automatically if not specified.
The index of the undo item to add this action to. An index of `0` creates a new undo item for it. Defaults to putting it into the appropriate undo item automatically if not specified.
super_forced | :: boolean? | If the cancel deconstruction is super-forced. Defaults to `false`.
If the cancel deconstruction is super-forced. Defaults to `false`.

#### Raised events

on_cancelled_deconstruction? instantly | Raised for every entity whose deconstruction has been successfully cancelled.

### 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.
The area to mark for upgrade.
force | :: ForceID | The force whose bots should perform the upgrade.
The force whose bots should perform the upgrade.
player | :: PlayerIdentification? | The player to set the last_user to if any.
The player to set the last_user to if any.
skip_fog_of_war | :: boolean? | If chunks covered by fog-of-war are skipped.
If chunks covered by fog-of-war are skipped.
item | :: LuaItemStack | The upgrade item to use.
The upgrade item to use.

#### Raised events

on_marked_for_upgrade? instantly | Raised for every entity that has been successfully marked for upgrade.

### 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.
The area to cancel upgrade orders in.
force | :: ForceID | The force whose upgrade orders to cancel.
The force whose upgrade orders to cancel.
player | :: PlayerIdentification? | The player to set the last_user to if any.
The player to set the last_user to if any.
skip_fog_of_war | :: boolean? | If chunks covered by fog-of-war are skipped.
If chunks covered by fog-of-war are skipped.
item | :: LuaItemStack | The upgrade item to use.
The upgrade item to use.

#### Raised events

on_cancelled_upgrade? instantly | Raised for every entity whose upgrade has been successfully cancelled.

### get_hidden_tile(position) → string?

The hidden tile name.

#### Parameters

position | :: TilePosition | The tile position.
The tile position.

#### Return values

→ string? | `nil` if there isn't one for the given position.

### get_double_hidden_tile(position) → string

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

#### Parameters

position | :: TilePosition | The tile position.
The tile position.

### set_hidden_tile(position, tile?)

Set the hidden tile for the specified position. While during normal gameplay only non-mineable or foundation tiles can become hidden, this method allows any kind of tile to be set as the hidden one.

#### Parameters

position | :: TilePosition | The tile position.
The tile position.
tile | :: TileID? | The new hidden tile or `nil` to clear the hidden tile.
The new hidden tile or `nil` to clear the hidden tile.

### set_double_hidden_tile(position, tile?)

Set double hidden tile for the specified position. During normal gameplay, only non-mineable tiles can become double hidden.

Does nothing if hidden tile at specified position does not exist.

#### Parameters

position | :: TilePosition | The tile position.
The tile position.
tile | :: TileID? | The new double hidden tile or `nil` to clear the double hidden tile.
The new double hidden tile or `nil` to clear the double hidden tile.

### get_connected_tiles(position, tiles, include_diagonal?, area?) → array[TilePosition]

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

This won't find tiles in non-generated chunks.

#### Parameters

position | :: TilePosition | The tile position to start at.
The tile position to start at.
tiles | :: array[TileID] | The tiles to search for.
The tiles to search for.
include_diagonal | :: boolean? | Include tiles that are connected diagonally.
Include tiles that are connected diagonally.
area | :: BoundingBox? | The area to find connected tiles in. If provided the start position must be in this area.
The area to find connected tiles in. If provided the start position must be in this area.

#### Return values

→ array[TilePosition] | The resulting set of tiles.

### delete_chunk(chunk_position)

#### Parameters

chunk_position | :: ChunkPosition | The chunk position to delete
The chunk position to delete

#### Raised events

on_pre_chunk_deleted future_tick |
on_chunk_deleted future_tick |
on_territory_destroyed? future_tick | Raised if a territory is automatically destroyed as a result of deleting the chunk.

### regenerate_entity(entities?, chunks?)

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

All specified entity prototypes must be autoplacable. If nothing is given all entities are generated on all chunks.

#### Parameters

entities | :: string or array[string]? | Prototype names of entity or entities to autoplace. When `nil` all entities with an autoplace are used.
Prototype names of entity or entities to autoplace. When `nil` all entities with an autoplace are used.
chunks | :: array[ChunkPosition]? | The chunk positions to regenerate the entities on. If not given all chunks are regenerated. Note chunks with status < entities are ignored.
The chunk positions to regenerate the entities on. If not given all chunks are regenerated. Note chunks with status < entities are ignored.

### regenerate_decorative(decoratives?, chunks?)

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

All specified decorative prototypes must be autoplacable. If nothing is given all decoratives are generated on all chunks.

#### Parameters

decoratives | :: string or array[string]? | Prototype names of decorative or decoratives to autoplace. When `nil` all decoratives with an autoplace are used.
Prototype names of decorative or decoratives to autoplace. When `nil` all decoratives with an autoplace are used.
chunks | :: array[ChunkPosition]? | The chunk positions to regenerate the decoratives on. If not given all chunks are regenerated. Note chunks with status < entities are ignored.
The chunk positions to regenerate the decoratives on. If not given all chunks are regenerated. Note chunks with status < entities are ignored.

### print(message, print_settings?)

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

By default, messages that are identical to a message sent in the last 60 ticks are not printed again.

#### Parameters

message | :: LocalisedString |
print_settings | :: PrintSettings? |

### destroy_decoratives{area?=…, position?=…, name?=…, collision_mask?=…, from_layer?=…, to_layer?=…, exclude_soft?=…, 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:

area | :: BoundingBox? |
position | :: TilePosition? |
name | :: DecorativeID or array[DecorativeID]? |
collision_mask | :: CollisionLayerID or array[CollisionLayerID] or dictionary[CollisionLayerID → `true`]? |
from_layer | :: string? |
to_layer | :: string? |
exclude_soft | :: boolean? | Soft decoratives can be drawn over rails.
Soft decoratives can be drawn over rails.
limit | :: uint32? |
invert | :: boolean? | If the filters should be inverted.
If the filters should be inverted.

### create_decoratives{check_collision?=…, decoratives=…}

Adds the given decoratives to the surface.

This will merge decoratives of the same type that already exist effectively increasing the "amount" field.

#### Parameters

Table with the following fields:

check_collision | :: boolean? | If collision should be checked against entities/tiles.
If collision should be checked against entities/tiles.
decoratives | :: array[Decorative] |

### find_decoratives_filtered{area?=…, position?=…, name?=…, collision_mask?=…, from_layer?=…, to_layer?=…, exclude_soft?=…, limit?=…, invert?=…} → array[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 every given filter. If no area and no position are given, the entire surface is searched.

#### Parameters

Table with the following fields:

area | :: BoundingBox? |
position | :: TilePosition? |
name | :: DecorativeID or array[DecorativeID]? |
collision_mask | :: CollisionLayerID or array[CollisionLayerID] or dictionary[CollisionLayerID → `true`]? |
from_layer | :: string? |
to_layer | :: string? |
exclude_soft | :: boolean? | Soft decoratives can be drawn over rails.
Soft decoratives can be drawn over rails.
limit | :: uint32? |
invert | :: boolean? | If the filters should be inverted.
If the filters should be inverted.

#### 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

### clear_pollution()

Clears all pollution on this surface.

### play_sound(sound_specification)

Play a sound for every player on this surface.

The sound is not played if its location is not charted for that player.

#### Parameters

sound_specification | :: PlaySoundSpecification | The sound to play.
The sound to play.

### get_resource_counts() → dictionary[string → uint32]

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?=…, create_build_effect_smoke?=…}

Clones the given area.

Entities are cloned in an order such that they can always be created, eg rails before trains.

#### Parameters

Table with the following fields:

source_area | :: BoundingBox |
destination_area | :: BoundingBox |
destination_surface | :: SurfaceIdentification? |
destination_force | :: ForceID? |
clone_tiles | :: boolean? | If tiles should be cloned
If tiles should be cloned
clone_entities | :: boolean? | If entities should be cloned
If entities should be cloned
clone_decoratives | :: boolean? | If decoratives should be cloned
If decoratives should be cloned
clear_destination_entities | :: boolean? | If the destination entities should be cleared
If the destination entities should be cleared
clear_destination_decoratives | :: boolean? | If the destination decoratives should be cleared
If the destination decoratives should be cleared
expand_map | :: boolean? | If the destination surface should be expanded when destination_area is outside current bounds. Defaults to `false`.
If the destination surface should be expanded when destination_area is outside current bounds. Defaults to `false`.
create_build_effect_smoke | :: boolean? | If true, the building effect smoke will be shown around the new entities. Defaults to `false`.
If true, the building effect smoke will be shown around the new entities. Defaults to `false`.

#### Raised events

on_entity_cloned instantly | Raised for every entity that was cloned.
on_area_cloned instantly | Raised after the individual `on_entity_cloned` events.

### 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?=…, create_build_effect_smoke?=…}

Clones the given area.

defines.events.on_entity_cloned is raised for each entity, and then defines.events.on_area_cloned is raised.

Entities are cloned in an order such that they can always be created, eg rails before trains.

#### Parameters

Table with the following fields:

source_offset | :: TilePosition |
destination_offset | :: TilePosition |
source_positions | :: array[TilePosition] |
destination_surface | :: SurfaceIdentification? |
destination_force | :: LuaForce or string? |
clone_tiles | :: boolean? | If tiles should be cloned
If tiles should be cloned
clone_entities | :: boolean? | If entities should be cloned
If entities should be cloned
clone_decoratives | :: boolean? | If decoratives should be cloned
If decoratives should be cloned
clear_destination_entities | :: boolean? | If the destination entities should be cleared
If the destination entities should be cleared
clear_destination_decoratives | :: boolean? | If the destination decoratives should be cleared
If the destination decoratives should be cleared
expand_map | :: boolean? | If the destination surface should be expanded when destination_area is outside current bounds. Defaults to `false`.
If the destination surface should be expanded when destination_area is outside current bounds. Defaults to `false`.
manual_collision_mode | :: boolean? | If manual-style collision checks should be done.
If manual-style collision checks should be done.
create_build_effect_smoke | :: boolean? | If true, the building effect smoke will be shown around the new entities.
If true, the building effect smoke will be shown around the new entities.

### clone_entities{entities=…, destination_offset=…, destination_surface?=…, destination_force?=…, snap_to_grid?=…, create_build_effect_smoke?=…}

Clones the given entities.

Entities are cloned in an order such that they can always be created, eg rails before trains.

#### Parameters

Table with the following fields:

entities | :: array[LuaEntity] |
destination_offset | :: Vector |
destination_surface | :: SurfaceIdentification? |
destination_force | :: ForceID? |
snap_to_grid | :: boolean? |
create_build_effect_smoke | :: boolean? | If true, the building effect smoke will be shown around the new entities.
If true, the building effect smoke will be shown around the new entities.

#### Raised events

on_entity_cloned instantly | Raised for every entity that was cloned.

### clear(ignore_characters?)

Clears this surface deleting all entities and chunks on it.

#### Parameters

ignore_characters | :: boolean? | Whether characters on this surface that are connected to or associated with players should be ignored (not destroyed). Defaults to `false`.
Whether characters on this surface that are connected to or associated with players should be ignored (not destroyed). Defaults to `false`.

#### Raised events

on_pre_surface_cleared future_tick |
on_surface_cleared future_tick |

### request_path{bounding_box=…, collision_mask=…, start=…, goal=…, force=…, radius?=…, pathfind_flags?=…, can_open_gates?=…, path_resolution_modifier?=…, max_gap_size?=…, max_attack_distance?=…, entity_to_ignore?=…} → uint32

Generates a path with the specified constraints (as an array of PathfinderWaypoints) using the unit pathfinding algorithm. This path can be used to emulate pathing behavior by script for non-unit entities, such as vehicles. If you want to command actual units (such as biters or spitters) to move, use LuaCommandable::set_command via LuaEntity::commandable instead.

The resulting path is ultimately returned asynchronously via on_script_path_request_finished.

#### Parameters

Table with the following fields:

bounding_box | :: BoundingBox | The dimensions of the object that's supposed to travel the path.
The dimensions of the object that's supposed to travel the path.
collision_mask | :: CollisionMask | The collision mask the `bounding_box` collides with.
The collision mask the `bounding_box` collides with.
start | :: MapPosition | The position from which to start pathfinding.
The position from which to start pathfinding.
goal | :: MapPosition | The position to find a path to.
The position to find a path to.
force | :: ForceID | The force for which to generate the path, determining which gates can be opened for example.
The force for which to generate the path, determining which gates can be opened for example.
radius | :: double? | How close the pathfinder needs to get to its `goal` (in tiles). Defaults to `1`.
How close the pathfinder needs to get to its `goal` (in tiles). Defaults to `1`.
pathfind_flags | :: PathfinderFlags? | Flags that affect pathfinder behavior.
Flags that affect pathfinder behavior.
can_open_gates | :: boolean? | Whether the path request can open gates. Defaults to `false`.
Whether the path request can open gates. Defaults to `false`.
path_resolution_modifier | :: int32? | Defines how coarse the pathfinder's grid is, where smaller values mean a coarser grid. Defaults to `0`, which equals a resolution of `1x1` tiles, centered on tile centers. Values range from `-8` to `8` inclusive, where each integer increment doubles/halves the resolution. So, a resolution of `-8` equals a grid of `256x256` tiles, and a resolution of `8` equals `1/256` of a tile.
Defines how coarse the pathfinder's grid is, where smaller values mean a coarser grid. Defaults to `0`, which equals a resolution of `1x1` tiles, centered on tile centers. Values range from `-8` to `8` inclusive, where each integer increment doubles/halves the resolution. So, a resolution of `-8` equals a grid of `256x256` tiles, and a resolution of `8` equals `1/256` of a tile.
max_gap_size | :: int32? | Defines the maximum allowed distance between path waypoints. 0 means that paths must be contiguous (as they are for biters). Values greater than 0 will produce paths with "gaps" that are suitable for spiders. Allowed values are from `0` to `31`. Defaults to `0`.
Defines the maximum allowed distance between path waypoints. 0 means that paths must be contiguous (as they are for biters). Values greater than 0 will produce paths with "gaps" that are suitable for spiders. Allowed values are from `0` to `31`. Defaults to `0`.
max_attack_distance | :: double? | Defines the maximum allowed distance between the last traversable path waypoint and an obstacle entity to be destroyed. Only used when finding a discontiguous path, i.e. when `max_gap_size` > 0. This field filters out paths that are blocked by obstacles that are outside the entity's attack range. Allowed values are `0` or greater. Defaults to `max_gap_size`.
Defines the maximum allowed distance between the last traversable path waypoint and an obstacle entity to be destroyed. Only used when finding a discontiguous path, i.e. when `max_gap_size` > 0. This field filters out paths that are blocked by obstacles that are outside the entity's attack range. Allowed values are `0` or greater. Defaults to `max_gap_size`.
entity_to_ignore | :: LuaEntity? | Makes the pathfinder ignore collisions with this entity if it is given.
Makes the pathfinder ignore collisions with this entity if it is given.

#### Return values

→ uint32 | A unique handle to identify this call when on_script_path_request_finished fires.

#### Raised events

on_script_path_request_finished future_tick |

### get_script_areas(name?) → array[ScriptArea]

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

#### Parameters

name | :: string? |

### get_script_area(key?) → ScriptArea?

Gets the first script area by name or id.

#### Parameters

key | :: string or uint32? | The name or id of the area to get.
The name or id of the area to get.

### edit_script_area(id, area)

Sets the given script area to the new values.

#### Parameters

id | :: uint32 | The area to edit.
The area to edit.
area | :: ScriptArea |

### add_script_area(area) → uint32

Adds the given script area.

#### Parameters

area | :: ScriptArea |

#### Return values

→ uint32 | The id of the created area.

### remove_script_area(id) → boolean

Removes the given script area.

#### Parameters

id | :: uint32 |

#### Return values

→ boolean | If the area was actually removed. False when it didn't exist.

### get_script_positions(name?) → array[ScriptPosition]

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

#### Parameters

name | :: string? |

### get_script_position(key?) → ScriptPosition?

Gets the first script position by name or id.

#### Parameters

key | :: string or uint32? | The name or id of the position to get.
The name or id of the position to get.

### edit_script_position(id, position)

Sets the given script position to the new values.

#### Parameters

id | :: uint32 | The position to edit.
The position to edit.
position | :: ScriptPosition |

### add_script_position(position) → uint32

Adds the given script position.

#### Parameters

position | :: ScriptPosition |

#### Return values

→ uint32 | The id of the created position.

### remove_script_position(id) → boolean

Removes the given script position.

#### Parameters

id | :: uint32 |

#### Return values

→ boolean | If the position was actually removed. False when it didn't exist.

### 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 | :: MapPosition |
entities | :: array[LuaEntity] | The Entities to check.
The Entities to check.

### get_total_pollution() → double

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

### entity_prototype_collides(prototype, position, use_map_generation_bounding_box, direction?) → boolean

Whether the given entity prototype collides at the given position and direction.

#### Parameters

prototype | :: EntityID | The entity prototype to check.
The entity prototype to check.
position | :: MapPosition | The position to check.
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.
If the map generation bounding box should be used instead of the collision bounding box.
direction | :: defines.direction? |

### decorative_prototype_collides(prototype, position) → boolean

Whether the given decorative prototype collides at the given position and direction.

#### Parameters

prototype | :: DecorativeID | The decorative prototype to check.
The decorative prototype to check.
position | :: MapPosition | The position to check.
The position to check.

### calculate_tile_properties(property_names, positions) → dictionary[string → array[double]]

Calculate values for a list of tile properties at a list of positions. Requests for unrecognized properties will be ignored, so this can also be used to test whether those properties exist.

#### Parameters

property_names | :: array[string] | Names of properties (`"elevation"`, etc) to calculate.
Names of properties (`"elevation"`, etc) to calculate.
positions | :: array[MapPosition] | Positions for which to calculate property values.
Positions for which to calculate property values.

#### Return values

→ dictionary[string → array[double]] | Table of property value lists, keyed by property name.

### get_entities_with_force(chunk_position, force) → array[LuaEntity]

Returns all the military targets (entities with force) on this chunk for the given force.

#### Parameters

chunk_position | :: ChunkPosition | The chunk's position.
The chunk's position.
force | :: ForceID | Entities of this force will be returned.
Entities of this force will be returned.

### create_entities_from_blueprint_string{string=…, position=…, force?=…, direction?=…, flip_horizontal?=…, flip_vertical?=…, by_player?=…} → int32?

This method only works when used in simulations.

Places entities via the given blueprint string. These entities are force-built.

#### Parameters

Table with the following fields:

string | :: string | The blueprint string to import.
The blueprint string to import.
position | :: MapPosition | The position to place the blueprint at.
The position to place the blueprint at.
force | :: ForceID? | The force to place the blueprint for. Defaults to the player force.
The force to place the blueprint for. Defaults to the player force.
direction | :: defines.direction? | The direction to place the blueprint in. Defaults to north.
The direction to place the blueprint in. Defaults to north.
flip_horizontal | :: boolean? | Whether to flip the blueprint horizontally. Defaults to `false`.
Whether to flip the blueprint horizontally. Defaults to `false`.
flip_vertical | :: boolean? | Whether to flip the blueprint vertically. Defaults to `false`.
Whether to flip the blueprint vertically. Defaults to `false`.
by_player | :: PlayerIdentification? | The player that placed the blueprint. Defaults to `nil`.
The player that placed the blueprint. Defaults to `nil`.

#### Return values

→ int32? | If the blueprint string was invalid, `1` is returned. Otherwise, `nil` is returned.

### build_checkerboard(area)

Sets the given area to the checkerboard lab tiles.

#### Parameters

area | :: BoundingBox | The tile area.
The tile area.

### get_property(property) → double

Gets the value of surface property on this surface.

#### Parameters

property | :: SurfacePropertyID | Property to read.
Property to read.

#### Return values

→ double | Value of the property.

### set_property(property, value)

Sets the value of surface property on this surface.

#### Parameters

property | :: SurfacePropertyID | Property to change.
Property to change.
value | :: double | The wanted value of the property.
The wanted value of the property.

### create_global_electric_network()

Creates a global electric network for this surface, if one doesn't exist already.

### destroy_global_electric_network()

Destroys the global electric network for this surface, if it exists.

### execute_lightning{name=…, position=…}

Creates lightning. If other entities which can be lightning targets are nearby, the final position will be adjusted.

#### Parameters

Table with the following fields:

name | :: EntityID |
position | :: MapPosition |

### clear_hidden_tiles()

Completely removes hidden and double hidden tiles data on this surface.

### get_default_cover_tile(force, tile) → LuaTilePrototype?

Gets the cover tile for the given force and tile on this surface if one is set.

#### Parameters

force | :: ForceID |
tile | :: TileID |

### set_default_cover_tile(force, from_tile, to_tile)

Sets the cover tile for the given force and tile on this surface.

#### Parameters

force | :: ForceID |
from_tile | :: TileID |
to_tile | :: TileID or nil |

## Attributes

### name :: Read|Write string

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

The default surface can't be renamed.

#### Raised events

on_surface_renamed instantly |

### index :: Read uint32

This surface's index in LuaGameScript::surfaces (unique ID). It is assigned when a surface is created, and remains so until it is deleted. Indexes of deleted surfaces can be reused.

### map_gen_settings :: Read|Write MapGenSettings

The generation settings for this surface. These can be modified after surface generation, but note that this will not retroactively update the surface. To manually regenerate it, LuaSurface::regenerate_entity, LuaSurface::regenerate_decorative, and LuaSurface::delete_chunk can be used.

### generate_with_lab_tiles :: Read|Write boolean

When set to true, new chunks will be generated with lab tiles, instead of using the surface's map generation settings.

### always_day :: Read|Write boolean

When set to true, the sun will always shine.

### daytime :: Read|Write double

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

### darkness :: Read float

Amount of darkness at the current time, as a number in range `[0, 1]`.

### wind_speed :: Read|Write double

Current wind speed in tiles per tick.

### wind_orientation :: Read|Write RealOrientation

Current wind direction.

### wind_orientation_change :: Read|Write double

Change in wind orientation per tick.

### peaceful_mode :: Read|Write boolean

Is peaceful mode enabled on this surface?

### no_enemies_mode :: Read|Write boolean

Is no-enemies mode enabled on this surface?

### freeze_daytime :: Read|Write boolean

True if daytime is currently frozen.

### ticks_per_day :: Read|Write uint32

The number of ticks per day for this surface.

### dusk :: Read|Write double

The daytime when dusk starts.

### dawn :: Read|Write double

The daytime when dawn starts.

### evening :: Read|Write double

The daytime when evening starts.

### morning :: Read|Write double

The daytime when morning starts.

### daytime_parameters :: Read|Write table

Parameters of daytime. Equivalent as reading dusk, evening, morning and dawn at the same time.

In order for a write to take place, a new table needs to be written in one go: changing individual members of the returned table has no effect as those are value copies.

#### Table fields

dusk | :: double | Must be < evening.
Must be < evening.
evening | :: double | Must be > dusk and < morning.
Must be > dusk and < morning.
morning | :: double | Must be > evening and < dawn.
Must be > evening and < dawn.
dawn | :: double | Must be > morning.
Must be > morning.

### solar_power_multiplier :: Read|Write double

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

### min_brightness :: Read|Write double

The minimal brightness during the night. Defaults to `0.15`. This has an effect on both rendering and game mechanics such as biter spawns and solar power.

### brightness_visual_weights :: Read|Write ColorModifier

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, LuaSurface::min_brightness is set to default value 0.15.
    game.surfaces[1].brightness_visual_weights = { 1 / 0.85, 1 / 0.85, 1 / 0.85 }

### show_clouds :: Read|Write boolean

If clouds are shown on this surface. If false, clouds are never shown. If true the player must also have clouds enabled in graphics settings for them to be shown.

By default, clouds are shown on all surfaces.

### has_global_electric_network :: Read boolean

Whether this surface currently has a global electric network.

### platform :: Read LuaSpacePlatform?

### planet :: Read LuaPlanet?

The planet associated with this surface, if there is one.

Use LuaPlanet::associate_surface to create a new association with a planet.

### deletable :: Read boolean

If this surface can be deleted.

### global_effect :: Read|Write ModuleEffects?

Surface-wide effects applied to entities with effect receivers. `nil` if this surface is not using surface-wide effect source.

### pollutant_type :: Read LuaAirbornePollutantPrototype?

The type of pollutant enabled on the surface, or `nil` if no pollutant is enabled.

### localised_name :: Read|Write LocalisedString?

Localised name of this surface. When set, will replace the internal surface name in places where a player sees surface name.

Value may be ignored if a surface has a SpacePlatform or Planet object attached to it, which take the precedence.

### ignore_surface_conditions :: Read|Write boolean

If surface condition checks should not be performed on this surface.

### pollution_statistics :: Read LuaFlowStatistics

The pollution statistics for this surface.

### global_electric_network_statistics :: Read LuaFlowStatistics?

The global electric network statistics for this surface.

### valid :: Read boolean

Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be `false`. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.

### object_name :: Read string

The class name of this object. Available even when `valid` is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.

Class used in

- LuaCommandable::surface
- LuaControl::surface
- LuaCustomChartTag::surface
- LuaEntity::clone()
- LuaGameScript::create_surface()
- LuaGameScript::get_surface()
- LuaGameScript::surfaces
- LuaPlanet::create_surface()
- LuaPlanet::surface
- LuaPlayer::physical_surface
- LuaRenderObject::surface
- LuaSegmentedUnit::clone()
- LuaSegmentedUnit::surface
- LuaSpacePlatform::surface
- LuaTerritory::surface
- LuaTile::surface
- ItemLocationData
- RegistrationTarget
- SurfaceIdentification
- on_area_cloned
- on_brush_cloned
- on_chart_tag_modified
- on_chunk_generated
- on_player_alt_reverse_selected_area
- on_player_alt_selected_area
- on_player_deconstructed_area
- on_player_reverse_selected_area
- on_player_selected_area
- on_player_setup_blueprint