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".
get_pollution(position) → double | Get the pollution for a given position. |
can_place_entity{name=…, position=…, direction=…, force=…, build_check_type=…, forced=…} → boolean | Check for collisions with terrain or other entities. |
can_fast_replace{name=…, position=…, direction=…, force=…} → boolean | If there exists an entity at the given location that can be fast-replaced with the given entity parameters. |
find_entity(entity, position) → LuaEntity | Find a specific entity at a specific position. |
find_entities(area) → array of LuaEntity | Find entities in a given area. |
find_entities_filtered{area=…, position=…, radius=…, name=…, type=…, ghost_name=…, ghost_type=…, direction=…, collision_mask=…, force=…, to_be_deconstructed=…, to_be_upgraded=…, limit=…, invert=…} → array of LuaEntity | Find entities of given type or name in a given area. |
find_tiles_filtered{area=…, position=…, radius=…, name=…, limit=…, has_hidden_tile=…, collision_mask=…} → array of LuaTile | Find tiles of a given name in a given area. |
count_entities_filtered{area=…, position=…, radius=…, name=…, type=…, ghost_name=…, ghost_type=…, direction=…, collision_mask=…, force=…, 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 of LuaEntity | Spill items on the ground centered at a given location. |
find_enemy_units(center, radius, force) → array of LuaEntity | Find enemy units (entities with type "unit") of a given force within an area. |
find_units{area=…, force=…, condition=…} → array of LuaEntity | Find units (entities with type "unit") of a given force and force condition within a given area. |
find_nearest_enemy{position=…, max_distance=…, force=…} → LuaEntity | Find the enemy entity-with-force (military entity) closest to the given position. |
set_multi_command{command=…, unit_count=…, force=…, unit_search_distance=…} → uint | Give a command to multiple units. |
create_entity{name=…, position=…, direction=…, force=…, target=…, source=…, fast_replace=…, player=…, spill=…, raise_built=…, create_build_effect_smoke=…, 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 of LuaLogisticNetwork | Finds all of the logistics networks whose construction area intersects with the given position. |
deconstruct_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} | Place a deconstruction request. |
cancel_deconstruct_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} | Cancel a deconstruction order. |
upgrade_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} | Place an upgrade request. |
cancel_upgrade_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} | Cancel a upgrade order. |
get_hidden_tile(position) → string | The hidden tile name or nil if there isn't one for the given position. |
set_hidden_tile(position, tile) | |
get_connected_tiles(position, tiles) → array of Position | Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position. |
delete_chunk(position) | |
regenerate_entity(entities, chunks) | Regenerate autoplacement of some entities on this surface. |
regenerate_decorative(decoratives, chunks) | Regenerate autoplacement of some decoratives on this surface. |
print(message, color) | Print text to the chat console of all players on this surface. |
destroy_decoratives{area=…, position=…, name=…, limit=…, invert=…} | Removes all decoratives from the given area. |
create_decoratives{check_collision=…, decoratives=…} | Adds the given decoratives to the surface. |
find_decoratives_filtered{area=…, position=…, name=…, limit=…, invert=…} → array of DecorativeResult | Find decoratives of a given name in a given area. |
get_trains(force) → array of LuaTrain | |
clear_pollution() | Clears all pollution on this surface. |
play_sound{path=…, position=…, volume_modifier=…, override_sound_type=…} → boolean | Plays a sound 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 | Starts a path find request without actually ordering a unit to move. |
get_script_areas(name) → array of ScriptArea | Gets the script areas that match the given name or if no name is given all areas are returned. |
get_script_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 of 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(opts) → array of LuaEntity | Gets train stops matching the given filters. |
get_total_pollution() → double | Gets the total amount of pollution on the surface by iterating over all of the chunks containing pollution. |
entity_prototype_collides(prototype, position, use_map_generation_bounding_box, direction) | |
decorative_prototype_collides(prototype, position) | |
calculate_tile_properties(property_names, positions) → dictionary string → array of double | |
get_entities_with_force(position, force) → array of LuaEntity | Returns all the entities with force on this chunk for the given force. |
build_checkerboard(area) | Sets the given area to the checkerboard lab tiles. |
name :: string [RW] | The name of this surface. |
index :: uint [R] | Unique ID associated with this surface. |
map_gen_settings :: MapGenSettings [RW] | The generation settings for the surface. |
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 :: float [RW] | Current time of day, as a number in range [0, 1). |
darkness :: float [R] | Amount of darkness at the current time. |
wind_speed :: float [RW] | Current wind speed. |
wind_orientation :: float [RW] | Current wind direction. |
wind_orientation_change :: float [RW] | Change in wind orientation per tick. |
peaceful_mode :: boolean [RW] | Is peaceful mode enabled on this surface? |
freeze_daytime :: boolean [RW] | True if daytime is currently frozen. |
ticks_per_day :: uint [RW] | The number of ticks per day for this surface. |
dusk :: double [RW] | The daytime when dusk starts. |
dawn :: double [RW] | The daytime when dawn starts. |
evening :: double [RW] | The daytime when evening starts. |
morning :: double [RW] | The daytime when morning starts. |
solar_power_multiplier :: double [RW] | The multiplier of solar power on this surface. |
min_brightness :: double [RW] | The minimal brightness during the night. |
brightness_visual_weights :: ColorModifier [RW] | Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT). |
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. |
help() → string | All methods, and properties that this object supports. |
Get the pollution for a given position.
game.surfaces[1].get_pollution({1,2})
Check for collisions with terrain or other entities.
If there exists an entity at the given location that can be fast-replaced with the given entity parameters.
Find entities in a given area.
If no area is given all entities on the surface are returned.
game.surfaces["nauvis"].find_entities({{-10, -10}, {10, 10}})
Find entities of given type or name in a given area.
If no filters (name
, type
, force
, etc.) are given, returns all entities in the search area.
If multiple filters are specified, returns only entities matching all given filters.
If no area or position are given, then the entire surface is searched. If position is given, returns entities colliding with that position (i.e the given position is within the entity's collision box). If position and radius are given, returns entities in that radius of the position. If area is specified, returns entities colliding with that area.
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 of a given name in a given area.
If no filters are given returns all tiles in the search area.
If no area or position and radius is given, then the entire surface is searched. If position and radius are given, only tiles within the radius of the position are included.
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, then the entire surface is searched. If position is given, returns entities colliding with that position (i.e the given position is within the entity's collision box). If position and radius are given, returns entities in that radius of the position. If area is specified, returns entities colliding with that area.
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, then the entire surface is searched. If position and radius are given, only tiles within the radius of the position are included.
Find a non-colliding position within a given radius.
nil
if no suitable position was found.Find a non-colliding position within a given rectangle.
nil
if no suitable position was found.Spill items on the ground centered at a given location.
Find enemy units (entities with type "unit") of a given force within an area.
local enemies = game.player.surface.find_enemy_units(game.player.position, 100)
Find units (entities with type "unit") of a given force and force condition within a given area.
local friendly_units = game.player.surface.find_units({area = {{-10, -10},{10, 10}}, force = "player", condition = "friend")
local units = game.player.surface.find_units({area = {{-10, -10},{10, 10}}, force = "player", condition = "same"})
Find the enemy entity-with-force (military entity) closest to the given position.
nil
if no enemy could be found within the
given area.Give a command to multiple units. This will automatically select suitable units for the task.
count
if not enough units were
available.Create an entity on this surface.
direction
will be used instead."output"
or "input"
; default is "input"
.nil
if the creation failed.asm = game.surfaces[1].create_entity{name = "assembling-machine-1", position = {15, 3}, force = game.forces.player, recipe = "iron-stick"}
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"}}
}
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
game.surfaces[1].create_entity{name = "inserter", position = game.player.position, direction = defines.direction.north}
Create a new unit group at a given position.
"enemy"
.Set tiles at specified locations. Automatically corrects the edges around modified tiles.
Get an iterator going over every chunk on this surface.
Blocks and generates all chunks that have been requested using all available threads.
Set generated status of a chunk. Useful when copying chunks.
Find the logistic network that covers a given position.
nil
if no such network was found.Finds all of the logistics networks whose construction area intersects with the given position.
Place a deconstruction request.
Cancel a deconstruction order.
Place an upgrade request.
Cancel a upgrade order.
Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position.
Regenerate autoplacement of some entities on this surface. This can be used to autoplace newly-added entities.
nil
all entities with an autoplace are used.Regenerate autoplacement of some decoratives on this surface. This can be used to autoplace newly-added decoratives.
nil
all decoratives with an autoplace are used.Print text to the chat console of all players on this surface.
Removes all decoratives from the given area.
If no area and no position are given, then the entire surface is searched.
Adds the given decoratives to the surface.
Each Decorative is
Find decoratives of a given name in a given area.
If no filters are given, returns all decoratives in the search area. If multiple filters are specified, returns only decoratives matching all given filters.
If no area and no position are given, then the entire surface is searched.
Each DecorativeResult is a table:
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
Clears all pollution on this surface.
Plays a sound on this surface.
Gets the resource amount of all resources on this surface
Gets a random generated chunk position or 0,0 if no chunks have been generated on this surface.
Clones the given area.
Clones the given area.
Clones the given entities.
Clears this surface deleting all entities and chunks on it.
Starts a path find request without actually ordering a unit to move. Result is ultimately returned asynchronously via defines.events.on_script_path_request_finished.
Gets the script areas that match the given name or if no name is given all areas are returned.
Sets the given script area to the new values.
Removes the given script area.
Gets the script positions that match the given name or if no name is given all positions are returned.
Sets the given script position to the new values.
Adds the given script position.
Removes the given script position.
Gets the map exchange string for the current map generation settings of this surface.
Gets the starting area radius of this surface.
Gets train stops matching the given filters.
Gets the total amount of pollution on the surface by iterating over all of the chunks containing pollution.
Returns all the entities with force on this chunk for the given force.
Sets the given area to the checkerboard lab tiles.
The name of this surface. Names are unique among surfaces.
Unique ID associated with this surface.
The generation settings for the surface.
can be used to adjust the surface after changing generation settings.
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, the sun will always shine.
Current time of day, as a number in range [0, 1).
Amount of darkness at the current time.
Current wind speed.
Current wind direction.
Change in wind orientation per tick.
Is peaceful mode enabled on this surface?
True if daytime is currently frozen.
The number of ticks per day for this surface.
The daytime when dusk starts.
The daytime when dawn starts.
The daytime when evening starts.
The daytime when morning starts.
The multiplier of solar power on this surface. Cannot be less than 0.
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.
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.
0.15
.
game.surfaces[1].brightness_visual_weights = { 1 / 0.85, 1 / 0.85, 1 / 0.85 }
If clouds are shown on this surface.