LuaSurface - API Docs

Factorio API Docs

1.1.52 <>

API Docs / Version 1.1.52 / Class LuaSurface

Class `LuaSurface`

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

Class LuaSurface

default

sorted

get_pollution(position) → double: Get 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.
can_fast_replace{name, position, direction, force} → boolean: If there exists an entity at the given location that can be fast-replaced with the given entity parameters.
find_entity(entity, position) → LuaEntity: Find a specific entity at a specific position.
find_entities(area) → array[LuaEntity]: Find entities in a given area.
find_entities_filtered{area, position, radius, name, type, ghost_name, ghost_type, direction, collision_mask, force, to_be_deconstructed, to_be_upgraded, limit, invert} → array[LuaEntity]: Find all entities of the given type or name in the given area.
find_tiles_filtered{area, position, radius, name, limit, has_hidden_tile, collision_mask} → array[LuaTile]: Find all tiles of the given name in the given area.
count_entities_filtered{area, position, radius, name, type, ghost_name, ghost_type, direction, collision_mask, force, to_be_deconstructed, to_be_upgraded, limit, invert} → uint: Count entities of given type or name in a given area.
count_tiles_filtered{area, position, radius, name, limit, has_hidden_tile, collision_mask} → uint: Count tiles of a given name in a given area.
find_non_colliding_position(name, center, radius, precision, force_to_tile_center) → Position: Find a non-colliding position within a given radius.
find_non_colliding_position_in_box(name, search_space, precision, force_to_tile_center) → Position: Find a non-colliding position within a given rectangle.
spill_item_stack(position, items, enable_looted, force, allow_belts) → array[LuaEntity]: Spill items 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_units{area, force, condition} → array[LuaEntity]: Find units (entities with type "unit") of a given force and force condition within a given area.
find_nearest_enemy{position, max_distance, force} → LuaEntity: Find the enemy 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.
set_multi_command{command, unit_count, force, unit_search_distance} → uint: Give a command to multiple units.
create_entity{name, position, direction, force, target, source, fast_replace, player, spill, raise_built, create_build_effect_smoke, spawn_decorations, move_stuck_players, item} → LuaEntity: Create an entity on this surface.
create_trivial_smoke{name, position}
create_particle{name, position, movement, height, vertical_speed, frame_speed}: Creates a particle at the given location
create_unit_group{position, force} → LuaUnitGroup: Create a new unit group at a given position.
build_enemy_base(position, unit_count, force): Send a group to build a new base.
get_tile(x, y) → LuaTile: Get the tile at a given position.
set_tiles(tiles, correct_tiles, remove_colliding_entities, remove_colliding_decoratives, raise_event): Set tiles at specified locations.
pollute(source, amount): Spawn pollution at the given position.
get_chunks() → LuaChunkIterator: Get an iterator going over every chunk on this surface.
is_chunk_generated(position) → boolean: Is a given chunk generated?
request_to_generate_chunks(position, radius): Request that the game's map generator generate chunks at the given position for the given radius on this surface.
force_generate_chunk_requests(): Blocks and generates all chunks that have been requested using all available threads.
set_chunk_generated_status(position, status): Set generated status of a chunk.
find_logistic_network_by_position(position, force) → LuaLogisticNetwork: Find the logistic network that covers a given position.
find_logistic_networks_by_construction_area(position, force) → array[LuaLogisticNetwork]: Finds all of the logistics networks whose construction area intersects with the given position.
deconstruct_area{area, force, player, skip_fog_of_war, item}: Place a deconstruction request.
cancel_deconstruct_area{area, force, player, skip_fog_of_war, item}: Cancel a deconstruction order.
upgrade_area{area, force, player, skip_fog_of_war, item}: Place an upgrade request.
cancel_upgrade_area{area, force, player, skip_fog_of_war, item}: Cancel a upgrade order.
get_hidden_tile(position) → string: The hidden tile name or nil if there isn't one for the given position.
set_hidden_tile(position, tile): Set the hidden tile for the specified position.
get_connected_tiles(position, tiles) → array[Position]: Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position.
delete_chunk(position)
regenerate_entity(entities, chunks): Regenerate autoplacement of some entities on this surface.
regenerate_decorative(decoratives, chunks): Regenerate autoplacement of some decoratives on this surface.
print(message, color): Print text to the chat console of all players on this surface.
destroy_decoratives{area, position, name, limit, invert}: Removes all decoratives from the given area.
create_decoratives{check_collision, decoratives}: Adds the given decoratives to the surface.
find_decoratives_filtered{area, position, name, limit, invert} → array[DecorativeResult]: Find decoratives of a given name in a given area.
get_trains(force) → array[LuaTrain]
clear_pollution(): Clears all pollution on this surface.
play_sound{path, position, volume_modifier, override_sound_type}: Play a sound for every player on this surface.
get_resource_counts() → dictionary[string → uint]: 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.
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.
clone_entities{entities, destination_offset, destination_surface, destination_force, snap_to_grid, create_build_effect_smoke}: Clones the given entities.
clear(ignore_characters): Clears this surface deleting all entities and chunks on it.
request_path{bounding_box, collision_mask, start, goal, force, radius, pathfind_flags, can_open_gates, path_resolution_modifier, entity_to_ignore} → uint: 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.
get_script_area(key) → ScriptArea: Gets the first script area by name or id.
edit_script_area(id, area): Sets the given script area to the new values.
add_script_area(area) → uint: Adds the given script area.
remove_script_area(id) → boolean: 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.
get_script_position(key) → ScriptPosition: Gets the first script position by name or id.
edit_script_position(id, area): Sets the given script position to the new values.
add_script_position(area) → uint: Adds the given script position.
remove_script_position(id) → boolean: Removes the given script position.
get_map_exchange_string() → string: Gets the map exchange string for the current map generation settings of this surface.
get_starting_area_radius() → double: Gets the starting area radius of this surface.
get_closest(position, entities) → LuaEntity: Gets the closest entity in the list to this position.
get_train_stops{name, force} → array[LuaEntity]: Gets train stops matching the given filters.
get_total_pollution() → double: Gets the total amount of pollution on the surface by iterating over all of the chunks containing pollution.
entity_prototype_collides(prototype, position, use_map_generation_bounding_box, direction)
decorative_prototype_collides(prototype, position)
calculate_tile_properties(property_names, positions) → dictionary[string → array[double]]
get_entities_with_force(position, force) → array[LuaEntity]: Returns all the military targets (entities with force) on this chunk for the given force.
build_checkerboard(area): Sets the given area to the checkerboard lab tiles.
help() → string: All methods and properties that this object supports.
name :: string [RW]: The name of this surface.
index :: uint [R]: Unique ID associated with this surface.
map_gen_settings :: MapGenSettings [RW]: The generation settings for this surface.
generate_with_lab_tiles :: boolean [RW]: When set to true, new chunks will be generated with lab tiles, instead of using the surface's map generation settings.
always_day :: boolean [RW]: When set to true, the sun will always shine.
daytime :: double [RW]: Current time of day, as a number in range [0, 1).
darkness :: float [R]: Amount of darkness at the current time.
wind_speed :: double [RW]: Current wind speed.
wind_orientation :: RealOrientation [RW]: Current wind direction.
wind_orientation_change :: double [RW]: Change in wind orientation per tick.
peaceful_mode :: boolean [RW]: Is peaceful mode enabled on this surface?
freeze_daytime :: boolean [RW]: True if daytime is currently frozen.
ticks_per_day :: uint [RW]: The number of ticks per day for this surface.
dusk :: double [RW]: The daytime when dusk starts.
dawn :: double [RW]: The daytime when dawn starts.
evening :: double [RW]: The daytime when evening starts.
morning :: double [RW]: The daytime when morning starts.
solar_power_multiplier :: double [RW]: The multiplier of solar power on this surface.
min_brightness :: double [RW]: The minimal brightness during the night.
brightness_visual_weights :: ColorModifier [RW]: Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT).
show_clouds :: boolean [RW]: If clouds are shown on this surface.
valid :: boolean [R]: Is this object valid?
object_name :: string [R]: The class name of this object.

