LuaSurface

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

Attributes

name

• Read: string
• Write: string
• Optional: false

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

The default surface can't be renamed.

index

• Read: uint32
• Write: unknown
• Optional: false

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

map_gen_settings

• Read: MapGenSettings
• Write: MapGenSettings
• Optional: false

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

generate_with_lab_tiles

• Read: boolean
• Write: boolean
• Optional: false

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

always_day

• Read: boolean
• Write: boolean
• Optional: false

When set to true, the sun will always shine.

daytime

• Read: double
• Write: double
• Optional: false

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

darkness

• Read: float
• Write: unknown
• Optional: false

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

wind_speed

• Read: double
• Write: double
• Optional: false

Current wind speed in tiles per tick.

wind_orientation

• Read: RealOrientation
• Write: RealOrientation
• Optional: false

Current wind direction.

wind_orientation_change

• Read: double
• Write: double
• Optional: false

Change in wind orientation per tick.

peaceful_mode

• Read: boolean
• Write: boolean
• Optional: false

Is peaceful mode enabled on this surface?

no_enemies_mode

• Read: boolean
• Write: boolean
• Optional: false

Is no-enemies mode enabled on this surface?

freeze_daytime

• Read: boolean
• Write: boolean
• Optional: false

True if daytime is currently frozen.

ticks_per_day

• Read: uint32
• Write: uint32
• Optional: false

The number of ticks per day for this surface.

dusk

• Read: double
• Write: double
• Optional: false

The daytime when dusk starts.

dawn

• Read: double
• Write: double
• Optional: false

The daytime when dawn starts.

evening

• Read: double
• Write: double
• Optional: false

The daytime when evening starts.

morning

• Read: double
• Write: double
• Optional: false

The daytime when morning starts.

daytime_parameters

• Read: { dawn: double, dusk: double, evening: double, morning: double }
• Write: { dawn: double, dusk: double, evening: double, morning: double }
• Optional: false

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

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

solar_power_multiplier

• Read: double
• Write: double
• Optional: false

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

min_brightness

• Read: double
• Write: double
• Optional: false

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

brightness_visual_weights

• Read: ColorModifier
• Write: ColorModifier
• Optional: false

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.

show_clouds

• Read: boolean
• Write: boolean
• Optional: false

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.

has_global_electric_network

• Read: boolean
• Write: unknown
• Optional: false

Whether this surface currently has a global electric network.

platform

• Read: LuaSpacePlatform
• Write: unknown
• Optional: true

planet

• Read: LuaPlanet
• Write: unknown
• Optional: true

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

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

deletable

• Read: boolean
• Write: unknown
• Optional: false

If this surface can be deleted.

global_effect

• Read: ModuleEffects
• Write: ModuleEffects
• Optional: true

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

pollutant_type

• Read: LuaAirbornePollutantPrototype
• Write: unknown
• Optional: true

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

localised_name

• Read: LocalisedString
• Write: LocalisedString
• Optional: true

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

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

ignore_surface_conditions

• Read: boolean
• Write: boolean
• Optional: false

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

pollution_statistics

• Read: LuaFlowStatistics
• Write: unknown
• Optional: false

The pollution statistics for this surface.

global_electric_network_statistics

• Read: LuaFlowStatistics
• Write: unknown
• Optional: true

The global electric network statistics for this surface.

valid

• Read: boolean
• Write: unknown
• Optional: false

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

object_name

• Read: string
• Write: unknown
• Optional: false

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.

Methods

get_pollution

LuaSurface.get_pollution(position: MapPosition) -> double

Call As

surface.get_pollution(position)

Call Convention

• takes_table: false
• table_optional: false

Get the pollution for a given position.

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

Parameters

• position: MapPosition — The position to poll the chunk's pollution

Returns

• double

set_pollution

LuaSurface.set_pollution(position: MapPosition, amount: double)

Call As

surface.set_pollution(position, amount)

Call Convention

• takes_table: false
• table_optional: false

Set the pollution for a given position.

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

Parameters

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

can_place_entity

LuaSurface.can_place_entity{ name: EntityID, position: MapPosition, direction?: defines.direction, force?: ForceID, build_check_type?: defines.build_check_type, forced?: boolean, inner_name?: string } -> boolean

Call As

surface.can_place_entity{ name="name", position=position }

Call Convention

• takes_table: true
• table_optional: false

Check for collisions with terrain or other entities.

Parameters

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

Returns

• boolean

can_fast_replace

LuaSurface.can_fast_replace{ name: EntityID, position: MapPosition, direction?: defines.direction, force?: ForceID } -> boolean

Call As

surface.can_fast_replace{ name="name", position=position }

Call Convention

• takes_table: true
• table_optional: false

If there exists an entity at the given location that can be fast-replaced with the given entity parameters.

Parameters

• name: EntityID — Name of the entity to check.
• position: MapPosition — Where the entity would be placed.
• direction?: defines.direction — Direction the entity would be placed. Defaults to north.
• force?: ForceID — The force that would place the entity. Defaults to the "neutral" force.

