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.

Attributes

surface

• Read: LuaSurface
• Write: unknown
• Optional: false

The surface on which this territory is located.

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

destroy

LuaTerritory.destroy()

Call As

territory.destroy()

Call Convention

• takes_table: false
• table_optional: false

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.

get_chunks

LuaTerritory.get_chunks() -> Array<ChunkPositionAndArea>

Call As

territory.get_chunks()

Call Convention

• takes_table: false
• table_optional: false

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.

Returns

• Array<ChunkPositionAndArea>

get_segmented_units

LuaTerritory.get_segmented_units() -> Array<LuaSegmentedUnit>

Call As

territory.get_segmented_units()

Call Convention

• takes_table: false
• table_optional: false

Gets the LuaSegmentedUnits that guard this territory.

Returns

• Array<LuaSegmentedUnit>

regenerate_segmented_units

LuaTerritory.regenerate_segmented_units()

Call As

territory.regenerate_segmented_units()

Call Convention

• takes_table: false
• table_optional: false

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.

regenerate_patrol_path

LuaTerritory.regenerate_patrol_path()

Call As

territory.regenerate_patrol_path()

Call Convention

• takes_table: false
• table_optional: false

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

LuaTerritory.get_patrol_path() -> Array<MapPosition>

Call As

territory.get_patrol_path()

Call Convention

• takes_table: false
• table_optional: false

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.

Returns

• Array<MapPosition>

set_patrol_path

LuaTerritory.set_patrol_path(patrol_path: Array<MapPosition>)

Call As

territory.set_patrol_path(patrol_path)

Call Convention

• takes_table: false
• table_optional: false

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.