add_script_area(area) → uint: Adds the given script area.
add_script_position(area) → uint: Adds the given script position.
always_day :: boolean [RW]: When set to true, the sun will always shine.
brightness_visual_weights :: ColorModifier [RW]: Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT).
build_checkerboard(area): Sets the given area to the checkerboard lab tiles.
build_enemy_base(position, unit_count, force): Send a group to build a new base.
calculate_tile_properties(property_names, positions) → dictionary[string → array[double]]
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.
can_place_entity{name, position, direction, force, build_check_type, forced, inner_name} → boolean: Check for collisions with terrain or other entities.
cancel_deconstruct_area{area, force, player, skip_fog_of_war, item}: Cancel a deconstruction order.
cancel_upgrade_area{area, force, player, skip_fog_of_war, item}: Cancel a upgrade order.
clear(ignore_characters): Clears this surface deleting all entities and chunks on it.
clear_pollution(): Clears all pollution 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.
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.
clone_entities{entities, destination_offset, destination_surface, destination_force, snap_to_grid, create_build_effect_smoke}: Clones the given entities.
count_entities_filtered{area, position, radius, name, type, ghost_name, ghost_type, direction, collision_mask, force, to_be_deconstructed, to_be_upgraded, limit, invert} → uint: Count entities of given type or name in a given area.
count_tiles_filtered{area, position, radius, name, limit, has_hidden_tile, collision_mask} → uint: Count tiles of a given name in a given area.
create_decoratives{check_collision, decoratives}: Adds the given decoratives to the surface.
create_entity{name, position, direction, force, target, source, fast_replace, player, spill, raise_built, create_build_effect_smoke, spawn_decorations, move_stuck_players, item} → LuaEntity: Create an entity on this surface.
create_particle{name, position, movement, height, vertical_speed, frame_speed}: Creates a particle at the given location
create_trivial_smoke{name, position}
create_unit_group{position, force} → LuaUnitGroup: Create a new unit group at a given position.
darkness :: float [R]: Amount of darkness at the current time.
dawn :: double [RW]: The daytime when dawn starts.
daytime :: double [RW]: Current time of day, as a number in range [0, 1).
deconstruct_area{area, force, player, skip_fog_of_war, item}: Place a deconstruction request.
decorative_prototype_collides(prototype, position)
delete_chunk(position)
destroy_decoratives{area, position, name, limit, invert}: Removes all decoratives from the given area.
dusk :: double [RW]: The daytime when dusk starts.
edit_script_area(id, area): Sets the given script area to the new values.
edit_script_position(id, area): Sets the given script position to the new values.
entity_prototype_collides(prototype, position, use_map_generation_bounding_box, direction)
evening :: double [RW]: The daytime when evening starts.
find_decoratives_filtered{area, position, name, limit, invert} → array[DecorativeResult]: Find decoratives of a given name in a given area.
find_enemy_units(center, radius, force) → array[LuaEntity]: Find enemy units (entities with type "unit") of a given force within an area.
find_entities(area) → array[LuaEntity]: Find entities in a given area.
find_entities_filtered{area, position, radius, name, type, ghost_name, ghost_type, direction, collision_mask, force, to_be_deconstructed, to_be_upgraded, limit, invert} → array[LuaEntity]: Find all entities of the given type or name in the given area.
find_entity(entity, position) → LuaEntity: Find a specific entity at a specific position.
find_logistic_network_by_position(position, force) → LuaLogisticNetwork: Find the logistic network that covers a given position.
find_logistic_networks_by_construction_area(position, force) → array[LuaLogisticNetwork]: Finds all of the logistics networks whose construction area intersects with the given position.
find_nearest_enemy{position, max_distance, force} → LuaEntity: 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_non_colliding_position(name, center, radius, precision, force_to_tile_center) → Position: Find a non-colliding position within a given radius.
find_non_colliding_position_in_box(name, search_space, precision, force_to_tile_center) → Position: Find a non-colliding position within a given rectangle.
find_tiles_filtered{area, position, radius, name, limit, has_hidden_tile, collision_mask} → array[LuaTile]: Find all tiles of the given name in the given 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.
force_generate_chunk_requests(): Blocks and generates all chunks that have been requested using all available threads.
freeze_daytime :: boolean [RW]: True if daytime is currently frozen.
generate_with_lab_tiles :: boolean [RW]: When set to true, new chunks will be generated with lab tiles, instead of using the surface's map generation settings.
get_chunks() → LuaChunkIterator: Get an iterator going over every chunk on this surface.
get_closest(position, entities) → LuaEntity: Gets the closest entity in the list to this position.
get_connected_tiles(position, tiles) → array[Position]: Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position.
get_entities_with_force(position, force) → array[LuaEntity]: Returns all the military targets (entities with force) on this chunk for the given force.
get_hidden_tile(position) → string: The hidden tile name or nil if there isn't one for the given position.
get_map_exchange_string() → string: Gets the map exchange string for the current map generation settings of this surface.
get_pollution(position) → double: Get the pollution for a given position.
get_random_chunk() → ChunkPosition: Gets a random generated chunk position or 0,0 if no chunks have been generated on this surface.
get_resource_counts() → dictionary[string → uint]: Gets the resource amount of all resources on this surface
get_script_area(key) → ScriptArea: Gets the first script area by name or id.
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.
get_script_position(key) → ScriptPosition: Gets the first script position by name or id.
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.
get_starting_area_radius() → double: Gets the starting area radius of this surface.
get_tile(x, y) → LuaTile: Get the tile at a given position.
get_total_pollution() → double: Gets the total amount of pollution on the surface by iterating over all of the chunks containing pollution.
get_train_stops{name, force} → array[LuaEntity]: Gets train stops matching the given filters.
get_trains(force) → array[LuaTrain]
help() → string: All methods and properties that this object supports.
index :: uint [R]: Unique ID associated with this surface.
is_chunk_generated(position) → boolean: Is a given chunk generated?
map_gen_settings :: MapGenSettings [RW]: The generation settings for this surface.
min_brightness :: double [RW]: The minimal brightness during the night.
morning :: double [RW]: The daytime when morning starts.
name :: string [RW]: The name of this surface.
object_name :: string [R]: The class name of this object.
peaceful_mode :: boolean [RW]: Is peaceful mode enabled on this surface?
play_sound{path, position, volume_modifier, override_sound_type}: Play a sound for every player on this surface.
pollute(source, amount): Spawn pollution at the given position.
print(message, color): Print text to the chat console of all players on this surface.
regenerate_decorative(decoratives, chunks): Regenerate autoplacement of some decoratives on this surface.
regenerate_entity(entities, chunks): Regenerate autoplacement of some entities on this surface.
remove_script_area(id) → boolean: Removes the given script area.
remove_script_position(id) → boolean: Removes the given script position.
request_path{bounding_box, collision_mask, start, goal, force, radius, pathfind_flags, can_open_gates, path_resolution_modifier, entity_to_ignore} → uint: Generates a path with the specified constraints (as an array of PathfinderWaypoints) using the unit pathfinding algorithm.
request_to_generate_chunks(position, radius): Request that the game's map generator generate chunks at the given position for the given radius on this surface.
set_chunk_generated_status(position, status): Set generated status of a chunk.
set_hidden_tile(position, tile): Set the hidden tile for the specified position.
set_multi_command{command, unit_count, force, unit_search_distance} → uint: Give a command to multiple units.
set_tiles(tiles, correct_tiles, remove_colliding_entities, remove_colliding_decoratives, raise_event): Set tiles at specified locations.
show_clouds :: boolean [RW]: If clouds are shown on this surface.
solar_power_multiplier :: double [RW]: The multiplier of solar power on this surface.
spill_item_stack(position, items, enable_looted, force, allow_belts) → array[LuaEntity]: Spill items on the ground centered at a given location.
ticks_per_day :: uint [RW]: The number of ticks per day for this surface.
upgrade_area{area, force, player, skip_fog_of_war, item}: Place an upgrade request.
valid :: boolean [R]: Is this object valid?
wind_orientation :: RealOrientation [RW]: Current wind direction.
wind_orientation_change :: double [RW]: Change in wind orientation per tick.
wind_speed :: double [RW]: Current wind speed.