Returns

• boolean

find_entity

LuaSurface.find_entity(entity: EntityWithQualityID, position: MapPosition) -> LuaEntity?

Call As

surface.find_entity(entity, position)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

Returns

• LuaEntity? — nil if no such entity is found.

find_entities

LuaSurface.find_entities(area?: BoundingBox) -> Array<LuaEntity>

Call As

surface.find_entities()

Call Convention

• takes_table: false
• table_optional: false

Find entities in a given area.

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

Parameters

• area?: BoundingBox

Returns

• Array<LuaEntity>

find_entities_filtered

LuaSurface.find_entities_filtered(filter: EntitySearchFilters) -> Array<LuaEntity>

Call As

surface.find_entities_filtered(filter)

Call Convention

• takes_table: false
• table_optional: false

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

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

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

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

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

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

Parameters

• filter: EntitySearchFilters

Returns

• Array<LuaEntity>

find_tiles_filtered

LuaSurface.find_tiles_filtered(filter: TileSearchFilters) -> Array<LuaTile>

Call As

surface.find_tiles_filtered(filter)

Call Convention

• takes_table: false
• table_optional: false

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

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

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

Parameters

• filter: TileSearchFilters

Returns

• Array<LuaTile>

count_entities_filtered

LuaSurface.count_entities_filtered(filter: EntitySearchFilters) -> uint32

Call As

surface.count_entities_filtered(filter)

Call Convention

• takes_table: false
• table_optional: false

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

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

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

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

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

Parameters

• filter: EntitySearchFilters

Returns

• uint32

count_tiles_filtered

LuaSurface.count_tiles_filtered(filter: TileSearchFilters) -> uint32

Call As

surface.count_tiles_filtered(filter)

Call Convention

• takes_table: false
• table_optional: false

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

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

Parameters

• filter: TileSearchFilters

Returns

• uint32

find_non_colliding_position

LuaSurface.find_non_colliding_position(name: EntityID, center: MapPosition, radius: double, precision: double, force_to_tile_center?: boolean) -> MapPosition?

Call As

surface.find_non_colliding_position("name", center, radius, precision)

Call Convention

• takes_table: false
• table_optional: false

Find a non-colliding position within a given radius.

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

Parameters

• name: EntityID — Prototype name of the entity to find a position for. (The bounding box for the collision checking is taken from this prototype.)
• center: MapPosition — Center of the search area.
• radius: double — Max distance from center to search in. A radius of 0 means an infinitely-large search area.
• precision: double — The step length from the given position as it searches, in tiles. Minimum value is 0.01.
• force_to_tile_center?: boolean — Will only check tile centers. This can be useful when your intent is to place a building at the resulting position, as they must generally be placed at tile centers. Defaults to false.

Returns

• MapPosition? — The non-colliding position. May be nil if no suitable position was found.

find_non_colliding_position_in_box

LuaSurface.find_non_colliding_position_in_box(name: EntityID, search_space: BoundingBox, precision: double, force_to_tile_center?: boolean) -> MapPosition?

Call As

surface.find_non_colliding_position_in_box("name", search_space, precision)

Call Convention

• takes_table: false
• table_optional: false

Find a non-colliding position within a given rectangle.

Parameters

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

Returns

• MapPosition? — The non-colliding position. May be nil if no suitable position was found.

spill_item_stack

LuaSurface.spill_item_stack{ position: MapPosition, stack: ItemStackIdentification, enable_looted?: boolean, force?: ForceID, allow_belts?: boolean, max_radius?: double, use_start_position_on_failure?: boolean, drop_full_stack?: boolean } -> Array<LuaEntity>

Call As

surface.spill_item_stack{ position=position, stack=stack }

Call Convention

• takes_table: true
• table_optional: false

Spill items on the ground centered at a given location.

Parameters

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

Returns

• Array<LuaEntity> — The created item-on-ground entities.

spill_inventory

LuaSurface.spill_inventory{ position: MapPosition, inventory: LuaInventory, enable_looted?: boolean, force?: ForceID, allow_belts?: boolean, max_radius?: double, use_start_position_on_failure?: boolean, drop_full_stack?: boolean } -> Array<LuaEntity>

Call As

surface.spill_inventory{ position=position, inventory=inventory }

Call Convention

• takes_table: true
• table_optional: false

Spill inventory on the ground centered at a given location.

Parameters

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

Returns

• Array<LuaEntity> — The created item-on-ground entities.

find_enemy_units

LuaSurface.find_enemy_units(center: MapPosition, radius: double, force?: ForceID) -> Array<LuaEntity>

Call As

surface.find_enemy_units(center, radius, force)

Call Convention

• takes_table: false
• table_optional: false

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

This is more efficient than LuaSurface::find_entities.

Parameters

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

Returns

• Array<LuaEntity>

find_units

