Factorio.com|Forums|Wiki|Mod Portal|API Docs

# Factorio Runtime Docs Version 2.0.77

# LuaTerritory - Runtime Docs

## Class LuaTerritory

A set of chunks on a single LuaSurface that can be guarded by one or more LuaSegmentedUnits.

A territory is owned by the surface for which it was created. It comprises any number of disconnected or connected chunks. A chunk can only be owned by at most one territory. A territory's chunks may or may not be generated.

Territories may be patrolled by any number of LuaSegmentedUnits. A territory with no units will not appear on player's maps.

Territories may define a patrol path that LuaSegmentedUnits will follow. If no such path is defined, then units will wander randomly throughout the territory chunks. If a territory contains no patrol path and no chunks, then units will behave as if they are assigned to any territory.

The game will automatically destroy any territory that does not have at least one chunk that is generated or requested to be generated. This is to prevent bloat when chunks are deleted. This can happen as a result of any operation that modifies a territory's chunks, including but not limited to LuaSurface::delete_chunk, LuaSurface::set_territory_for_chunks, and LuaSurface::clear_territory_for_chunks.

## Members

destroy() |  | Immediately destroys the territory, along with any segmented units guarding it. [...]
Immediately destroys the territory, along with any segmented units guarding it. [...]
get_chunks() | → array[ChunkPositionAndArea] | Gets all chunks that are a part of the territory. [...]
Gets all chunks that are a part of the territory. [...]
get_segmented_units() | → array[LuaSegmentedUnit] | Gets the LuaSegmentedUnits that guard this territory.
Gets the LuaSegmentedUnits that guard this territory.
regenerate_segmented_units() |  | Regenerates any segmented units that were created when the territory was generated by the map generator. [...]
Regenerates any segmented units that were created when the territory was generated by the map generator. [...]
regenerate_patrol_path() |  | Regenerates the patrol path for the territory according to the game's default territory generation algorithm and overwrites the territory's current patrol path.
Regenerates the patrol path for the territory according to the game's default territory generation algorithm and overwrites the territory's current patrol path.
get_patrol_path() | → array[MapPosition] | Get the path that the territory's units follow when patrolling the territory. [...]
Get the path that the territory's units follow when patrolling the territory. [...]
set_patrol_path(patrol_path) |  | Overwrite the territory patrol path for units that guard the territory. [...]
Overwrite the territory patrol path for units that guard the territory. [...]
surface | :: R LuaSurface | The surface on which this territory is located.
The surface on which this territory is located.
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. [...]

## Methods

### destroy()

Immediately destroys the territory, along with any segmented units guarding it. All associated chunks are cleared from the territory system, allowing the map generator to potentially generate new territories for these chunks in the future.

This LuaTerritory is no longer valid after calling this.

#### Raised events

on_territory_destroyed instantly |

### get_chunks() → array[ChunkPositionAndArea]

Gets all chunks that are a part of the territory.

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

### get_segmented_units() → array[LuaSegmentedUnit]

Gets the LuaSegmentedUnits that guard this territory.

### regenerate_segmented_units()

Regenerates any segmented units that were created when the territory was generated by the map generator. If the territory was created or modified by a script, and the surface's map generator is configured to create segmented units with territories, then this function will create the segmented units that would have been created along with the script-modified or script-created territory. If the surface's map generator is not configured to create segmented units at all, then no segmented units will be created.

Note: this does not destroy or replace existing units guarding the territory, and existing units will not prevent the generation of new units. Calling this repeatedly on a territory that generates a segmented unit will simply repeatedly add new segmented units to the map, all guarding this territory.

#### Raised events

on_segmented_unit_created? instantly | Raised for each segmented unit successfully created. cause will be set to map_generated.

### regenerate_patrol_path()

Regenerates the patrol path for the territory according to the game's default territory generation algorithm and overwrites the territory's current patrol path.

### get_patrol_path() → array[MapPosition]

Get the path that the territory's units follow when patrolling the territory. Will not be empty.

It is common that the territory's patrol path is fully contained within the territory's chunks, but it is not strictly necessary.

### set_patrol_path(patrol_path)

Overwrite the territory patrol path for units that guard the territory.

It is recommended that the territory's patrol path be fully contained within the territory's chunks, but it is not strictly necessary.

To let the territory system generate a patrol path, use LuaTerritory::regenerate_patrol_path.

#### Parameters

patrol_path | :: array[MapPosition] | The new patrol path for the territory. Must not be empty.
The new patrol path for the territory. Must not be empty.

## Attributes

### surface :: Read LuaSurface

The surface on which this territory is located.

### valid :: Read boolean

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

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.

Class used in

- LuaSegmentedUnit::clone()
- LuaSegmentedUnit::territory
- LuaSurface::create_segmented_unit()
- LuaSurface::create_territory()
- LuaSurface::get_territories()
- LuaSurface::get_territory_for_chunk()
- LuaSurface::set_territory_for_chunks()
- RegistrationTarget
- on_territory_created
- on_territory_destroyed