Methods

`get_pollution (position) → double`

Get the pollution for a given position.

Parameters

position :: Position

Example

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

Note

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

`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 :: string: Name of the entity prototype to check.
position :: Position: Where the entity would be placed.
direction :: defines.direction Optional: Direction of the placed entity.
force :: ForceIdentification Optional: The force that would place the entity. If not specified, the enemy force is assumed.
build_check_type :: defines.build_check_type Optional: Which type of check should be carried out.
forced :: boolean Optional: 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.
inner_name :: string Optional: 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 :: string: Name of the entity to check
position :: Position: Where the entity would be placed
direction :: defines.direction Optional: Direction the entity would be placed
force :: ForceIdentification Optional: The force that would place the entity. If not specified, the enemy force is assumed.

`find_entity (entity, position) → LuaEntity`

Find a specific entity at a specific position.

Parameters

entity :: string: Entity to look for
position :: Position: Coordinates to look at

Return value

Will be nil if no such entity is found.

Example

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

`find_entities (area) → array[LuaEntity]`

Find entities in a given area.

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

Parameters

area :: BoundingBox Optional

Example

Will evaluate to a list of all entities within given area.

game.surfaces["nauvis"].find_entities({{-10, -10}, {10, 10}})

`find_entities_filtered {area, position, radius, name, type, ghost_name, ghost_type, direction, collision_mask, force, to_be_deconstructed, to_be_upgraded, limit, invert} → 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. If area is specified, this returns the entities colliding with that area.