LuaSurface.find_units{ area: BoundingBox, force: ForceID, condition: ForceCondition } -> Array<LuaEntity>

Call As

surface.find_units{ area=area, force=force, condition=condition }

Call Convention

• takes_table: true
• table_optional: false

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

This is more efficient than LuaSurface::find_entities.

Parameters

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

Returns

• Array<LuaEntity>

find_nearest_enemy

LuaSurface.find_nearest_enemy{ position: MapPosition, max_distance: double, force?: ForceID } -> LuaEntity?

Call As

surface.find_nearest_enemy{ position=position, max_distance=max_distance }

Call Convention

• takes_table: true
• table_optional: false

Find the enemy military target (military entity) closest to the given position.

Parameters

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

Returns

• LuaEntity? — The nearest enemy military target or nil if no enemy could be found within the given area.

find_nearest_enemy_entity_with_owner

LuaSurface.find_nearest_enemy_entity_with_owner{ position: MapPosition, max_distance: double, force?: ForceID } -> LuaEntity

Call As

surface.find_nearest_enemy_entity_with_owner{ position=position, max_distance=max_distance }

Call Convention

• takes_table: true
• table_optional: false

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

Parameters

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

Returns

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

set_multi_command

LuaSurface.set_multi_command{ command: Command, unit_count: uint32, force?: ForceID, unit_search_distance?: uint32 } -> uint32

Call As

surface.set_multi_command{ command=command, unit_count=unit_count }

Call Convention

• takes_table: true
• table_optional: false

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

Parameters

• command: Command
• unit_count: uint32 — Number of units to give the command to.
• force?: ForceID — Force of the units this command is to be given to. If not specified, uses the enemy force.
• unit_search_distance?: uint32 — Radius to search for units. The search area is centered on the destination of the command. If not specified uses default value of 150.

Returns

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

create_entity

LuaSurface.create_entity{ name: EntityID, position: MapPosition, direction?: defines.direction, mirror?: boolean, quality?: QualityID, force?: ForceID, target?: LuaEntity | MapPosition, source?: LuaEntity | MapPosition, cause?: LuaEntity | ForceID, snap_to_grid?: boolean, fast_replace?: boolean, undo_index?: uint32, player?: PlayerIdentification, character?: LuaEntity, spill?: boolean, raise_built?: boolean, create_build_effect_smoke?: boolean, spawn_decorations?: boolean, move_stuck_players?: boolean, item?: LuaItemStack, preserve_ghosts_and_corpses?: boolean, register_plant?: boolean, burner_fuel_inventory?: BlueprintInventoryWithFilters } -> LuaEntity?

Call As

surface.create_entity{ name="name", position=position }

Call Convention

• takes_table: true
• table_optional: false

Create an entity on this surface.

Parameters

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

Returns

• LuaEntity? — The created entity or nil if the creation failed.

create_segmented_unit

LuaSurface.create_segmented_unit{ name: EntityID, quality?: QualityID, force?: ForceID, territory?: LuaTerritory } -> LuaSegmentedUnit?

Call As

surface.create_segmented_unit{ name="name" }

Call Convention

• takes_table: true
• table_optional: false

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

Parameters

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

Returns

• LuaSegmentedUnit? — The created segmented unit or nil if the creation failed or the unit was destroyed during creation.

create_territory

LuaSurface.create_territory{ chunks: Array<ChunkPosition>, patrol_path?: Array<MapPosition> } -> LuaTerritory?

Call As

surface.create_territory{ chunks=chunks }

Call Convention

• takes_table: true
• table_optional: false

Create a territory on the surface.

Parameters

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

Returns

• LuaTerritory? — The created territory or nil if the creation failed or the territory was destroyed during creation.

create_trivial_smoke

LuaSurface.create_trivial_smoke{ name: TrivialSmokeID, position: MapPosition }

Call As

surface.create_trivial_smoke{ name="name", position=position }

Call Convention

• takes_table: true
• table_optional: false

Parameters

• name: TrivialSmokeID — The smoke prototype name to create.
• position: MapPosition — Where to create the smoke.

create_particle

LuaSurface.create_particle{ name: ParticleID, position: MapPosition, movement: Vector, height: float, vertical_speed: float, frame_speed: float }

Call As

surface.create_particle{ name="name", position=position, movement=movement, height=height, vertical_speed=vertical_speed, frame_speed=frame_speed }

Call Convention

• takes_table: true
• table_optional: false

Creates a particle at the given location

Parameters

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

create_unit_group

LuaSurface.create_unit_group{ position: MapPosition, force?: ForceID } -> LuaCommandable

Call As

surface.create_unit_group{ position=position }

Call Convention

• takes_table: true
• table_optional: false

Create a new unit group at a given position.

Parameters

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

Returns

• LuaCommandable

build_enemy_base

LuaSurface.build_enemy_base(position: MapPosition, unit_count: uint32, force?: ForceID)

Call As

