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. |
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. |
Check for collisions with terrain or other entities. |
||
can_fast_replace{name=…, position=…, direction?=…, force?=…} | → boolean |
If there exists an entity at the given location that can be fast-replaced with the given entity parameters. |
If there exists an entity at the given location that can be fast-replaced with the given entity parameters. |
||
find_entity(entity, position) | → LuaEntity? |
Find an entity of the given type at the given position. |
Find an entity of the given type at the given position. |
||
find_entities(area?) | → array[LuaEntity] |
Find entities in a given area. |
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?=…, is_military_target?=…, has_item_inside?=…, invert?=…} | → array[LuaEntity] |
Find all entities of the given type or name in the given area. |
Find all entities of the given type or name in the given area. |
||
find_tiles_filtered{area?=…, position?=…, radius?=…, name?=…, force?=…, limit?=…, has_hidden_tile?=…, has_tile_ghost?=…, to_be_deconstructed?=…, collision_mask?=…, invert?=…} | → array[LuaTile] |
Find all tiles of the given name in the given area. |
Find all tiles of the given name in the given area. |
||
count_entities_filtered{area?=…, position?=…, radius?=…, name?=…, type?=…, ghost_name?=…, ghost_type?=…, direction?=…, collision_mask?=…, force?=…, to_be_deconstructed?=…, to_be_upgraded?=…, limit?=…, is_military_target?=…, invert?=…} | → uint |
Count entities of given type or name in a given area. |
Count entities of given type or name in a given area. |
||
count_tiles_filtered{area?=…, position?=…, radius?=…, name?=…, force?=…, limit?=…, has_hidden_tile?=…, has_tile_ghost?=…, to_be_deconstructed?=…, collision_mask?=…, invert?=…} | → uint |
Count tiles of a given name in a given area. |
Count tiles of a given name in a given area. |
||
find_non_colliding_position(name, center, radius, precision, force_to_tile_center?) | → MapPosition? |
Find a non-colliding position within a given radius. |
Find a non-colliding position within a given radius. |
||
find_non_colliding_position_in_box(name, search_space, precision, force_to_tile_center?) | → MapPosition? |
Find a non-colliding position within a given rectangle. |
Find a non-colliding position within a given rectangle. |
||
spill_item_stack(position, items, enable_looted?, force?, allow_belts?) | → array[LuaEntity] |
Spill items on the ground centered at a given location. |
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 enemy units (entities with type "unit") of a given force within an area. |
||
find_units{area=…, force=…, condition=…} | → array[LuaEntity] |
Find units (entities with type "unit") of a given force and force condition within a given area. |
Find units (entities with type "unit") of a given force and force condition within a given area. |
||
find_nearest_enemy{position=…, max_distance=…, force?=…} | → LuaEntity? |
Find the enemy military target (military entity) closest to the given position. |
Find the enemy military target (military entity) closest to the given position. |
||
find_nearest_enemy_entity_with_owner{position=…, max_distance=…, force?=…} | → LuaEntity |
Find the enemy entity-with-owner closest to the given position. |
Find the enemy entity-with-owner closest to the given position. |
||
set_multi_command{command=…, unit_count=…, force?=…, unit_search_distance?=…} | → uint |
Give a command to multiple units. |
Give a command to multiple units. |
||
create_entity{name=…, position=…, direction?=…, force?=…, target?=…, source?=…, fast_replace?=…, player?=…, character?=…, spill?=…, raise_built?=…, create_build_effect_smoke?=…, spawn_decorations?=…, move_stuck_players?=…, item?=…} | → LuaEntity? |
Create an entity on this surface. |
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 |
|
Creates a particle at the given location |
||
create_unit_group{position=…, force?=…} | → LuaUnitGroup |
Create a new unit group at a given position. |
Create a new unit group at a given position. |
||
build_enemy_base(position, unit_count, force?) |
Send a group to build a new base. |
|
Send a group to build a new base. |
||
get_tile(x, y) | → LuaTile |
Get the tile at a given position. |
Get the tile at a given position. |
||
set_tiles(tiles, correct_tiles?, remove_colliding_entities?, remove_colliding_decoratives?, raise_event?) |
Set tiles at specified locations. |
|
Set tiles at specified locations. |
||
pollute(source, amount) |
Spawn pollution at the given position. |
|
Spawn pollution at the given position. |
||
get_chunks() | → LuaChunkIterator |
Get an iterator going over every chunk on this surface. |
Get an iterator going over every chunk on this surface. |
||
is_chunk_generated(position) | → boolean |
Is a given chunk generated? |
Is a given chunk generated? |
||
request_to_generate_chunks(position, radius) |
Request that the game's map generator generate chunks at the given position for the given radius on this surface. |
|
Request that the game's map generator generate chunks at the given position for the given radius on this surface. |
||
force_generate_chunk_requests() |
Blocks and generates all chunks that have been requested using all available threads. |
|
Blocks and generates all chunks that have been requested using all available threads. |
||
set_chunk_generated_status(position, status) |
Set generated status of a chunk. |
|
Set generated status of a chunk. |
||
find_logistic_network_by_position(position, force) | → LuaLogisticNetwork? |
Find the logistic network that covers a given position. |
Find the logistic network that covers a given position. |
||
find_closest_logistic_network_by_position(position, force) | → LuaLogisticNetwork? |
Find the logistic network with a cell closest to a given position. |
Find the logistic network with a cell closest to a given position. |
||
find_logistic_networks_by_construction_area(position, force) | → array[LuaLogisticNetwork] |
Finds all of the logistics networks whose construction area intersects with the given position. |
Finds all of the logistics networks whose construction area intersects with the given position. |
||
deconstruct_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item?=…} |
Place a deconstruction request. |
|
Place a deconstruction request. |
||
cancel_deconstruct_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item?=…} |
Cancel a deconstruction order. |
|
Cancel a deconstruction order. |
||
upgrade_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item=…} |
Place an upgrade request. |
|
Place an upgrade request. |
||
cancel_upgrade_area{area=…, force=…, player?=…, skip_fog_of_war?=…, item?=…} |
Cancel a upgrade order. |
|
Cancel a upgrade order. |
||
get_hidden_tile(position) | → string? |
The hidden tile name. |
The hidden tile name. |
||
set_hidden_tile(position, tile) |
Set the hidden tile for the specified position. |
|
Set the hidden tile for the specified position. |
||
get_connected_tiles(position, tiles, include_diagonal?, area?) | → array[TilePosition] |
Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position. |
Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position. |
||
delete_chunk(position) |
|
|
regenerate_entity(entities?, chunks?) |
Regenerate autoplacement of some entities on this surface. |
|
Regenerate autoplacement of some entities on this surface. |
||
regenerate_decorative(decoratives?, chunks?) |
Regenerate autoplacement of some decoratives on this surface. |
|
Regenerate autoplacement of some decoratives on this surface. |
||
print(message, color?) |
Print text to the chat console of all players on this surface. |
|
Print text to the chat console of all players on this surface. |
||
destroy_decoratives{area?=…, position?=…, name?=…, collision_mask?=…, from_layer?=…, to_layer?=…, exclude_soft?=…, limit?=…, invert?=…} |
Removes all decoratives from the given area. |
|
Removes all decoratives from the given area. |
||
create_decoratives{check_collision?=…, decoratives=…} |
Adds the given decoratives to the surface. |
|
Adds the given decoratives to the surface. |
||
find_decoratives_filtered{area?=…, position?=…, name?=…, collision_mask?=…, from_layer?=…, to_layer?=…, exclude_soft?=…, limit?=…, invert?=…} | → array[DecorativeResult] |
Find decoratives of a given name in a given area. |
Find decoratives of a given name in a given area. |
||
get_trains(force?) | → array[LuaTrain] |
|
clear_pollution() |
Clears all pollution on this surface. |
|
Clears all pollution on this surface. |
||
play_sound{path=…, position?=…, volume_modifier?=…, override_sound_type?=…} |
Play a sound for every player on this surface. |
|
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 |
Gets the resource amount of all resources on this surface |
||
get_random_chunk() | → ChunkPosition |
Gets a random generated chunk position or 0,0 if no chunks have been generated on this surface. |
Gets a random generated chunk position or 0,0 if no chunks have been generated on this surface. |
||
clone_area{source_area=…, destination_area=…, destination_surface?=…, destination_force?=…, clone_tiles?=…, clone_entities?=…, clone_decoratives?=…, clear_destination_entities?=…, clear_destination_decoratives?=…, expand_map?=…, create_build_effect_smoke?=…} |
Clones the given area. |
|
Clones the given area. |
||
clone_brush{source_offset=…, destination_offset=…, source_positions=…, destination_surface?=…, destination_force?=…, clone_tiles?=…, clone_entities?=…, clone_decoratives?=…, clear_destination_entities?=…, clear_destination_decoratives?=…, expand_map?=…, manual_collision_mode?=…, create_build_effect_smoke?=…} |
Clones the given area. |
|
Clones the given area. |
||
clone_entities{entities=…, destination_offset=…, destination_surface?=…, destination_force?=…, snap_to_grid?=…, create_build_effect_smoke?=…} |
Clones the given entities. |
|
Clones the given entities. |
||
clear(ignore_characters?) |
Clears this surface deleting all entities and chunks on it. |
|
Clears this surface deleting all entities and chunks on it. |
||
request_path{bounding_box=…, collision_mask=…, start=…, goal=…, force=…, radius?=…, pathfind_flags?=…, can_open_gates?=…, path_resolution_modifier?=…, entity_to_ignore?=…} | → uint |
Generates a path with the specified constraints (as an array of PathfinderWaypoints) using the unit pathfinding algorithm. |
Generates a path with the specified constraints (as an array of PathfinderWaypoints) using the unit pathfinding algorithm. |
||
get_script_areas(name?) | → array[ScriptArea] |
Gets the script areas that match the given name or if no name is given all areas are returned. |
Gets the script areas that match the given name or if no name is given all areas are returned. |
||
get_script_area(key?) | → ScriptArea? |
Gets the first script area by name or id. |
Gets the first script area by name or id. |
||
edit_script_area(id, area) |
Sets the given script area to the new values. |
|
Sets the given script area to the new values. |
||
add_script_area(area) | → uint |
Adds the given script area. |
Adds the given script area. |
||
remove_script_area(id) | → boolean |
Removes the given script area. |
Removes the given script area. |
||
get_script_positions(name?) | → array[ScriptPosition] |
Gets the script positions that match the given name or if no name is given all positions are returned. |
Gets the script positions that match the given name or if no name is given all positions are returned. |
||
get_script_position(key?) | → ScriptPosition? |
Gets the first script position by name or id. |
Gets the first script position by name or id. |
||
edit_script_position(id, area) |
Sets the given script position to the new values. |
|
Sets the given script position to the new values. |
||
add_script_position(area) | → uint |
Adds the given script position. |
Adds the given script position. |
||
remove_script_position(id) | → boolean |
Removes the given script position. |
Removes the given script position. |
||
get_map_exchange_string() | → string |
Gets the map exchange string for the current map generation settings of this surface. |
Gets the map exchange string for the current map generation settings of this surface. |
||
get_starting_area_radius() | → double |
Gets the starting area radius of this surface. |
Gets the starting area radius of this surface. |
||
get_closest(position, entities) | → LuaEntity? |
Gets the closest entity in the list to this position. |
Gets the closest entity in the list to this position. |
||
get_train_stops{name?=…, force?=…} | → array[LuaEntity] |
Gets train stops matching the given filters. |
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. |
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?) | → boolean |
Whether the given entity prototype collides at the given position and direction. |
Whether the given entity prototype collides at the given position and direction. |
||
decorative_prototype_collides(prototype, position) | → boolean |
Whether the given decorative prototype collides at the given position and direction. |
Whether the given decorative prototype collides at the given position and direction. |
||
calculate_tile_properties(property_names, positions) | → dictionary[string → array[double]] |
|
get_entities_with_force(position, force) | → array[LuaEntity] |
Returns all the military targets (entities with force) on this chunk for the given force. |
Returns all the military targets (entities with force) on this chunk for the given force. |
||
build_checkerboard(area) |
Sets the given area to the checkerboard lab tiles. |
|
Sets the given area to the checkerboard lab tiles. |
||
help() | → string |
All methods and properties that this object supports. |
All methods and properties that this object supports. |
||
name [RW] | :: string |
The name of this surface. |
The name of this surface. |
||
index [R] | :: uint |
This surface's index in LuaGameScript::surfaces (unique ID). |
This surface's index in LuaGameScript::surfaces (unique ID). |
||
map_gen_settings [RW] | :: MapGenSettings |
The generation settings for this surface. |
The generation settings for this surface. |
||
generate_with_lab_tiles [RW] | :: boolean |
When set to true, new chunks will be generated with lab tiles, instead of using the surface's map generation settings. |
When set to true, new chunks will be generated with lab tiles, instead of using the surface's map generation settings. |
||
always_day [RW] | :: boolean |
When set to true, the sun will always shine. |
When set to true, the sun will always shine. |
||
daytime [RW] | :: double |
Current time of day, as a number in range [0, 1). |
Current time of day, as a number in range [0, 1). |
||
darkness [R] | :: float |
Amount of darkness at the current time, as a number in range [0, 1]. |
Amount of darkness at the current time, as a number in range [0, 1]. |
||
wind_speed [RW] | :: double |
Current wind speed in tiles per tick. |
Current wind speed in tiles per tick. |
||
wind_orientation [RW] | :: RealOrientation |
Current wind direction. |
Current wind direction. |
||
wind_orientation_change [RW] | :: double |
Change in wind orientation per tick. |
Change in wind orientation per tick. |
||
peaceful_mode [RW] | :: boolean |
Is peaceful mode enabled on this surface? |
Is peaceful mode enabled on this surface? |
||
freeze_daytime [RW] | :: boolean |
True if daytime is currently frozen. |
True if daytime is currently frozen. |
||
ticks_per_day [RW] | :: uint |
The number of ticks per day for this surface. |
The number of ticks per day for this surface. |
||
dusk [RW] | :: double |
The daytime when dusk starts. |
The daytime when dusk starts. |
||
dawn [RW] | :: double |
The daytime when dawn starts. |
The daytime when dawn starts. |
||
evening [RW] | :: double |
The daytime when evening starts. |
The daytime when evening starts. |
||
morning [RW] | :: double |
The daytime when morning starts. |
The daytime when morning starts. |
||
solar_power_multiplier [RW] | :: double |
The multiplier of solar power on this surface. |
The multiplier of solar power on this surface. |
||
min_brightness [RW] | :: double |
The minimal brightness during the night. |
The minimal brightness during the night. |
||
brightness_visual_weights [RW] | :: ColorModifier |
Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT). |
Defines how surface daytime brightness influences each color channel of the current color lookup table (LUT). |
||
show_clouds [RW] | :: boolean |
If clouds are shown on this surface. |
If clouds are shown on this surface. |
||
valid [R] | :: boolean |
Is this object valid? |
Is this object valid? |
||
object_name [R] | :: string |
The class name of this object. |
The class name of this object. |
Get the pollution for a given position.
position | :: MapPosition |
|
|
Pollution is stored per chunk, so this will return the same value for all positions in one chunk.
Check for collisions with terrain or other entities.
name | :: string |
Name of the entity prototype to check. |
Name of the entity prototype to check. |
||
position | :: MapPosition |
Where the entity would be placed. |
Where the entity would be placed. |
||
direction | :: defines.direction? |
Direction of the placed entity. Defaults to |
Direction of the placed entity. Defaults to |
||
force | :: ForceIdentification? |
The force that would place the entity. Defaults to the |
The force that would place the entity. Defaults to the |
||
build_check_type | :: defines.build_check_type? |
Which type of check should be carried out. Defaults to |
Which type of check should be carried out. Defaults to |
||
forced | :: boolean? |
If |
If |
||
inner_name | :: string? |
The prototype name of the entity contained in the ghost. Only used if |
The prototype name of the entity contained in the ghost. Only used if |
If there exists an entity at the given location that can be fast-replaced with the given entity parameters.
name | :: string |
Name of the entity to check. |
Name of the entity to check. |
||
position | :: MapPosition |
Where the entity would be placed. |
Where the entity would be placed. |
||
direction | :: defines.direction? |
Direction the entity would be placed. Defaults to |
Direction the entity would be placed. Defaults to |
||
force | :: ForceIdentification? |
The force that would place the entity. Defaults to the |
The force that would place the entity. Defaults to the |
Find an entity of the given type at the given position. This checks both the exact position and the bounding box of the entity.
entity | :: string |
Entity to look for. |
Entity to look for. |
||
position | :: MapPosition |
Coordinates to look at. |
Coordinates to look at. |
→ LuaEntity? |
|
|
Find entities in a given area.
If no area is given all entities on the surface are returned.
area | :: BoundingBox? |
|
Will evaluate to a list of all entities within given area.
|
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.
area
or position
are given, the entire surface is searched.position
is given, this returns the entities colliding with that position (i.e the given position is within the entity's collision box).position
and radius
are given, this returns the entities within the radius of the position. Looks for the center of entities.area
is specified, this returns the entities colliding with that area.area | :: BoundingBox? |
|
position | :: MapPosition? |
Has precedence over area field. |
Has precedence over area field. |
||
radius | :: double? |
|
name | :: string or array[string]? |
|
type | :: string or array[string]? |
|
ghost_name | :: string or array[string]? |
|
ghost_type | :: string or array[string]? |
|
direction | :: defines.direction or array[defines.direction]? |
|
collision_mask | :: CollisionMaskLayer or array[CollisionMaskLayer]? |
|
force | :: ForceIdentification or array[ForceIdentification]? |
|
to_be_deconstructed | :: boolean? |
|
to_be_upgraded | :: boolean? |
|
limit | :: uint? |
|
is_military_target | :: boolean? |
|
has_item_inside | :: LuaItemPrototype? |
|
invert | :: boolean? |
Whether the filters should be inverted. |
Whether the filters should be inverted. |
|
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.
area | :: BoundingBox? |
|
position | :: MapPosition? |
Ignored if not given with radius. |
Ignored if not given with radius. |
||
radius | :: double? |
If given with position, will return all entities within the radius of the position. |
If given with position, will return all entities within the radius of the position. |
||
name | :: string or array[string]? |
|
force | :: ForceIdentification or array[ForceIdentification]? |
|
limit | :: uint? |
|
has_hidden_tile | :: boolean? |
|
has_tile_ghost | :: boolean? |
Can be further filtered by supplying a |
Can be further filtered by supplying a |
||
to_be_deconstructed | :: boolean? |
Can be further filtered by supplying a |
Can be further filtered by supplying a |
||
collision_mask | :: CollisionMaskLayer or array[CollisionMaskLayer]? |
|
invert | :: boolean? |
Whether the filters should be inverted. |
Whether the filters should be inverted. |
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.
area | :: BoundingBox? |
|
position | :: MapPosition? |
|
radius | :: double? |
If given with position, will count all entities within the radius of the position. |
If given with position, will count all entities within the radius of the position. |
||
name | :: string or array[string]? |
|
type | :: string or array[string]? |
|
ghost_name | :: string or array[string]? |
|
ghost_type | :: string or array[string]? |
|
direction | :: defines.direction or array[defines.direction]? |
|
collision_mask | :: CollisionMaskLayer or array[CollisionMaskLayer]? |
|
force | :: ForceIdentification or array[ForceIdentification]? |
|
to_be_deconstructed | :: boolean? |
|
to_be_upgraded | :: boolean? |
|
limit | :: uint? |
|
is_military_target | :: boolean? |
|
invert | :: boolean? |
Whether the filters should be inverted. |
Whether the filters should be inverted. |
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.
area | :: BoundingBox? |
|
position | :: MapPosition? |
Ignored if not given with radius. |
Ignored if not given with radius. |
||
radius | :: double? |
If given with position, will return all entities within the radius of the position. |
If given with position, will return all entities within the radius of the position. |
||
name | :: string or array[string]? |
|
force | :: ForceIdentification or array[ForceIdentification]? |
|
limit | :: uint? |
|
has_hidden_tile | :: boolean? |
|
has_tile_ghost | :: boolean? |
Can be further filtered by supplying a |
Can be further filtered by supplying a |
||
to_be_deconstructed | :: boolean? |
Can be further filtered by supplying a |
Can be further filtered by supplying a |
||
collision_mask | :: CollisionMaskLayer or array[CollisionMaskLayer]? |
|
invert | :: boolean? |
If the filters should be inverted. |
If the filters should be inverted. |
Find a non-colliding position within a given radius.
name | :: string |
Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.) |
Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.) |
||
center | :: MapPosition |
Center of the search area. |
Center of the search area. |
||
radius | :: double |
Max distance from |
Max distance from |
||
precision | :: double |
The step length from the given position as it searches, in tiles. Minimum value is |
The step length from the given position as it searches, in tiles. Minimum value is |
||
force_to_tile_center | :: boolean? |
Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Default false. |
Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Default false. |
→ MapPosition? |
The non-colliding position. May be |
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 a non-colliding position within a given rectangle.
name | :: string |
Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.) |
Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.) |
||
search_space | :: BoundingBox |
The rectangle to search inside. |
The rectangle to search inside. |
||
precision | :: double |
The step length from the given position as it searches, in tiles. Minimum value is 0.01. |
The step length from the given position as it searches, in tiles. Minimum value is 0.01. |
||
force_to_tile_center | :: boolean? |
Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Default false. |
Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Default false. |
→ MapPosition? |
The non-colliding position. May be |
Spill items on the ground centered at a given location.
position | :: MapPosition |
Center of the spillage |
Center of the spillage |
||
items | :: ItemStackIdentification |
Items to spill |
Items to spill |
||
enable_looted | :: boolean? |
When true, each created item will be flagged with the LuaEntity::to_be_looted flag. |
When true, each created item will be flagged with the LuaEntity::to_be_looted flag. |
||
force | :: LuaForce or string? |
When provided (and not |
When provided (and not |
||
allow_belts | :: boolean? |
Whether items can be spilled onto belts. Defaults to |
Whether items can be spilled onto belts. Defaults to |
→ array[LuaEntity] |
The created item-on-ground entities. |
Find enemy units (entities with type "unit") of a given force within an area.
center | :: MapPosition |
Center of the search area |
Center of the search area |
||
radius | :: double |
Radius of the circular search area |
Radius of the circular search area |
||
force | :: LuaForce or string? |
Force to find enemies of. If not given, uses the player force. |
Force to find enemies of. If not given, uses the player force. |
Find all units who would be interested to attack the player, within 100-tile area.
|
This is more efficient than LuaSurface::find_entities.
Find units (entities with type "unit") of a given force and force condition within a given area.
area | :: BoundingBox |
Box to find units within. |
Box to find units within. |
||
force | :: LuaForce or string |
Force performing the search. |
Force performing the search. |
||
condition | :: ForceCondition |
Only forces which meet the condition will be included in the search. |
Only forces which meet the condition will be included in the search. |
Find friendly units to "player" force
|
Find units of "player" force
|
This is more efficient than LuaSurface::find_entities.
Find the enemy military target (military entity) closest to the given position.
position | :: MapPosition |
Center of the search area. |
Center of the search area. |
||
max_distance | :: double |
Radius of the circular search area. |
Radius of the circular search area. |
||
force | :: ForceIdentification? |
The force the result will be an enemy of. Uses the player force if not specified. |
The force the result will be an enemy of. Uses the player force if not specified. |
→ LuaEntity? |
The nearest enemy military target or |
Find the enemy entity-with-owner closest to the given position.
position | :: MapPosition |
Center of the search area. |
Center of the search area. |
||
max_distance | :: double |
Radius of the circular search area. |
Radius of the circular search area. |
||
force | :: ForceIdentification? |
The force the result will be an enemy of. Uses the player force if not specified. |
The force the result will be an enemy of. Uses the player force if not specified. |
→ LuaEntity |
The nearest enemy entity-with-owner or |
Give a command to multiple units. This will automatically select suitable units for the task.
command | :: Command |
|
unit_count | :: uint |
Number of units to give the command to. |
Number of units to give the command to. |
||
force | :: ForceIdentification? |
Force of the units this command is to be given to. If not specified, uses the enemy force. |
Force of the units this command is to be given to. If not specified, uses the enemy force. |
||
unit_search_distance | :: uint? |
Radius to search for units. The search area is centered on the destination of the command. |
Radius to search for units. The search area is centered on the destination of the command. |
→ uint |
Number of units actually sent. May be less than |
Create an entity on this surface.
name | :: string |
The entity prototype name to create. |
The entity prototype name to create. |
||
position | :: MapPosition |
Where to create the entity. |
Where to create the entity. |
||
direction | :: defines.direction? |
Desired orientation of the entity after creation. |
Desired orientation of the entity after creation. |
||
force | :: ForceIdentification? |
Force of the entity, default is enemy. |
Force of the entity, default is enemy. |
||
target | :: LuaEntity or MapPosition? |
Entity with health for the new entity to target. |
Entity with health for the new entity to target. |
||
source | :: LuaEntity or MapPosition? |
Source entity. Used for beams, projectiles, and highlight-boxes. |
Source entity. Used for beams, projectiles, and highlight-boxes. |
||
fast_replace | :: boolean? |
If true, building will attempt to simulate fast-replace building. |
If true, building will attempt to simulate fast-replace building. |
||
player | :: PlayerIdentification? |
If given set the last_user to this player. If fast_replace is true simulate fast replace using this player. |
If given set the last_user to this player. If fast_replace is true simulate fast replace using this player. |
||
character | :: LuaEntity? |
If fast_replace is true simulate fast replace using this character. |
If fast_replace is true simulate fast replace using this character. |
||
spill | :: boolean? |
If false while fast_replace is true and player is nil any items from fast-replacing will be deleted instead of dropped on the ground. |
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? |
If true; defines.events.script_raised_built will be fired on successful entity creation. |
If true; defines.events.script_raised_built will be fired on successful entity creation. |
||
create_build_effect_smoke | :: boolean? |
If false, the building effect smoke will not be shown around the new entity. |
If false, the building effect smoke will not be shown around the new entity. |
||
spawn_decorations | :: boolean? |
If true, entity types that have spawn_decorations property will apply triggers defined in the property. |
If true, entity types that have spawn_decorations property will apply triggers defined in the property. |
||
move_stuck_players | :: boolean? |
If true, any characters that are in the way of the entity are teleported out of the way. |
If true, any characters that are in the way of the entity are teleported out of the way. |
||
item | :: LuaItemStack? |
If provided, the entity will attempt to pull stored values from this item (for example; creating a spidertron from a previously named and mined spidertron) |
If provided, the entity will attempt to pull stored values from this item (for example; creating a spidertron from a previously named and mined spidertron) |
Other attributes may be specified depending on the type of entity:
assembling-machine
recipe | :: string? |
|
beam
target_position | :: MapPosition? |
Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined). |
Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined). |
||
source_position | :: MapPosition? |
Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined). |
Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined). |
||
max_length | :: uint? |
If set, beam will be destroyed when distance between source and target is greater than this value. |
If set, beam will be destroyed when distance between source and target is greater than this value. |
||
duration | :: uint? |
If set, beam will be destroyed after this value of ticks. |
If set, beam will be destroyed after this value of ticks. |
||
source_offset | :: Vector? |
Source position will be offset by this value when rendering the beam. |
Source position will be offset by this value when rendering the beam. |
stream
target_position | :: MapPosition? |
Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined). |
Absolute target position that can be used instead of target entity (entity has precedence if both entity and position are defined). |
||
source_position | :: MapPosition? |
Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined). |
Absolute source position that can be used instead of source entity (entity has precedence if both entity and position are defined). |
||
source_offset | :: Vector? |
Source position will be offset by this value when rendering the stream. |
Source position will be offset by this value when rendering the stream. |
container
bar | :: uint? |
Inventory index where the red limiting bar should be set. |
Inventory index where the red limiting bar should be set. |
cliff
cliff_orientation | :: CliffOrientation? |
If not specified, |
If not specified, |
flying-text
text | :: LocalisedString |
The string to show. |
The string to show. |
||
color | :: Color? |
Color of the displayed text. |
Color of the displayed text. |
||
render_player_index | :: uint? |
|
entity-ghost
inner_name | :: string |
The prototype name of the entity contained in the ghost. |
The prototype name of the entity contained in the ghost. |
||
expires | :: boolean? |
If |
If |
fire
initial_ground_flame_count | :: uint8? |
With how many small flames should the fire on ground be created. Defaults to the initial flame count of the prototype. |
With how many small flames should the fire on ground be created. Defaults to the initial flame count of the prototype. |
inserter
conditions | :: InserterCircuitConditions |
|
filters | :: array[InventoryFilter] |
|
item-entity
stack | :: SimpleItemStack |
The stack of items to create. |
The stack of items to create. |
item-request-proxy
target | :: LuaEntity |
The target items are to be delivered to. |
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. |
The stacks of items to be delivered to target entity from logistic network. |
rolling-stock
orientation | :: RealOrientation? |
The orientation of this rolling stock. |
The orientation of this rolling stock. |
||
color | :: Color? |
The color of this rolling stock, if it supports colors. |
The color of this rolling stock, if it supports colors. |
locomotive
snap_to_train_stop | :: boolean? |
Whether the locomotive should snap to an adjacent train stop. Defaults to true. |
Whether the locomotive should snap to an adjacent train stop. Defaults to true. |
logistic-container
request_filters | :: array[InventoryFilter]? |
|
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? |
|
artillery-projectile
speed | :: double |
|
max_range | :: double? |
|
resource
amount | :: uint |
|
enable_tree_removal | :: boolean? |
If colliding trees are removed normally for this resource entity based off the prototype tree removal values. Default is true. |
If colliding trees are removed normally for this resource entity based off the prototype tree removal values. Default is true. |
||
enable_cliff_removal | :: boolean? |
If colliding cliffs are removed. Default is true. |
If colliding cliffs are removed. Default is true. |
||
snap_to_tile_center | :: boolean? |
If true, the resource entity will be placed to center of a tile as map generator would place it, otherwise standard non-resource grid alignment rules will apply. Default is true. |
If true, the resource entity will be placed to center of a tile as map generator would place it, otherwise standard non-resource grid alignment rules will apply. Default is true. |
underground-belt
type | :: string? |
|
|
programmable-speaker
parameters | :: ProgrammableSpeakerParameters? |
|
alert_parameters | :: ProgrammableSpeakerAlertParameters? |
|
character-corpse
inventory_size | :: uint? |
|
player_index | :: uint? |
|
highlight-box
bounding_box | :: BoundingBox? |
The bounding box defining the highlight box using absolute map coordinates. If specified, the general |
The bounding box defining the highlight box using absolute map coordinates. If specified, the general |
||
box_type | :: CursorBoxRenderType? |
Specifies the graphical appearance (color) of the highlight box. Defaults to |
Specifies the graphical appearance (color) of the highlight box. Defaults to |
||
render_player_index | :: uint? |
The player to render the highlight box for. If not provided, it will be rendered for all players. |
The player to render the highlight box for. If not provided, it will be rendered for all players. |
||
blink_interval | :: uint? |
The blink interval for this highlight box. Makes it be shown every |
The blink interval for this highlight box. Makes it be shown every |
||
time_to_live | :: uint? |
The amount of time in ticks that the highlight box will exist for. Defaults to existing forever. |
The amount of time in ticks that the highlight box will exist for. Defaults to existing forever. |
speech-bubble
text | :: LocalisedString |
|
lifetime | :: uint? |
|
simple-entity-with-owner
render_player_index | :: uint? |
|
simple-entity-with-force
render_player_index | :: uint? |
|
→ LuaEntity? |
The created entity or |
script_raised_built? instantly |
Raised if the |
|
Creates a filter inserter with circuit conditions and a filter
|
Creates a requester chest already set to request 128 iron plates.
|
|
Creates a basic inserter at the player's location facing north
|
name | :: string |
The smoke prototype name to create. |
The smoke prototype name to create. |
||
position | :: MapPosition |
Where to create the smoke. |
Where to create the smoke. |
Creates a particle at the given location
name | :: string |
The particle name. |
The particle name. |
||
position | :: MapPosition |
Where to create the particle. |
Where to create the particle. |
||
movement | :: Vector |
|
height | :: float |
|
vertical_speed | :: float |
|
frame_speed | :: float |
|
Create a new unit group at a given position.
position | :: MapPosition |
Initial position of the new unit group. |
Initial position of the new unit group. |
||
force | :: ForceIdentification? |
Force of the new unit group. Defaults to |
Force of the new unit group. Defaults to |
on_unit_group_created instantly |
|
Send a group to build a new base.
position | :: MapPosition |
Location of the new base. |
Location of the new base. |
||
unit_count | :: uint |
Number of biters to send for the base-building task. |
Number of biters to send for the base-building task. |
||
force | :: ForceIdentification? |
Force the new base will belong to. Defaults to enemy. |
Force the new base will belong to. Defaults to enemy. |
The specified force must be AI-controlled; i.e. force.ai_controllable
must be true
.
Get the tile at a given position. An alternative call signature for this method is passing it a single TilePosition.
x | :: int |
|
y | :: int |
|
Non-integer values will result in them being rounded down.
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.
tiles | :: array[Tile] |
|
correct_tiles | :: boolean? |
If |
If |
||
remove_colliding_entities | :: boolean or string? |
|
|
||
remove_colliding_decoratives | :: boolean? |
|
|
||
raise_event | :: boolean? |
|
|
script_raised_set_tiles? instantly |
Raised if the |
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.
Spawn pollution at the given position.
source | :: MapPosition |
Where to spawn the pollution. |
Where to spawn the pollution. |
||
amount | :: double |
How much pollution to add. |
How much pollution to add. |
Get an iterator going over every chunk on this surface.
Is a given chunk generated?
position | :: ChunkPosition |
The chunk's position. |
The chunk's position. |
Request that the game's map generator generate chunks at the given position for the given radius on this surface.
position | :: MapPosition |
Where to generate the new chunks. |
Where to generate the new chunks. |
||
radius | :: uint |
The chunk radius from |
The chunk radius from |
Blocks and generates all chunks that have been requested using all available threads.
Set generated status of a chunk. Useful when copying chunks.
position | :: ChunkPosition |
The chunk's position. |
The chunk's position. |
||
status | :: defines.chunk_generated_status |
The chunk's new status. |
The chunk's new status. |
Find the logistic network that covers a given position.
position | :: MapPosition |
|
force | :: ForceIdentification |
Force the logistic network should belong to. |
Force the logistic network should belong to. |
→ LuaLogisticNetwork? |
The found network or |
Find the logistic network with a cell closest to a given position.
position | :: MapPosition |
|
force | :: ForceIdentification |
Force the logistic network should belong to. |
Force the logistic network should belong to. |
→ LuaLogisticNetwork? |
The found network or |
Finds all of the logistics networks whose construction area intersects with the given position.
position | :: MapPosition |
|
force | :: ForceIdentification |
Force the logistic networks should belong to. |
Force the logistic networks should belong to. |
Place a deconstruction request.
area | :: BoundingBox |
The area to mark for deconstruction. |
The area to mark for deconstruction. |
||
force | :: ForceIdentification |
The force whose bots should perform the deconstruction. |
The force whose bots should perform the deconstruction. |
||
player | :: PlayerIdentification? |
The player to set the last_user to if any. |
The player to set the last_user to if any. |
||
skip_fog_of_war | :: boolean? |
If chunks covered by fog-of-war are skipped. |
If chunks covered by fog-of-war are skipped. |
||
item | :: LuaItemStack? |
The deconstruction item to use if any. |
The deconstruction item to use if any. |
on_marked_for_deconstruction? instantly |
Raised for every entity that has been successfully marked for deconstruction. |
Cancel a deconstruction order.
area | :: BoundingBox |
The area to cancel deconstruction orders in. |
The area to cancel deconstruction orders in. |
||
force | :: ForceIdentification |
The force whose deconstruction orders to cancel. |
The force whose deconstruction orders to cancel. |
||
player | :: PlayerIdentification? |
The player to set the last_user to if any. |
The player to set the last_user to if any. |
||
skip_fog_of_war | :: boolean? |
If chunks covered by fog-of-war are skipped. |
If chunks covered by fog-of-war are skipped. |
||
item | :: LuaItemStack? |
The deconstruction item to use if any. |
The deconstruction item to use if any. |
on_cancelled_deconstruction? instantly |
Raised for every entity whose deconstruction has been successfully cancelled. |
Place an upgrade request.
area | :: BoundingBox |
The area to mark for upgrade. |
The area to mark for upgrade. |
||
force | :: ForceIdentification |
The force whose bots should perform the upgrade. |
The force whose bots should perform the upgrade. |
||
player | :: PlayerIdentification? |
The player to set the last_user to if any. |
The player to set the last_user to if any. |
||
skip_fog_of_war | :: boolean? |
If chunks covered by fog-of-war are skipped. |
If chunks covered by fog-of-war are skipped. |
||
item | :: LuaItemStack |
The upgrade item to use. |
The upgrade item to use. |
on_marked_for_upgrade? instantly |
Raised for every entity that has been successfully marked for upgrade. |
Cancel a upgrade order.
area | :: BoundingBox |
The area to cancel upgrade orders in. |
The area to cancel upgrade orders in. |
||
force | :: ForceIdentification |
The force whose upgrade orders to cancel. |
The force whose upgrade orders to cancel. |
||
player | :: PlayerIdentification? |
The player to set the last_user to if any. |
The player to set the last_user to if any. |
||
skip_fog_of_war | :: boolean? |
If chunks covered by fog-of-war are skipped. |
If chunks covered by fog-of-war are skipped. |
||
item | :: LuaItemStack? |
The upgrade item to use if any. |
The upgrade item to use if any. |
on_cancelled_upgrade? instantly |
Raised for every entity whose upgrade has been successfully cancelled. |
Gets all tiles of the given types that are connected horizontally or vertically to the given tile position including the given tile position.
position | :: TilePosition |
The tile position to start at. |
The tile position to start at. |
||
tiles | :: array[string] |
The tiles to search for. |
The tiles to search for. |
||
include_diagonal | :: boolean? |
Include tiles that are connected diagonally. |
Include tiles that are connected diagonally. |
||
area | :: BoundingBox? |
The area to find connected tiles in. If provided the start position must be in this area. |
The area to find connected tiles in. If provided the start position must be in this area. |
→ array[TilePosition] |
The resulting set of tiles. |
This won't find tiles in non-generated chunks.
position | :: ChunkPosition |
The chunk position to delete |
The chunk position to delete |
on_pre_chunk_deleted future_tick |
|
on_chunk_deleted future_tick |
|
Regenerate autoplacement of some entities on this surface. This can be used to autoplace newly-added entities.
entities | :: string or array[string]? |
Prototype names of entity or entities to autoplace. When |
Prototype names of entity or entities to autoplace. When |
||
chunks | :: array[ChunkPosition]? |
The chunk positions to regenerate the entities on. If not given all chunks are regenerated. Note chunks with status < entities are ignored. |
The chunk positions to regenerate the entities on. If not given all chunks are regenerated. Note chunks with status < entities are ignored. |
All specified entity prototypes must be autoplacable. If nothing is given all entities are generated on all chunks.
Regenerate autoplacement of some decoratives on this surface. This can be used to autoplace newly-added decoratives.
decoratives | :: string or array[string]? |
Prototype names of decorative or decoratives to autoplace. When |
Prototype names of decorative or decoratives to autoplace. When |
||
chunks | :: array[ChunkPosition]? |
The chunk positions to regenerate the entities on. If not given all chunks are regenerated. Note chunks with status < entities are ignored. |
The chunk positions to regenerate the entities on. If not given all chunks are regenerated. Note chunks with status < entities are ignored. |
All specified decorative prototypes must be autoplacable. If nothing is given all decoratives are generated on all chunks.
Print text to the chat console of all players on this surface.
message | :: LocalisedString |
|
color | :: Color? |
|
Messages that are identical to a message sent in the last 60 ticks are not printed again.
Removes all decoratives from the given area. If no area and no position are given, then the entire surface is searched.
area | :: BoundingBox? |
|
position | :: TilePosition? |
|
name | :: string or array[string] or LuaDecorativePrototype or array[LuaDecorativePrototype]? |
|
collision_mask | :: CollisionMaskLayer or array[CollisionMaskLayer]? |
|
from_layer | :: string? |
|
to_layer | :: string? |
|
exclude_soft | :: boolean? |
Soft decoratives can be drawn over rails. |
Soft decoratives can be drawn over rails. |
||
limit | :: uint? |
|
invert | :: boolean? |
If the filters should be inverted. |
If the filters should be inverted. |
Adds the given decoratives to the surface.
check_collision | :: boolean? |
If collision should be checked against entities/tiles. |
If collision should be checked against entities/tiles. |
||
decoratives | :: array[Decorative] |
|
This will merge decoratives of the same type that already exist effectively increasing the "amount" field.
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.
area | :: BoundingBox? |
|
position | :: TilePosition? |
|
name | :: string or array[string] or LuaDecorativePrototype or array[LuaDecorativePrototype]? |
|
collision_mask | :: CollisionMaskLayer or array[CollisionMaskLayer]? |
|
from_layer | :: string? |
|
to_layer | :: string? |
|
exclude_soft | :: boolean? |
Soft decoratives can be drawn over rails. |
Soft decoratives can be drawn over rails. |
||
limit | :: uint? |
|
invert | :: boolean? |
If the filters should be inverted. |
If the filters should be inverted. |
|
force | :: ForceIdentification? |
The force to search. Not providing a force will match trains in any force. |
The force to search. Not providing a force will match trains in any force. |
Play a sound for every player on this surface.
path | :: SoundPath |
The sound to play. |
The sound to play. |
||
position | :: MapPosition? |
Where the sound should be played. If not given, it's played at the current position of each player. |
Where the sound should be played. If not given, it's played at the current position of each player. |
||
volume_modifier | :: double? |
The volume of the sound to play. Must be between 0 and 1 inclusive. |
The volume of the sound to play. Must be between 0 and 1 inclusive. |
||
override_sound_type | :: SoundType? |
The volume mixer to play the sound through. Defaults to the default mixer for the given sound type. |
The volume mixer to play the sound through. Defaults to the default mixer for the given sound type. |
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.
source_area | :: BoundingBox |
|
destination_area | :: BoundingBox |
|
destination_surface | :: SurfaceIdentification? |
|
destination_force | :: LuaForce or string? |
|
clone_tiles | :: boolean? |
If tiles should be cloned |
If tiles should be cloned |
||
clone_entities | :: boolean? |
If entities should be cloned |
If entities should be cloned |
||
clone_decoratives | :: boolean? |
If decoratives should be cloned |
If decoratives should be cloned |
||
clear_destination_entities | :: boolean? |
If the destination entities should be cleared |
If the destination entities should be cleared |
||
clear_destination_decoratives | :: boolean? |
If the destination decoratives should be cleared |
If the destination decoratives should be cleared |
||
expand_map | :: boolean? |
If the destination surface should be expanded when destination_area is outside current bounds. Default false. |
If the destination surface should be expanded when destination_area is outside current bounds. Default false. |
||
create_build_effect_smoke | :: boolean? |
If true, the building effect smoke will be shown around the new entities. |
If true, the building effect smoke will be shown around the new entities. |
on_entity_cloned instantly |
Raised for every entity that was cloned. |
on_area_cloned instantly |
Raised after the individual |
Entities are cloned in an order such that they can always be created, eg rails before trains.
Clones the given area.
source_offset | :: TilePosition |
|
destination_offset | :: TilePosition |
|
source_positions | :: array[TilePosition] |
|
destination_surface | :: SurfaceIdentification? |
|
destination_force | :: LuaForce or string? |
|
clone_tiles | :: boolean? |
If tiles should be cloned |
If tiles should be cloned |
||
clone_entities | :: boolean? |
If entities should be cloned |
If entities should be cloned |
||
clone_decoratives | :: boolean? |
If decoratives should be cloned |
If decoratives should be cloned |
||
clear_destination_entities | :: boolean? |
If the destination entities should be cleared |
If the destination entities should be cleared |
||
clear_destination_decoratives | :: boolean? |
If the destination decoratives should be cleared |
If the destination decoratives should be cleared |
||
expand_map | :: boolean? |
If the destination surface should be expanded when destination_area is outside current bounds. Default false. |
If the destination surface should be expanded when destination_area is outside current bounds. Default false. |
||
manual_collision_mode | :: boolean? |
If manual-style collision checks should be done. |
If manual-style collision checks should be done. |
||
create_build_effect_smoke | :: boolean? |
If true, the building effect smoke will be shown around the new entities. |
If true, the building effect smoke will be shown around the new entities. |
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.
Clones the given entities.
entities | :: array[LuaEntity] |
|
destination_offset | :: Vector |
|
destination_surface | :: SurfaceIdentification? |
|
destination_force | :: ForceIdentification? |
|
snap_to_grid | :: boolean? |
|
create_build_effect_smoke | :: boolean? |
If true, the building effect smoke will be shown around the new entities. |
If true, the building effect smoke will be shown around the new entities. |
on_entity_cloned instantly |
Raised for every entity that was cloned. |
Entities are cloned in an order such that they can always be created, eg rails before trains.
Clears this surface deleting all entities and chunks on it.
ignore_characters | :: boolean? |
Whether characters on this surface that are connected to or associated with players should be ignored (not destroyed). |
Whether characters on this surface that are connected to or associated with players should be ignored (not destroyed). |
on_pre_surface_cleared future_tick |
|
on_surface_cleared future_tick |
|
Generates a path with the specified constraints (as an array of PathfinderWaypoints) using the unit pathfinding algorithm. This path can be used to emulate pathing behavior by script for non-unit entities, such as vehicles. If you want to command actual units (such as biters or spitters) to move, use LuaEntity::set_command instead.
The resulting path is ultimately returned asynchronously via on_script_path_request_finished.
bounding_box | :: BoundingBox |
The dimensions of the object that's supposed to travel the path. |
The dimensions of the object that's supposed to travel the path. |
||
collision_mask | :: CollisionMaskWithFlags or array[string] |
The list of masks the |
The list of masks the |
||
start | :: MapPosition |
The position from which to start pathfinding. |
The position from which to start pathfinding. |
||
goal | :: MapPosition |
The position to find a path to. |
The position to find a path to. |
||
force | :: ForceIdentification |
The force for which to generate the path, determining which gates can be opened for example. |
The force for which to generate the path, determining which gates can be opened for example. |
||
radius | :: double? |
How close the pathfinder needs to get to its |
How close the pathfinder needs to get to its |
||
pathfind_flags | :: PathfinderFlags? |
Flags that affect pathfinder behavior. |
Flags that affect pathfinder behavior. |
||
can_open_gates | :: boolean? |
Whether the path request can open gates. Defaults to |
Whether the path request can open gates. Defaults to |
||
path_resolution_modifier | :: int? |
Defines how coarse the pathfinder's grid is, where smaller values mean a coarser grid. Defaults to |
Defines how coarse the pathfinder's grid is, where smaller values mean a coarser grid. Defaults to |
||
entity_to_ignore | :: LuaEntity? |
Makes the pathfinder ignore collisions with this entity if it is given. |
Makes the pathfinder ignore collisions with this entity if it is given. |
→ uint |
A unique handle to identify this call when on_script_path_request_finished fires. |
on_script_path_request_finished future_tick |
|
Gets the script areas that match the given name or if no name is given all areas are returned.
name | :: string? |
|
Sets the given script area to the new values.
id | :: uint |
The area to edit. |
The area to edit. |
||
area | :: ScriptArea |
|
Adds the given script area.
area | :: ScriptArea |
|
→ uint |
The id of the created area. |
Gets the script positions that match the given name or if no name is given all positions are returned.
name | :: string? |
|
Sets the given script position to the new values.
id | :: uint |
The position to edit. |
The position to edit. |
||
area | :: ScriptPosition |
|
Adds the given script position.
area | :: ScriptPosition |
|
→ uint |
The id of the created position. |
Gets the map exchange string for the current map generation settings of this surface.
Gets the starting area radius of this surface.
Gets the closest entity in the list to this position.
position | :: MapPosition |
|
entities | :: array[LuaEntity] |
The Entities to check |
The Entities to check |
Gets train stops matching the given filters.
name | :: string or array[string]? |
The name(s) of the train stops. Not providing names will match any stop. |
The name(s) of the train stops. Not providing names will match any stop. |
||
force | :: ForceIdentification? |
The force to search. Not providing a force will match stops in any force. |
The force to search. Not providing a force will match stops in any force. |
Gets the total amount of pollution on the surface by iterating over all of the chunks containing pollution.
Whether the given entity prototype collides at the given position and direction.
prototype | :: EntityPrototypeIdentification |
The entity prototype to check |
The entity prototype to check |
||
position | :: MapPosition |
The position to check |
The position to check |
||
use_map_generation_bounding_box | :: boolean |
If the map generation bounding box should be used instead of the collision bounding box |
If the map generation bounding box should be used instead of the collision bounding box |
||
direction | :: defines.direction? |
|
Whether the given decorative prototype collides at the given position and direction.
prototype | :: string |
The decorative prototype to check |
The decorative prototype to check |
||
position | :: MapPosition |
The position to check |
The position to check |
property_names | :: array[string] |
Names of properties (e.g. "elevation") to calculate |
Names of properties (e.g. "elevation") to calculate |
||
positions | :: array[MapPosition] |
Positions for which to calculate property values |
Positions for which to calculate property values |
→ dictionary[string → array[double]] |
Table of property value lists, keyed by property name |
Returns all the military targets (entities with force) on this chunk for the given force.
position | :: ChunkPosition |
The chunk's position. |
The chunk's position. |
||
force | :: LuaForce or string |
Entities of this force will be returned. |
Entities of this force will be returned. |
Sets the given area to the checkerboard lab tiles.
area | :: BoundingBox |
The tile area. |
The tile area. |
All methods and properties that this object supports.
The name of this surface. Names are unique among surfaces.
on_surface_renamed instantly |
|
the default surface can't be renamed.
This surface's index in LuaGameScript::surfaces (unique ID). It is assigned when a surface is created, and remains so until it is deleted. Indexes of deleted surfaces can be reused.
The generation settings for this surface. These can be modified after surface generation, but note that this will not retroactively update the surface. To manually regenerate it, LuaSurface::regenerate_entity, LuaSurface::regenerate_decorative, and LuaSurface::delete_chunk can be used.
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, as a number in range [0, 1].
Current wind speed in tiles per tick.
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.
Solar equipment is still limited to its maximum power output.
The minimal brightness during the night. Defaults to 0.15
. This has an effect on both rendering and game mechanics such as biter spawns and solar power.
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.
Makes night on the surface pitch black, assuming LuaSurface::min_brightness being set to default value
|
If clouds are shown on this surface.
If false, clouds are never shown. If true the player must also have clouds enabled in graphics settings for them to be shown.
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.
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.