Parameters

Table with the following fields:

area :: BoundingBox Optional
position :: Position Optional: Has precedence over area field.
radius :: double Optional: If given with position, will return all entities within the radius of the position.
name :: string or array[string] Optional
type :: string or array[string] Optional
ghost_name :: string or array[string] Optional
ghost_type :: string or array[string] Optional
direction :: defines.direction or array[defines.direction] Optional
collision_mask :: CollisionMaskLayer or array[CollisionMaskLayer] Optional
force :: ForceIdentification or array[ForceIdentification] Optional
to_be_deconstructed :: boolean Optional
to_be_upgraded :: boolean Optional
limit :: uint Optional
invert :: boolean Optional: If the filters should be inverted. These filters are: name, type, ghost_name, ghost_type, direction, collision_mask, force.

Example

game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, type = "resource"} -- gets all resources in the rectangle
game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, name = "iron-ore"} -- gets all iron ores in the rectangle
game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, name = {"iron-ore", "copper-ore"}} -- gets all iron ore and copper ore in the rectangle
game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, force = "player"}  -- gets player owned entities in the rectangle
game.surfaces[1].find_entities_filtered{area = {{-10, -10}, {10, 10}}, limit = 5}  -- gets the first 5 entities in the rectangle
game.surfaces[1].find_entities_filtered{position = {0, 0}, radius = 10}  -- gets all entities within 10 tiles of the position [0,0].