surface.build_enemy_base(position, unit_count, force)

Call Convention

• takes_table: false
• table_optional: false

Send a group to build a new base.

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

Parameters

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

get_tile

LuaSurface.get_tile(x: int32, y: int32) -> LuaTile

Call As

surface.get_tile(x, y)

Call Convention

• takes_table: false
• table_optional: false

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

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

Parameters

• x: int32
• y: int32

Returns

• LuaTile

set_tiles

LuaSurface.set_tiles(tiles: Array<Tile>, correct_tiles?: boolean, remove_colliding_entities?: boolean | "abort_on_collision", remove_colliding_decoratives?: boolean, raise_event?: boolean, player?: PlayerIdentification, undo_index?: uint32)

Call As

surface.set_tiles(tiles, true)

Call Convention

• takes_table: false
• table_optional: false

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

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

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

Parameters

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

pollute

LuaSurface.pollute(source: MapPosition, amount: double, prototype?: EntityID)

Call As

surface.pollute(source, amount, prototype)

Call Convention

• takes_table: false
• table_optional: false

Spawn pollution at the given position.

Parameters

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

get_chunks

LuaSurface.get_chunks() -> LuaChunkIterator

Call As

surface.get_chunks()

Call Convention

• takes_table: false
• table_optional: false

Get an iterator going over every chunk on this surface.

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

Returns

• LuaChunkIterator

is_chunk_generated

LuaSurface.is_chunk_generated(chunk_position: ChunkPosition) -> boolean

Call As

surface.is_chunk_generated(chunk_position)

Call Convention

• takes_table: false
• table_optional: false

Is a given chunk generated?

Parameters

• chunk_position: ChunkPosition — The chunk's position.

Returns

• boolean

request_to_generate_chunks

LuaSurface.request_to_generate_chunks(position: MapPosition, radius?: uint32)

Call As

surface.request_to_generate_chunks(position, radius)

Call Convention

• takes_table: false
• table_optional: false

Request that the game's map generator generate chunks at the given position for the given radius on this surface. If the radius is 0, then only the chunk at the given position is generated.

Parameters

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

force_generate_chunk_requests

LuaSurface.force_generate_chunk_requests()

Call As

surface.force_generate_chunk_requests()

Call Convention

• takes_table: false
• table_optional: false

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

set_chunk_generated_status

LuaSurface.set_chunk_generated_status(chunk_position: ChunkPosition, status: defines.chunk_generated_status)

Call As

surface.set_chunk_generated_status(chunk_position, status)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

get_territories

LuaSurface.get_territories() -> Array<LuaTerritory>

Call As

surface.get_territories()

Call Convention

• takes_table: false
• table_optional: false

Get all territories on the surface.

Returns

• Array<LuaTerritory>

get_territory_for_chunk

LuaSurface.get_territory_for_chunk(chunk_position: ChunkPosition) -> LuaTerritory?

Call As

surface.get_territory_for_chunk(chunk_position)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

Returns

• LuaTerritory?

set_territory_for_chunks

LuaSurface.set_territory_for_chunks(chunk_positions: Array<ChunkPosition>, territory?: LuaTerritory)

Call As

surface.set_territory_for_chunks(chunk_positions, territory)

Call Convention

• takes_table: false
• table_optional: false

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

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

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

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

Parameters

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

clear_territory_for_chunks

LuaSurface.clear_territory_for_chunks(chunk_positions: Array<ChunkPosition>)

Call As

surface.clear_territory_for_chunks(chunk_positions)

Call Convention

• takes_table: false
• table_optional: false

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

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

Parameters

• chunk_positions: Array<ChunkPosition> — The chunk positions. The chunks at these positions does not need to exist.

get_segmented_units

LuaSurface.get_segmented_units() -> Array<LuaSegmentedUnit>

Call As

surface.get_segmented_units()

Call Convention

• takes_table: false
• table_optional: false

Get all segmented units that exist on the surface.

Returns

• Array<LuaSegmentedUnit>

find_logistic_network_by_position

LuaSurface.find_logistic_network_by_position(position: MapPosition, force: ForceID) -> LuaLogisticNetwork?

Call As

surface.find_logistic_network_by_position(position, force)

Call Convention

• takes_table: false
• table_optional: false

Find the logistic network that covers a given position.

Parameters

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

Returns

• LuaLogisticNetwork? — The found network or nil if no such network was found.

find_closest_logistic_network_by_position

LuaSurface.find_closest_logistic_network_by_position(position: MapPosition, force: ForceID) -> LuaLogisticNetwork?

Call As

surface.find_closest_logistic_network_by_position(position, force)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

Returns

• LuaLogisticNetwork? — The found network or nil if no such network was found.

find_logistic_networks_by_construction_area

LuaSurface.find_logistic_networks_by_construction_area(position: MapPosition, force: ForceID) -> Array<LuaLogisticNetwork>

Call As

surface.find_logistic_networks_by_construction_area(position, force)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

