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=…, name=…, type=…, ghost_name=…, ghost_type=…, direction=…, collision_mask=…, force=…, limit=…, invert=…} → array of LuaEntity | Find entities of given type or name in a given area. |
find_tiles_filtered{area=…, 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=…, name=…, type=…, ghost_name=…, ghost_type=…, direction=…, collision_mask=…, force=…, limit=…, invert=…} → uint | Count entities of given type or name in a given area. |
count_tiles_filtered{area=…, 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) → Position | Find a non-colliding position within a given rectangle. |
spill_item_stack(position, items, enable_looted, force) | Spill items on the ground centered at a given location. |
find_enemy_units(center, radius, force) → array of LuaEntity | Find units enemy of a given force within an area. |
find_units{} → array of LuaEntity | Find units of a given force and force condition within a given area. |
find_nearest_enemy{position=…, max_distance=…, force=…} → LuaEntity | Find the enemy closest to the given position. |
set_multi_command{command=…, unit_count=…, force=…, unit_search_distance=…} → uint | Give a command to multiple units. |
create_entity{name=…, position=…, direction=…, force=…, target=…, source=…, fast_replace=…, player=…, spill=…, raise_built=…, create_build_effect_smoke=…} → LuaEntity | Create an entity on this surface. |
create_trivial_smoke{name=…, position=…} | |
create_unit_group{position=…, force=…} → LuaUnitGroup | Create a new unit group at a given position. |
build_enemy_base(position, unit_count, force) | Send a group to build a new base. |
get_tile(x, y) → LuaTile | Get the tile at a given position. |
set_tiles(tiles, correct_tiles) | Set tiles at specified locations. |
pollute(source, amount) | Spawn pollution at the given position. |
get_chunks() → LuaChunkIterator | Get an iterator going over every chunk on this surface. |
is_chunk_generated(position) → boolean | Is a given chunk generated? |
request_to_generate_chunks(position, radius) | Request that the game's map generator generate chunks at the given position for the given radius on this surface. |
force_generate_chunk_requests() | Blocks and generates all chunks that have been requested using all available threads. |
set_chunk_generated_status(position, status) | Set generated status of a chunk. |
find_logistic_network_by_position(position, force) → LuaLogisticNetwork | Find the logistic network that covers a given position. |
find_logistic_networks_by_construction_area(position, force) → array of LuaLogisticNetwork | Finds all of the logistics networks whose construction area intersects with the given position. |
deconstruct_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} | Place a deconstruction request. |
cancel_deconstruct_area{area=…, force=…, player=…, skip_fog_of_war=…, item=…} | Cancel a deconstruction order. |
get_hidden_tile(position) → string | The hidden tile name or nil if there isn't one for the given position. |
set_hidden_tile(position, tile) | |
get_connected_tiles(position, tiles) → array of Position | Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position. |
delete_chunk(position) | |
regenerate_entity(entities, chunks) | Regenerate autoplacement of some entities on this surface. |
regenerate_decorative(decoratives, chunks) | Regenerate autoplacement of some decoratives on this surface. |
print(message, color) | Print text to the chat console of all players on this surface. |
destroy_decoratives{area=…, position=…, name=…, limit=…, invert=…} | Removes all decoratives from the given area. |
create_decoratives{check_collision=…, decoratives=…} | Adds the given decoratives to the surface. |
find_decoratives_filtered{area=…, position=…, name=…, limit=…, invert=…} → array of DecorativeResult | Find decoratives of a given name in a given area. |
get_trains(force) → array of LuaTrain | |
clear_pollution() | Clears all pollution on this surface. |
play_sound{path=…, position=…, volume_modifier=…} → boolean | Plays a sound on this surface. |
get_resource_counts() → dictionary 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=…, expand_map=…} | Clones the given area. |
clone_entities{entities=…, destination_offset=…, destination_force=…, snap_to_grid=…} | Clones the given entities. |
clear() | 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=…} → uint | Starts a path find request without actually ordering a unit to move. |
get_script_areas(name) → array of ScriptArea | Gets the script areas that match the given name or if no name is given all areas are returned. |
get_script_positions(name) → array of ScriptPosition | Gets the script positions that match the given name or if no name is given all positions are returned. |
get_map_exchange_string() → string | Gets the map exchange string for the current map generation settings of this surface. |
get_starting_area_radius() → double | Gets the starting area radius of this surface. |
get_closest(position, entities) → LuaEntity | Gets the closest entity in the list to this position. |
get_train_stops(opts) → array of LuaEntity | Gets train stops matching the given filters. |
name :: string [RW] | The name of this surface. |
index :: uint [R] | Unique ID associated with this surface. |
map_gen_settings :: MapGenSettings [RW] | The generation settings for the surface. |
always_day :: boolean [RW] | When set to true, the sun will always shine. |
daytime :: float [RW] | Current time of day, as a number in range [0, 1). |
darkness :: float [R] | Amount of darkness at the current time. |
wind_speed :: float [RW] | Current wind speed. |
wind_orientation :: float [RW] | Current wind direction. |
wind_orientation_change :: float [RW] | Change in wind orientation per tick. |
peaceful_mode :: boolean [RW] | Is peaceful mode enabled on this surface? |
freeze_daytime :: boolean [RW] | True if daytime is currently frozen. |
ticks_per_day :: uint [RW] | The number of ticks per day for this surface. |
dusk :: double [RW] | The daytime when dusk starts. |
dawn :: double [RW] | The daytime when dawn starts. |
evening :: double [RW] | The daytime when evening starts. |
morning :: double [RW] | The daytime when morning starts. |
valid :: boolean [R] | Is this object valid? |
help() → string | All methods, and properties that this object supports. |
A "domain" of the world. Surfaces can only be created and deleted through the API. Surfaces are uniquely identified by their name. Every game contains at least the surface "nauvis".
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
, or force
) are given, returns all entities in the search area.
If multiple filters are specified, returns only entities matching all given filters.
If no area and no position are given, then the entire surface is searched. If both area and position are specified, returns only entities matching the position.
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
Find tiles of a given name in a given area.
If no filters are given returns all tiles in the search area.
If no area is given, then the entire surface is searched.
Count entities of given type or name in a given area. Works just like LuaSurface::find_entities_filtered, except this only returns the count. As it doesn't construct all the wrapper objects, this is more efficient if one is only interested in the number of entities.
If no area and no position are given, then the entire surface is searched. If both area and position are specified, returns only entities matching the position.
Count tiles of a given name in a given area. Works just like LuaSurface::find_tiles_filtered, except this only returns the count. As it doesn't construct all the wrapper objects, this is more efficient if one is only interested in the number of tiles.
If no area is given, then the entire surface is searched.
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 units enemy of a given force within an area.
local enemies = game.player.surface.find_enemy_units(game.player.position, 100)
Find units 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 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.
"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.
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.
Regenerate autoplacement of some decoratives on this surface. This can be used to autoplace newly-added decoratives.
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.
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 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.
Gets the script positions that match the given name or if no name is given all positions are returned.
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.
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, 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.