`find_tiles_filtered {area, position, radius, name, limit, has_hidden_tile, collision_mask} → array[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

Table with the following fields:

area :: BoundingBox Optional
position :: Position Optional: Ignored if not given with radius.
radius :: double Optional: If given with position, will return all entities within the radius of the position.
name :: string or array[string] Optional
limit :: uint Optional
has_hidden_tile :: boolean Optional
collision_mask :: CollisionMaskLayer or array[CollisionMaskLayer] Optional

`count_entities_filtered {area, position, radius, name, type, ghost_name, ghost_type, direction, collision_mask, force, to_be_deconstructed, to_be_upgraded, limit, invert} → uint`

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

If no area 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

Table with the following fields:

area :: BoundingBox Optional
position :: Position Optional
radius :: double Optional: If given with position, will count all entities within the radius of the position.
name :: string or array[string] Optional
type :: string or array[string] Optional
ghost_name :: string or array[string] Optional
ghost_type :: string or array[string] Optional
direction :: defines.direction or array[defines.direction] Optional
collision_mask :: CollisionMaskLayer or array[CollisionMaskLayer] Optional
force :: ForceIdentification or array[ForceIdentification] Optional
to_be_deconstructed :: boolean Optional
to_be_upgraded :: boolean Optional
limit :: uint Optional
invert :: boolean Optional: If the filters should be inverted. These filters are: name, type, ghost_name, ghost_type, direction, collision_mask, force.

`count_tiles_filtered {area, position, radius, name, limit, has_hidden_tile, collision_mask} → uint`

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

If no area 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

Table with the following fields:

area :: BoundingBox Optional
position :: Position Optional: Ignored if not given with radius.
radius :: double Optional: If given with position, will return all entities within the radius of the position.
name :: string or array[string] Optional
limit :: uint Optional
has_hidden_tile :: boolean Optional
collision_mask :: CollisionMaskLayer or array[CollisionMaskLayer] Optional

`find_non_colliding_position (name, center, radius, precision, force_to_tile_center) → Position`

Find a non-colliding position within a given radius.

Parameters

name :: string: Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.)
center :: Position: Center of the search area.
radius :: double: Max distance from center to search in. 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.
force_to_tile_center :: boolean Optional: Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Default false.

Return value

The non-colliding position. May be nil if no suitable position was found.

Note

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.

`find_non_colliding_position_in_box (name, search_space, precision, force_to_tile_center) → Position`

Find a non-colliding position within a given rectangle.

Parameters

name :: string: Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.)
search_space :: BoundingBox: The rectangle to search inside.
precision :: double: The step length from the given position as it searches, in tiles. Minimum value is 0.01.
force_to_tile_center :: boolean Optional: Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Default false.

Return value

The non-colliding position. May be nil if no suitable position was found.

`spill_item_stack (position, items, enable_looted, force, allow_belts) → array[LuaEntity]`

Spill items on the ground centered at a given location.

Parameters

position :: Position: Center of the spillage
items :: ItemStackIdentification: Items to spill
enable_looted :: boolean Optional: When true, each created item will be flagged with the LuaEntity::to_be_looted flag.
force :: LuaForce or string Optional: When provided (and not nil) the items will be marked for deconstruction by this force.
allow_belts :: boolean Optional: Whether items can be spilled onto belts. Defaults to true.

Return value

The created item-on-ground entities.

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

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

Parameters

center :: Position: Center of the search area
radius :: double: Radius of the circular search area
force :: LuaForce or string Optional: Force to find enemies of. If not given, uses the player force.

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)

Note

This is more efficient than LuaSurface::find_entities.

`find_units {area, force, condition} → array[LuaEntity]`

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

Parameters

Table with the following fields:

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

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

Note

This is more efficient than LuaSurface::find_entities.

`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 :: Position: Center of the search area.
max_distance :: double: Radius of the circular search area.
force :: ForceIdentification Optional: The force the result will be an enemy of. Uses the player force if not specified.

Return value

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 :: Position: Center of the search area.
max_distance :: double: Radius of the circular search area.
force :: ForceIdentification Optional: The force the result will be an enemy of. Uses the player force if not specified.

Return value

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} → uint`

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

Parameters

Table with the following fields:

command :: Command
unit_count :: uint: Number of units to give the command to.
force :: ForceIdentification Optional: Force of the units this command is to be given to. If not specified, uses the enemy force.
unit_search_distance :: uint Optional: Radius to search for units. The search area is centered on the destination of the command.

Return value

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

`create_entity {name, position, direction, force, target, source, fast_replace, player, spill, raise_built, create_build_effect_smoke, spawn_decorations, move_stuck_players, item} → LuaEntity`

Create an entity on this surface.

Parameters

Table with the following fields:

name :: string: The entity prototype name to create.
position :: Position: Where to create the entity.
direction :: defines.direction Optional: Desired orientation of the entity after creation.
force :: ForceIdentification Optional: Force of the entity, default is enemy.
target :: LuaEntity Optional: Entity with health for the new entity to target.
source :: LuaEntity Optional: Source entity. Used for beams and highlight-boxes.
fast_replace :: boolean Optional: If true, building will attempt to simulate fast-replace building.
player :: PlayerIdentification Optional: If given set the last_user to this player. If fast_replace is true simulate fast replace using this player.
spill :: boolean Optional: If false while fast_replace is true and player is nil any items from fast-replacing will be deleted instead of dropped on the ground.
raise_built :: boolean Optional: If true; defines.events.script_raised_built will be fired on successful entity creation.
create_build_effect_smoke :: boolean Optional: If false, the building effect smoke will not be shown around the new entity.
spawn_decorations :: boolean Optional: If true, entity types that have spawn_decorations property will apply triggers defined in the property.
move_stuck_players :: boolean Optional: If true, any characters that are in the way of the entity are teleported out of the way.
item :: LuaItemStack Optional: 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)

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

`assembling-machine`

recipe :: string Optional

`beam`

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

`container`

bar :: uint Optional: Inventory index where the red limiting bar should be set.

`cliff`

cliff_orientation :: CliffOrientation Optional: If not specified, direction will be used instead.

`flying-text`

text :: LocalisedString: The string to show.
color :: Color Optional: Color of the displayed text.
render_player_index :: uint Optional

`entity-ghost`

inner_name :: string: The prototype name of the entity contained in the ghost.
expires :: boolean Optional: If false the ghost entity will not expire. Default is false.

`fire`

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

`inserter`

conditions :: InserterCircuitConditions
filters :: array[InventoryFilter]

`item-entity`

stack :: SimpleItemStack: The stack of items to create.

`item-request-proxy`

target :: LuaEntity: The target items are to be delivered to.
modules :: dictionary[string → uint]: The stacks of items to be delivered to target entity from logistic network.

`rolling-stock`

orientation :: RealOrientation Optional: The orientation of this rolling stock.
color :: Color Optional: The color of this rolling stock, if it supports colors.

`locomotive`

snap_to_train_stop :: boolean Optional: Whether the locomotive should snap to an adjacent train stop. Defaults to true.

`logistic-container`

request_filters :: array[InventoryFilter] Optional

`particle`

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

`artillery-flare`

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

`projectile`

speed :: double
max_range :: double

`resource`

amount :: uint
enable_tree_removal :: boolean Optional: If colliding trees are removed normally for this resource entity based off the prototype tree removal values. Default is true.
enable_cliff_removal :: boolean Optional: If colliding cliffs are removed. Default is true.
snap_to_tile_center :: boolean Optional: 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.

`underground-belt`

type :: string Optional: "output" or "input"; default is "input".

`programmable-speaker`

parameters :: ProgrammableSpeakerParameters Optional
alert_parameters :: ProgrammableSpeakerAlertParameters Optional

`character-corpse`

inventory_size :: uint Optional
player_index :: uint Optional

`highlight-box`

bounding_box :: BoundingBox Optional: The bounding box defining the highlight box using absolute map coordinates. If specified, the position parameter is ignored, but needs to be present anyways. 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 Optional: Specifies the graphical appearance (color) of the highlight box. Defaults to "electricity".
render_player_index :: uint Optional: The player to render the highlight box for. If not provided, it will be rendered for all players.
blink_interval :: uint Optional: The blink interval for this highlight box. Makes it be shown every blink_interval ticks. Defaults to 0 (constantly shown).
time_to_live :: uint Optional: The amount of time in ticks that the highlight box will exist for. Defaults to existing forever.

`speech-bubble`

text :: LocalisedString
lifetime :: uint Optional

`simple-entity-with-owner`

render_player_index :: uint Optional

`simple-entity-with-force`

render_player_index :: uint Optional

Return value

The created entity or nil if the creation failed.

Examples

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 = "logistic-chest-requester", position = {game.player.position.x+3, game.player.position.y},
  force = game.player.force, request_filters = {{index = 1, name = "iron-plate", count = 128}}
}

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_trivial_smoke {name, position}`