Returns

• Array<LuaLogisticNetwork>

deconstruct_area

LuaSurface.deconstruct_area{ area: BoundingBox, force: ForceID, player?: PlayerIdentification, skip_fog_of_war?: boolean, item?: LuaItemStack, super_forced?: boolean }

Call As

surface.deconstruct_area{ area=area, force=force }

Call Convention

• takes_table: true
• table_optional: false

Place a deconstruction request.

Parameters

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

cancel_deconstruct_area

LuaSurface.cancel_deconstruct_area{ area: BoundingBox, force: ForceID, player?: PlayerIdentification, skip_fog_of_war?: boolean, item?: LuaItemStack, undo_index?: uint32, super_forced?: boolean }

Call As

surface.cancel_deconstruct_area{ area=area, force=force }

Call Convention

• takes_table: true
• table_optional: false

Cancel a deconstruction order.

Parameters

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

upgrade_area

LuaSurface.upgrade_area{ area: BoundingBox, force: ForceID, player?: PlayerIdentification, skip_fog_of_war?: boolean, item: LuaItemStack }

Call As

surface.upgrade_area{ area=area, force=force, item=item }

Call Convention

• takes_table: true
• table_optional: false

Place an upgrade request.

Parameters

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

cancel_upgrade_area

LuaSurface.cancel_upgrade_area{ area: BoundingBox, force: ForceID, player?: PlayerIdentification, skip_fog_of_war?: boolean, item: LuaItemStack }

Call As

surface.cancel_upgrade_area{ area=area, force=force, item=item }

Call Convention

• takes_table: true
• table_optional: false

Cancel a upgrade order.

Parameters

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

get_hidden_tile

LuaSurface.get_hidden_tile(position: TilePosition) -> string?

Call As

surface.get_hidden_tile(position)

Call Convention

• takes_table: false
• table_optional: false

The hidden tile name.

Parameters

• position: TilePosition — The tile position.

Returns

• string? — nil if there isn't one for the given position.

get_double_hidden_tile

LuaSurface.get_double_hidden_tile(position: TilePosition) -> string

Call As

surface.get_double_hidden_tile(position)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• position: TilePosition — The tile position.

Returns

• string

set_hidden_tile

LuaSurface.set_hidden_tile(position: TilePosition, tile?: TileID)

Call As

surface.set_hidden_tile(position, tile)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• position: TilePosition — The tile position.
• tile?: TileID — The new hidden tile or nil to clear the hidden tile.

set_double_hidden_tile

LuaSurface.set_double_hidden_tile(position: TilePosition, tile?: TileID)

Call As

surface.set_double_hidden_tile(position, tile)

Call Convention

• takes_table: false
• table_optional: false

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

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

Parameters

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

get_connected_tiles

LuaSurface.get_connected_tiles(position: TilePosition, tiles: Array<TileID>, include_diagonal?: boolean, area?: BoundingBox) -> Array<TilePosition>

Call As

surface.get_connected_tiles(position, tiles, true)

Call Convention

• takes_table: false
• table_optional: false

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

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

Parameters

• position: TilePosition — The tile position to start at.
• tiles: Array<TileID> — The tiles to search for.
• include_diagonal?: boolean — 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.

Returns

• Array<TilePosition> — The resulting set of tiles.

delete_chunk

LuaSurface.delete_chunk(chunk_position: ChunkPosition)

Call As

surface.delete_chunk(chunk_position)

Call Convention

• takes_table: false
• table_optional: false

Parameters

• chunk_position: ChunkPosition — The chunk position to delete

regenerate_entity

LuaSurface.regenerate_entity(entities?: string | Array<string>, chunks?: Array<ChunkPosition>)

Call As

surface.regenerate_entity()

Call Convention

• takes_table: false
• table_optional: false

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

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

Parameters

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

regenerate_decorative

LuaSurface.regenerate_decorative(decoratives?: string | Array<string>, chunks?: Array<ChunkPosition>)

Call As

surface.regenerate_decorative()

Call Convention

• takes_table: false
• table_optional: false

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

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

Parameters

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

print

LuaSurface.print(message: LocalisedString, print_settings?: PrintSettings)

Call As

surface.print(message, print_settings)

Call Convention

• takes_table: false
• table_optional: false

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

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

Parameters

• message: LocalisedString
• print_settings?: PrintSettings

destroy_decoratives

LuaSurface.destroy_decoratives{ area?: BoundingBox, position?: TilePosition, name?: DecorativeID | Array<DecorativeID>, collision_mask?: CollisionLayerID | Array<CollisionLayerID> | Dict<CollisionLayerID, true>, from_layer?: string, to_layer?: string, exclude_soft?: boolean, limit?: uint32, invert?: boolean }

Call As

surface.destroy_decoratives{ area=area }

Call Convention

• takes_table: true
• table_optional: false

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

Parameters

• area?: BoundingBox
• position?: TilePosition
• name?: DecorativeID | Array<DecorativeID>
• collision_mask?: CollisionLayerID | Array<CollisionLayerID> | Dict<CollisionLayerID, true>
• from_layer?: string
• to_layer?: string
• exclude_soft?: boolean — Soft decoratives can be drawn over rails.
• limit?: uint32
• invert?: boolean — If the filters should be inverted.

create_decoratives

LuaSurface.create_decoratives{ check_collision?: boolean, decoratives: Array<Decorative> }

Call As

surface.create_decoratives{ decoratives=decoratives }

Call Convention

• takes_table: true
• table_optional: false

Adds the given decoratives to the surface.

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

Parameters

• check_collision?: boolean — If collision should be checked against entities/tiles.
• decoratives: Array<Decorative>

find_decoratives_filtered

LuaSurface.find_decoratives_filtered{ area?: BoundingBox, position?: TilePosition, name?: DecorativeID | Array<DecorativeID>, collision_mask?: CollisionLayerID | Array<CollisionLayerID> | Dict<CollisionLayerID, true>, from_layer?: string, to_layer?: string, exclude_soft?: boolean, limit?: uint32, invert?: boolean } -> Array<DecorativeResult>

Call As

surface.find_decoratives_filtered{ area=area }

Call Convention

• takes_table: true
• table_optional: false

Find decoratives of a given name in a given area.

If no filters are given, returns all decoratives in the search area. If multiple filters are specified, returns only decoratives matching every given filter. If no area and no position are given, the entire surface is searched.

Parameters

• area?: BoundingBox
• position?: TilePosition
• name?: DecorativeID | Array<DecorativeID>
• collision_mask?: CollisionLayerID | Array<CollisionLayerID> | Dict<CollisionLayerID, true>
• from_layer?: string
• to_layer?: string
• exclude_soft?: boolean — Soft decoratives can be drawn over rails.
• limit?: uint32
• invert?: boolean — If the filters should be inverted.

Returns

• Array<DecorativeResult>

clear_pollution

LuaSurface.clear_pollution()

Call As

surface.clear_pollution()

Call Convention

• takes_table: false
• table_optional: false

Clears all pollution on this surface.

play_sound

LuaSurface.play_sound(sound_specification: PlaySoundSpecification)

Call As

surface.play_sound(sound_specification)

Call Convention

• takes_table: false
• table_optional: false

Play a sound for every player on this surface.

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

Parameters

• sound_specification: PlaySoundSpecification — The sound to play.

get_resource_counts

LuaSurface.get_resource_counts() -> Dict<string, uint32>

Call As

surface.get_resource_counts()

Call Convention

• takes_table: false
• table_optional: false

Gets the resource amount of all resources on this surface

Returns

• Dict<string, uint32>

get_random_chunk

LuaSurface.get_random_chunk() -> ChunkPosition

Call As

surface.get_random_chunk()

Call Convention

• takes_table: false
• table_optional: false

Gets a random generated chunk position or 0,0 if no chunks have been generated on this surface.

Returns

• ChunkPosition

clone_area

LuaSurface.clone_area{ source_area: BoundingBox, destination_area: BoundingBox, destination_surface?: SurfaceIdentification, destination_force?: ForceID, clone_tiles?: boolean, clone_entities?: boolean, clone_decoratives?: boolean, clear_destination_entities?: boolean, clear_destination_decoratives?: boolean, expand_map?: boolean, create_build_effect_smoke?: boolean }

Call As

surface.clone_area{ source_area=source_area, destination_area=destination_area }

Call Convention

• takes_table: true
• table_optional: false

Clones the given area.

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

Parameters

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

clone_brush

LuaSurface.clone_brush{ source_offset: TilePosition, destination_offset: TilePosition, source_positions: Array<TilePosition>, destination_surface?: SurfaceIdentification, destination_force?: LuaForce | string, clone_tiles?: boolean, clone_entities?: boolean, clone_decoratives?: boolean, clear_destination_entities?: boolean, clear_destination_decoratives?: boolean, expand_map?: boolean, manual_collision_mode?: boolean, create_build_effect_smoke?: boolean }

Call As

surface.clone_brush{ source_offset=source_offset, destination_offset=destination_offset, source_positions=source_positions }

Call Convention

• takes_table: true
• table_optional: false

Clones the given area.

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

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

Parameters

• source_offset: TilePosition
• destination_offset: TilePosition
• source_positions: Array<TilePosition>
• destination_surface?: SurfaceIdentification
• destination_force?: LuaForce | string
• clone_tiles?: boolean — If tiles should be cloned
• clone_entities?: boolean — If entities should be cloned
• clone_decoratives?: boolean — If decoratives should be cloned
• clear_destination_entities?: boolean — If the destination entities should be cleared
• clear_destination_decoratives?: boolean — If the destination decoratives should be cleared
• expand_map?: boolean — If the destination surface should be expanded when destination_area is outside current bounds. Defaults to false.
• manual_collision_mode?: boolean — 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.