Parameters

Table with the following fields:

name :: string: The smoke prototype name to create.
position :: Position: Where to create the smoke.

`create_particle {name, position, movement, height, vertical_speed, frame_speed}`

Creates a particle at the given location

Parameters

Table with the following fields:

name :: string: The particle name.
position :: Position: Where to create the particle.
movement :: Vector
height :: float
vertical_speed :: float
frame_speed :: float

`create_unit_group {position, force} → LuaUnitGroup`

Create a new unit group at a given position.

Parameters

Table with the following fields:

position :: Position: Initial position of the new unit group.
force :: ForceIdentification Optional: Force of the new unit group. Defaults to "enemy".

`build_enemy_base (position, unit_count, force)`

Send a group to build a new base.

Parameters

position :: Position: Location of the new base.
unit_count :: uint: Number of biters to send for the base-building task.
force :: ForceIdentification Optional: Force the new base will belong to. Defaults to enemy.

Note

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

`get_tile (x, y) → LuaTile`

Get the tile at a given position.

Parameters

x :: int
y :: int

Note

The input position params can also be a single tile position.

`set_tiles (tiles, correct_tiles, remove_colliding_entities, remove_colliding_decoratives, raise_event)`

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

Placing a mineable tile on top of a non-mineable one will turn the latter into the LuaTile::hidden_tile for that tile. Placing a mineable tile on a mineable one or a non-mineable tile on a non-mineable one will not modify the hidden tile. This restriction can however be circumvented by using LuaSurface::set_hidden_tile.

Parameters

tiles :: array[Tile]
correct_tiles :: boolean Optional: If false, the correction logic is not applied to the changed tiles. Defaults to true.
remove_colliding_entities :: boolean or string Optional: true, false, or abort_on_collision. Defaults to true.
remove_colliding_decoratives :: boolean Optional: true or false. Defaults to true.
raise_event :: boolean Optional: true or false. Defaults to false.

Note

It is recommended to call this method once for all the tiles you want to change rather than calling it individually for every tile. As the tile correction is used after every step, calling it one by one could cause the tile correction logic to redo some of the changes. Also, many small API calls are generally more performance intensive than one big one.

`pollute (source, amount)`

Spawn pollution at the given position.

Parameters

source :: Position: Where to spawn the pollution.
amount :: double: How much pollution to add.

`get_chunks () → LuaChunkIterator`

Get an iterator going over every chunk on this surface.

`is_chunk_generated (position) → boolean`

Is a given chunk generated?

Parameters

position :: ChunkPosition: The chunk's position.

`request_to_generate_chunks (position, radius)`

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

Parameters

position :: Position: Where to generate the new chunks.
radius :: uint: The chunk radius from position to generate new chunks in.

`force_generate_chunk_requests ()`

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

`set_chunk_generated_status (position, status)`

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

Parameters

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

`find_logistic_network_by_position (position, force) → LuaLogisticNetwork`

Find the logistic network that covers a given position.

Parameters

position :: Position
force :: ForceIdentification: Force the logistic network should belong to.

Return value

The found network or nil if no such network was found.

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

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

Parameters

position :: Position
force :: ForceIdentification: Force the logistic networks should belong to.

`deconstruct_area {area, force, player, skip_fog_of_war, item}`

Place a deconstruction request.

Parameters

Table with the following fields:

area :: BoundingBox: The area to mark for deconstruction.
force :: ForceIdentification: The force whose bots should perform the deconstruction.
player :: PlayerIdentification Optional: The player to set the last_user to if any.
skip_fog_of_war :: boolean Optional: If chunks covered by fog-of-war are skipped.
item :: LuaItemStack Optional: The deconstruction item to use if any.