clone_entities

LuaSurface.clone_entities{ entities: Array<LuaEntity>, destination_offset: Vector, destination_surface?: SurfaceIdentification, destination_force?: ForceID, snap_to_grid?: boolean, create_build_effect_smoke?: boolean }

Call As

surface.clone_entities{ entities=entities, destination_offset=destination_offset }

Call Convention

• takes_table: true
• table_optional: false

Clones the given entities.

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

Parameters

• entities: Array<LuaEntity>
• destination_offset: Vector
• destination_surface?: SurfaceIdentification
• destination_force?: ForceID
• snap_to_grid?: boolean
• create_build_effect_smoke?: boolean — If true, the building effect smoke will be shown around the new entities.

clear

LuaSurface.clear(ignore_characters?: boolean)

Call As

surface.clear()

Call Convention

• takes_table: false
• table_optional: false

Clears this surface deleting all entities and chunks on it.

Parameters

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

request_path

LuaSurface.request_path{ bounding_box: BoundingBox, collision_mask: CollisionMask, start: MapPosition, goal: MapPosition, force: ForceID, radius?: double, pathfind_flags?: PathfinderFlags, can_open_gates?: boolean, path_resolution_modifier?: int32, max_gap_size?: int32, max_attack_distance?: double, entity_to_ignore?: LuaEntity } -> uint32

Call As

surface.request_path{ bounding_box=bounding_box, collision_mask=collision_mask, start=start, goal=goal, force=force }

Call Convention

• takes_table: true
• table_optional: false

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

The resulting path is ultimately returned asynchronously via on_script_path_request_finished.

Parameters

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

Returns

• uint32 — A unique handle to identify this call when on_script_path_request_finished fires.

get_script_areas

LuaSurface.get_script_areas(name?: string) -> Array<ScriptArea>

Call As

surface.get_script_areas()

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• name?: string

Returns

• Array<ScriptArea>

get_script_area

LuaSurface.get_script_area(key?: string | uint32) -> ScriptArea?

Call As

surface.get_script_area()

Call Convention

• takes_table: false
• table_optional: false

Gets the first script area by name or id.

Parameters

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

Returns

• ScriptArea?

edit_script_area

LuaSurface.edit_script_area(id: uint32, area: ScriptArea)

Call As

surface.edit_script_area(id, area)

Call Convention

• takes_table: false
• table_optional: false

Sets the given script area to the new values.

Parameters

• id: uint32 — The area to edit.
• area: ScriptArea

add_script_area

LuaSurface.add_script_area(area: ScriptArea) -> uint32

Call As

surface.add_script_area(area)

Call Convention

• takes_table: false
• table_optional: false

Adds the given script area.

Parameters

• area: ScriptArea

Returns

• uint32 — The id of the created area.

remove_script_area

LuaSurface.remove_script_area(id: uint32) -> boolean

Call As

surface.remove_script_area(id)

Call Convention

• takes_table: false
• table_optional: false

Removes the given script area.

Parameters

• id: uint32

Returns

• boolean — If the area was actually removed. False when it didn't exist.

get_script_positions

LuaSurface.get_script_positions(name?: string) -> Array<ScriptPosition>

Call As

surface.get_script_positions()

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• name?: string

Returns

• Array<ScriptPosition>

get_script_position

LuaSurface.get_script_position(key?: string | uint32) -> ScriptPosition?

Call As

surface.get_script_position()

Call Convention

• takes_table: false
• table_optional: false

Gets the first script position by name or id.

Parameters

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

Returns

• ScriptPosition?

edit_script_position

LuaSurface.edit_script_position(id: uint32, position: ScriptPosition)

Call As

surface.edit_script_position(id, position)

Call Convention

• takes_table: false
• table_optional: false

Sets the given script position to the new values.

Parameters

• id: uint32 — The position to edit.
• position: ScriptPosition

add_script_position

LuaSurface.add_script_position(position: ScriptPosition) -> uint32

Call As

surface.add_script_position(position)

Call Convention

• takes_table: false
• table_optional: false

Adds the given script position.

Parameters

• position: ScriptPosition

Returns

• uint32 — The id of the created position.

remove_script_position

LuaSurface.remove_script_position(id: uint32) -> boolean

Call As

surface.remove_script_position(id)

Call Convention

• takes_table: false
• table_optional: false

Removes the given script position.

Parameters

• id: uint32

Returns

• boolean — If the position was actually removed. False when it didn't exist.

get_map_exchange_string

LuaSurface.get_map_exchange_string() -> string

Call As

surface.get_map_exchange_string()

Call Convention

• takes_table: false
• table_optional: false

Gets the map exchange string for the current map generation settings of this surface.

Returns

• string

get_starting_area_radius

LuaSurface.get_starting_area_radius() -> double

Call As

surface.get_starting_area_radius()

Call Convention

• takes_table: false
• table_optional: false