`cancel_deconstruct_area {area, force, player, skip_fog_of_war, item}`

Cancel a deconstruction order.

Parameters

Table with the following fields:

area :: BoundingBox: The area to cancel deconstruction orders in.
force :: ForceIdentification: The force whose deconstruction orders to cancel.
player :: PlayerIdentification Optional: The player to set the last_user to if any.
skip_fog_of_war :: boolean Optional: If chunks covered by fog-of-war are skipped.
item :: LuaItemStack Optional: The deconstruction item to use if any.

`upgrade_area {area, force, player, skip_fog_of_war, item}`

Place an upgrade request.

Parameters

Table with the following fields:

area :: BoundingBox: The area to mark for upgrade.
force :: ForceIdentification: The force whose bots should perform the upgrade.
player :: PlayerIdentification Optional: The player to set the last_user to if any.
skip_fog_of_war :: boolean Optional: If chunks covered by fog-of-war are skipped.
item :: LuaItemStack: The upgrade item to use.

`cancel_upgrade_area {area, force, player, skip_fog_of_war, item}`

Cancel a upgrade order.

Parameters

Table with the following fields:

area :: BoundingBox: The area to cancel upgrade orders in.
force :: ForceIdentification: The force whose upgrade orders to cancel.
player :: PlayerIdentification Optional: The player to set the last_user to if any.
skip_fog_of_war :: boolean Optional: If chunks covered by fog-of-war are skipped.
item :: LuaItemStack Optional: The upgrade item to use if any.

`get_hidden_tile (position) → string`

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

Parameters

position :: TilePosition: The tile position.

`set_hidden_tile (position, tile)`

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

Parameters

position :: TilePosition: The tile position.
tile :: string or LuaTilePrototype: The new hidden tile or nil to clear the hidden tile.

`get_connected_tiles (position, tiles) → array[Position]`

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

Parameters

position :: Position: The tile position to start at.
tiles :: array[string]: The tiles to search for.

Return value

The resulting set of tiles.

Note

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

`delete_chunk (position)`

Parameters

position :: ChunkPosition: The chunk position to delete

Note

This won't delete the chunk immediately. Chunks are deleted at the end of the current tick.

`regenerate_entity (entities, chunks)`

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

Parameters

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

Note

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

`regenerate_decorative (decoratives, chunks)`

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

Parameters

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

Note

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

`print (message, color)`

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

Parameters

message :: LocalisedString
color :: Color Optional

Note

Messages that are identical to a message sent in the last 60 ticks are not printed again.

`destroy_decoratives {area, position, name, limit, invert}`

Removes all decoratives from the given area. If no area and no position are given, then the entire surface is searched.

Parameters

Table with the following fields:

area :: BoundingBox Optional
position :: TilePosition Optional
name :: string or array[string] or LuaDecorativePrototype or array[LuaDecorativePrototype] Optional
limit :: uint Optional
invert :: boolean Optional: If the filters should be inverted.

`create_decoratives {check_collision, decoratives}`

Adds the given decoratives to the surface.

Parameters

Table with the following fields:

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

Note

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

`find_decoratives_filtered {area, position, name, limit, invert} → array[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 Optional
position :: TilePosition Optional
name :: string or array[string] or LuaDecorativePrototype or array[LuaDecorativePrototype] Optional
limit :: uint Optional
invert :: boolean Optional: 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

`get_trains (force) → array[LuaTrain]`

Parameters

force :: ForceIdentification Optional: If given only trains matching this force are returned.

`clear_pollution ()`

Clears all pollution on this surface.

`play_sound {path, position, volume_modifier, override_sound_type}`

Play a sound for every player on this surface.

Parameters

Table with the following fields:

path :: SoundPath: The sound to play.
position :: Position Optional: Where the sound should be played. If not given, it's played at the current position of each player.
volume_modifier :: double Optional: The volume of the sound to play. Must be between 0 and 1 inclusive.
override_sound_type :: SoundType Optional: The volume mixer to play the sound through. Defaults to the default mixer for the given sound type.

`get_resource_counts () → dictionary[string → uint]`

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.

Parameters

Table with the following fields:

source_area :: BoundingBox
destination_area :: BoundingBox
destination_surface :: SurfaceIdentification Optional
destination_force :: LuaForce or string Optional
clone_tiles :: boolean Optional: If tiles should be cloned
clone_entities :: boolean Optional: If entities should be cloned
clone_decoratives :: boolean Optional: If decoratives should be cloned
clear_destination_entities :: boolean Optional: If the destination entities should be cleared
clear_destination_decoratives :: boolean Optional: If the destination decoratives should be cleared
expand_map :: boolean Optional: If the destination surface should be expanded when destination_area is outside current bounds. Default false.
create_build_effect_smoke :: boolean Optional: If true, the building effect smoke will be shown around the new entities.

Notes

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.

`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.

Parameters

Table with the following fields:

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

Notes

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.

`clone_entities {entities, destination_offset, destination_surface, destination_force, snap_to_grid, create_build_effect_smoke}`

Clones the given entities.

Parameters

Table with the following fields:

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

Notes

defines.events.on_entity_cloned is raised for each entity.

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

`clear (ignore_characters)`

Clears this surface deleting all entities and chunks on it.

Parameters

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

Note