Gets the starting area radius of this surface.

Returns

• double

get_closest

LuaSurface.get_closest(position: MapPosition, entities: Array<LuaEntity>) -> LuaEntity?

Call As

surface.get_closest(position, entities)

Call Convention

• takes_table: false
• table_optional: false

Gets the closest entity in the list to this position.

Parameters

• position: MapPosition
• entities: Array<LuaEntity> — The Entities to check.

Returns

• LuaEntity?

get_total_pollution

LuaSurface.get_total_pollution() -> double

Call As

surface.get_total_pollution()

Call Convention

• takes_table: false
• table_optional: false

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

Returns

• double

entity_prototype_collides

LuaSurface.entity_prototype_collides(prototype: EntityID, position: MapPosition, use_map_generation_bounding_box: boolean, direction?: defines.direction) -> boolean

Call As

surface.entity_prototype_collides(prototype, position, true)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• prototype: EntityID — The entity prototype to check.
• position: MapPosition — The position to check.
• use_map_generation_bounding_box: boolean — If the map generation bounding box should be used instead of the collision bounding box.
• direction?: defines.direction

Returns

• boolean

decorative_prototype_collides

LuaSurface.decorative_prototype_collides(prototype: DecorativeID, position: MapPosition) -> boolean

Call As

surface.decorative_prototype_collides(prototype, position)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• prototype: DecorativeID — The decorative prototype to check.
• position: MapPosition — The position to check.

Returns

• boolean

calculate_tile_properties

LuaSurface.calculate_tile_properties(property_names: Array<string>, positions: Array<MapPosition>) -> Dict<string, Array<double>>

Call As

surface.calculate_tile_properties(property_names, positions)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• property_names: Array<string> — Names of properties ("elevation", etc) to calculate.
• positions: Array<MapPosition> — Positions for which to calculate property values.

Returns

• Dict<string, Array<double>> — Table of property value lists, keyed by property name.

get_entities_with_force

LuaSurface.get_entities_with_force(chunk_position: ChunkPosition, force: ForceID) -> Array<LuaEntity>

Call As

surface.get_entities_with_force(chunk_position, force)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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

Returns

• Array<LuaEntity>

create_entities_from_blueprint_string

LuaSurface.create_entities_from_blueprint_string{ string: string, position: MapPosition, force?: ForceID, direction?: defines.direction, flip_horizontal?: boolean, flip_vertical?: boolean, by_player?: PlayerIdentification } -> int32?

Call As

surface.create_entities_from_blueprint_string{ string=string, position=position }

Call Convention

• takes_table: true
• table_optional: false

This method only works when used in simulations.

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

Parameters

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

Returns

• int32? — If the blueprint string was invalid, 1 is returned. Otherwise, nil is returned.

build_checkerboard

LuaSurface.build_checkerboard(area: BoundingBox)

Call As

surface.build_checkerboard(area)

Call Convention

• takes_table: false
• table_optional: false

Sets the given area to the checkerboard lab tiles.

Parameters

• area: BoundingBox — The tile area.

get_property

LuaSurface.get_property(property: SurfacePropertyID) -> double

Call As

surface.get_property(property)

Call Convention

• takes_table: false
• table_optional: false

Gets the value of surface property on this surface.

Parameters

• property: SurfacePropertyID — Property to read.

Returns

• double — Value of the property.

set_property

LuaSurface.set_property(property: SurfacePropertyID, value: double)

Call As

surface.set_property(property, value)

Call Convention

• takes_table: false
• table_optional: false

Sets the value of surface property on this surface.

Parameters

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

create_global_electric_network

LuaSurface.create_global_electric_network()

Call As

surface.create_global_electric_network()

Call Convention

• takes_table: false
• table_optional: false

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

destroy_global_electric_network

LuaSurface.destroy_global_electric_network()

Call As

surface.destroy_global_electric_network()

Call Convention

• takes_table: false
• table_optional: false

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

execute_lightning

LuaSurface.execute_lightning{ name: EntityID, position: MapPosition }

Call As

surface.execute_lightning{ name="name", position=position }

Call Convention

• takes_table: true
• table_optional: false

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

Parameters

• name: EntityID
• position: MapPosition

clear_hidden_tiles

LuaSurface.clear_hidden_tiles()

Call As

surface.clear_hidden_tiles()

Call Convention

• takes_table: false
• table_optional: false

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

get_default_cover_tile

LuaSurface.get_default_cover_tile(force: ForceID, tile: TileID) -> LuaTilePrototype?

Call As

surface.get_default_cover_tile(force, tile)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

• force: ForceID
• tile: TileID

Returns

• LuaTilePrototype?

set_default_cover_tile

LuaSurface.set_default_cover_tile(force: ForceID, from_tile: TileID, to_tile: TileID | nil)

Call As

surface.set_default_cover_tile(force, from_tile, to_tile)

Call Convention

• takes_table: false
• table_optional: false

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

Parameters

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