This won't clear the surface immediately. It will be cleared at the end of the current tick.

`request_path {bounding_box, collision_mask, start, goal, force, radius, pathfind_flags, can_open_gates, path_resolution_modifier, entity_to_ignore} → uint`

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. If you want to command actual units to move, use the LuaEntity::set_command functionality 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.
collision_mask :: CollisionMask or array[string]: The list of masks the bounding_box collides with.
start :: Position: The position from which to start pathfinding.
goal :: Position: The position to find a path to.
force :: ForceIdentification: The force for which to generate the path, determining which gates can be opened for example.
radius :: double Optional: How close the pathfinder needs to get to its goal (in tiles). Defaults to 1.
pathfind_flags :: PathfinderFlags Optional: Flags that affect pathfinder behavior.
can_open_gates :: boolean Optional: Whether the path request can open gates. Defaults to false.
path_resolution_modifier :: int Optional: Defines how coarse the pathfinder's grid is. Smaller values mean a coarser grid (negative numbers allowed). Defaults to 0.
entity_to_ignore :: LuaEntity Optional: Makes the pathfinder ignore collisions with this entity if it is given.

Return value

A unique handle to identify this call when on_script_path_request_finished fires.

`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 Optional

`get_script_area (key) → ScriptArea`

Gets the first script area by name or id.

Parameters

key :: string or uint Optional: 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 :: uint: The area to edit.
area :: ScriptArea

`add_script_area (area) → uint`

Adds the given script area.

Parameters

area :: ScriptArea

Return value

The id of the created area.

`remove_script_area (id) → boolean`

Removes the given script area.

Parameters

id :: uint

Return value

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 Optional

`get_script_position (key) → ScriptPosition`

Gets the first script position by name or id.

Parameters

key :: string or uint Optional: The name or id of the position to get.

`edit_script_position (id, area)`

Sets the given script position to the new values.

Parameters

id :: uint: The position to edit.
area :: ScriptPosition

`add_script_position (area) → uint`

Adds the given script position.

Parameters

area :: ScriptPosition

Return value

The id of the created position.

`remove_script_position (id) → boolean`

Removes the given script position.

Parameters

id :: uint

Return value

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

`get_train_stops {name, force} → array[LuaEntity]`

Gets train stops matching the given filters.

Parameters

Table (optional) with the following fields:

name :: string or array[string] Optional
force :: ForceIdentification Optional

`get_total_pollution () → double`

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

`entity_prototype_collides (prototype, position, use_map_generation_bounding_box, direction)`

Parameters

prototype :: EntityPrototypeIdentification: The entity prototype to check
position :: Position: The position to check
use_map_generation_bounding_box :: boolean: If the map generation bounding box should be used instead of the collision bounding box
direction :: defines.direction Optional

`decorative_prototype_collides (prototype, position)`

Parameters

prototype :: string: The decorative prototype to check
position :: Position: The position to check

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

Parameters

property_names :: array[string]: Names of properties (e.g. "elevation") to calculate
positions :: array[Position]: Positions for which to calculate property values

Return value

Table of property value lists, keyed by property name

`get_entities_with_force (position, force) → array[LuaEntity]`

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

Parameters

position :: ChunkPosition: The chunk's position.
force :: LuaForce or string: Entities of this force will be returned.

`build_checkerboard (area)`

Sets the given area to the checkerboard lab tiles.

Parameters

area :: BoundingBox: The tile area.

`help () → string`

All methods and properties that this object supports.

Attributes

`name :: string` [Read/Write]

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

Note

the default surface can't be renamed.

`index :: uint` [Read]

Unique ID associated with this surface.

`map_gen_settings :: MapGenSettings` [Read/Write]

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

`generate_with_lab_tiles :: boolean` [Read/Write]

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

`always_day :: boolean` [Read/Write]

When set to true, the sun will always shine.

`daytime :: double` [Read/Write]

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

`darkness :: float` [Read]

Amount of darkness at the current time.

`wind_speed :: double` [Read/Write]

Current wind speed.

`wind_orientation :: RealOrientation` [Read/Write]

Current wind direction.

`wind_orientation_change :: double` [Read/Write]

Change in wind orientation per tick.

`peaceful_mode :: boolean` [Read/Write]

Is peaceful mode enabled on this surface?

`freeze_daytime :: boolean` [Read/Write]

True if daytime is currently frozen.

`ticks_per_day :: uint` [Read/Write]

The number of ticks per day for this surface.

`dusk :: double` [Read/Write]

The daytime when dusk starts.

`dawn :: double` [Read/Write]

The daytime when dawn starts.

`evening :: double` [Read/Write]

The daytime when evening starts.

`morning :: double` [Read/Write]

The daytime when morning starts.

`solar_power_multiplier :: double` [Read/Write]

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

Note

Solar equipment is still limited to its maximum power output.

`min_brightness :: double` [Read/Write]

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

`brightness_visual_weights :: ColorModifier` [Read/Write]

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

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

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

Example

Makes night on the surface pitch black, assuming LuaSurface::min_brightness being set to default value 0.15.

game.surfaces[1].brightness_visual_weights = { 1 / 0.85, 1 / 0.85, 1 / 0.85 }

`show_clouds :: boolean` [Read/Write]

If clouds are shown on this surface.

Note

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

`valid :: boolean` [Read]

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 :: string` [Read]

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.