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

# Factorio Runtime Docs Version 2.0.77

# LuaSegmentedUnit - Runtime Docs

## Class LuaSegmentedUnit

A surface-level object composed of one SegmentedUnitPrototype followed by up to 63 SegmentPrototypes.

This object is not an entity, and can exist on chunks that do not exist. Instead, the individual segments that compose its body will be destroyed as the unit's body crosses into un-generated or void terrain, and will be re-created when the body crosses into generated, non-void terrain.

Use LuaSurface::get_segmented_units to iterate over all units on a surface, LuaTerritory::get_segmented_units to iterate over all units that guard a territory, or LuaEntity::segmented_unit to get the unit that controls any given segment entity.

## Members

destroy{raise_destroy?=…} |  | Destroys the segmented unit.
Destroys the segmented unit.
die(force?, cause?, damage_type?) |  | Immediately kills the unit. [...]
Immediately kills the unit. [...]
damage(damage, force, type?, source?, cause?) | → float | Damages the unit.
Damages the unit.
move_forward(distance) |  | Moves the unit forward by a fixed distance according to its natural movement patterns and AI configuration. [...]
Moves the unit forward by a fixed distance according to its natural movement patterns and AI configuration. [...]
clone{position=…, surface?=…, force?=…, territory?=…} | → LuaSegmentedUnit? | Clones this unit.
Clones this unit.
get_body_nodes() | → array[MapPosition] | Gets the nodes that define the shape of the unit's body from front to back. [...]
Gets the nodes that define the shape of the unit's body from front to back. [...]
set_body_nodes(nodes) |  | Overwrites the segmented unit's body nodes, which are a series of points that make up the general shape of the unit. [...]
Overwrites the segmented unit's body nodes, which are a series of points that make up the general shape of the unit. [...]
get_ai_state() | → SegmentedUnitAIState | Gets the state of the unit's AI. [...]
Gets the state of the unit's AI. [...]
set_ai_state(state) |  | Sets the segmented unit's AI.
Sets the segmented unit's AI.
prototype | :: R LuaEntityPrototype | The prototype of the `segmented-unit` entity that defines the traits and behaviors of the unit.
The prototype of the `segmented-unit` entity that defines the traits and behaviors of the unit.
surface | :: R LuaSurface | The surface on which the unit is located.
The surface on which the unit is located.
territory | :: RW LuaTerritory? | The territory that the unit is protecting.
The territory that the unit is protecting.
segments | :: R array[LuaSegment] | The segments that compose the unit.
The segments that compose the unit.
force | :: R LuaForce| W ForceID | The force that the unit belongs to. [...]
The force that the unit belongs to. [...]
unit_number | :: R uint64 | A unique number identifying this unit for the lifetime of the save. [...]
A unique number identifying this unit for the lifetime of the save. [...]
health | :: RW float | The current health of the unit. [...]
The current health of the unit. [...]
max_health | :: R float | The maximum health of the unit.
The maximum health of the unit.
health_ratio | :: RW float | The ratio of LuaSegmentedUnit::health to LuaSegmentedUnit::max_health. [...]
The ratio of LuaSegmentedUnit::health to LuaSegmentedUnit::max_health. [...]
speed | :: RW double | The current instantaneous speed in tiles per map tick. [...]
The current instantaneous speed in tiles per map tick. [...]
target_speed | :: R double | The speed in tiles per tick that the unit is currently attempting to reach, as determined by its AI. [...]
The speed in tiles per tick that the unit is currently attempting to reach, as determined by its AI. [...]
acceleration | :: R double | The rate at which LuaSegmentedUnit::speed is changing over time, in tiles per tick per tick. [...]
The rate at which LuaSegmentedUnit::speed is changing over time, in tiles per tick per tick. [...]
max_body_nodes | :: R uint32 | The maximum length of LuaSegmentedUnit::get_body_nodes.
The maximum length of LuaSegmentedUnit::get_body_nodes.
activity_mode | :: RW defines.segmented_unit_activity_mode | The current activity mode of the unit. [...]
The current activity mode of the unit. [...]
minimum_activity_mode | :: RW defines.segmented_unit_activity_mode | The lowest-level activity mode that the unit is allowed to be in. [...]
The lowest-level activity mode that the unit is allowed to be in. [...]
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{raise_destroy?=…}

Destroys the segmented unit.

#### Parameters

Table (optional) with the following fields:

raise_destroy | :: boolean? | If `true`, script_raised_destroy_segmented_unit will be called. Defaults to `false`.
If `true`, script_raised_destroy_segmented_unit will be called. Defaults to `false`.

#### Raised events

script_raised_destroy_segmented_unit? instantly | Raised if the `raise_destroy` flag was set and the unit was successfully destroyed.

### die(force?, cause?, damage_type?)

Immediately kills the unit.

Unlike LuaSegmentedUnit::destroy, `die` will trigger the on_segmented_unit_died event and the unit's individual segments will produce a corpse and drop loot if they have any, and if the segment entities exist at the moment of death (are not in non-generated chunks or out-of-map tiles).

#### Parameters

force | :: ForceID? | The force to attribute the kill to. Defaults to the `"neutral"` force.
The force to attribute the kill to. Defaults to the `"neutral"` force.
cause | :: LuaEntity? | The cause to attribute the kill to.
The cause to attribute the kill to.
damage_type | :: DamageTypeID? | The final damage type that caused the unit to die.
The final damage type that caused the unit to die.

#### Raised events

on_segmented_unit_died instantly |
on_post_segmented_unit_died instantly |

### damage(damage, force, type?, source?, cause?) → float

Damages the unit.

#### Parameters

damage | :: float | The amount of damage to be done.
The amount of damage to be done.
force | :: ForceID | The force that is doing the damage.
The force that is doing the damage.
type | :: DamageTypeID? | The type of damage being done. Defaults to `"impact"`.
The type of damage being done. Defaults to `"impact"`.
source | :: LuaEntity? | The entity that is directly dealing the damage. This is the projectile, flame, sticker, grenade, laster beam, etc. Must be on the same surface as the entity being damaged.
The entity that is directly dealing the damage. This is the projectile, flame, sticker, grenade, laster beam, etc. Must be on the same surface as the entity being damaged.
cause | :: LuaEntity? | The entity that originally triggered the events that led to this damage being dealt. This can be the player character, turret, unit, etc. that pulled the trigger. Does not need to be on the same surface as the segmented unit being damaged.
The entity that originally triggered the events that led to this damage being dealt. This can be the player character, turret, unit, etc. that pulled the trigger. Does not need to be on the same surface as the segmented unit being damaged.

#### Return values

→ float | The total damage actually applied after resistances.

#### Raised events

on_segmented_unit_damaged instantly |

### move_forward(distance)

Moves the unit forward by a fixed distance according to its natural movement patterns and AI configuration. This movement occurs in addition to the unit's current speed, but affects neither LuaSegmentedUnit::speed nor LuaSegmentedUnit::acceleration.

#### Parameters

distance | :: double | The distance in tiles to move the segmented unit forward.
The distance in tiles to move the segmented unit forward.

### clone{position=…, surface?=…, force?=…, territory?=…} → LuaSegmentedUnit?

Clones this unit.

#### Parameters

Table with the following fields:

position | :: MapPosition | The destination position of the head segment. The rest of the body nodes will be copied relative to this.
The destination position of the head segment. The rest of the body nodes will be copied relative to this.
surface | :: LuaSurface? | The destination surface. If different from this unit's surface, then the clone will not copy the original unit's territory.
The destination surface. If different from this unit's surface, then the clone will not copy the original unit's territory.
force | :: ForceID? | The new unit's force.
The new unit's force.
territory | :: LuaTerritory? | The territory that the clone should guard. Must be on the same surface as the destination surface.
The territory that the clone should guard. Must be on the same surface as the destination surface.

#### Return values

→ LuaSegmentedUnit? | The cloned unit or `nil` if the unit cannot be cloned.

#### Raised events

on_segmented_unit_created? instantly | Raised if a clone of the segmented unit was successfully created. cause will be set to script_cloned.

### get_body_nodes() → array[MapPosition]

Gets the nodes that define the shape of the unit's body from front to back. Segments are moved along the path these nodes create.

The returned array will always contain at least 1 position, but will not contain more than LuaSegmentedUnit::max_body_nodes.

The returned table is a copy of the unit's actual body nodes.

### set_body_nodes(nodes)

Overwrites the segmented unit's body nodes, which are a series of points that make up the general shape of the unit. Segments are moved along the path these nodes create. For best results, adjacent nodes should be approximately 1.0 tile apart from each other.

This array must contain at least 1 position. Positions at indexes greater than LuaSegmentedUnit::max_body_nodes will be ignored.

Segment entities may be created, destroyed, or moved as a result of setting this field's value. Any segment entities that have a TriggerEffectWithCooldowns will reduce that effect's distance cooldown. However, any effects that go off cooldown as a result will not trigger until the next game update.

#### Parameters

nodes | :: array[MapPosition] | The new positions that make up the segmented unit's body nodes. Must not be empty.
The new positions that make up the segmented unit's body nodes. Must not be empty.

### get_ai_state() → SegmentedUnitAIState

Gets the state of the unit's AI.

This method returns a copy of the internal AI state. Modifying the returned table will not affect the unit's AI.

### set_ai_state(state)

Sets the segmented unit's AI.

#### Parameters

state | :: SegmentedUnitAIState | The new AI state. A copy of this table used, so you can read or write to this table after calling this function without being affected by or affecting the unit's AI.
The new AI state. A copy of this table used, so you can read or write to this table after calling this function without being affected by or affecting the unit's AI.

## Attributes

### prototype :: Read LuaEntityPrototype

The prototype of the `segmented-unit` entity that defines the traits and behaviors of the unit.

### surface :: Read LuaSurface

The surface on which the unit is located.

### territory :: Read|Write LuaTerritory?

The territory that the unit is protecting.

### segments :: Read array[LuaSegment]

The segments that compose the unit.

### force :: Read LuaForce| Write ForceID

The force that the unit belongs to. Changing this also changes the force of all segment entities.

Always returns a LuaForce, but may be assigned to any ForceID type.

### unit_number :: Read uint64

A unique number identifying this unit for the lifetime of the save. These are allocated sequentially and not re-used (until overflow). These numbers are allocated from the same pool as LuaEntity::unit_number, so segmented unit numbers are unique among all segmented units and all entities with owners.

### health :: Read|Write float

The current health of the unit. Health is automatically clamped to be between `0` and LuaSegmentedUnit::max_health.

### max_health :: Read float

The maximum health of the unit.

### health_ratio :: Read|Write float

The ratio of LuaSegmentedUnit::health to LuaSegmentedUnit::max_health. Values are clamped between `0` (no health) and `1` (full health) inclusive.

### speed :: Read|Write double

The current instantaneous speed in tiles per map tick. Must always be greater than or equal to 0; segmented units are currently incapable of naturally moving in reverse.

When setting this value, note that unless the unit's AI is similarly overridden by a script, the unit's speed will continuously accelerate or decelerate to match LuaSegmentedUnit::target_speed.

### target_speed :: Read double

The speed in tiles per tick that the unit is currently attempting to reach, as determined by its AI. Must always be greater than or equal to 0.

### acceleration :: Read double

The rate at which LuaSegmentedUnit::speed is changing over time, in tiles per tick per tick.

This value represents unit's most recent change in speed. If its speed is not changing, the acceleration value will be 0. If it is gaining speed, the value will be positive. If it is losing speed, the value will be negative.

### max_body_nodes :: Read uint32

The maximum length of LuaSegmentedUnit::get_body_nodes.

### activity_mode :: Read|Write defines.segmented_unit_activity_mode

The current activity mode of the unit. Setting this field can cause the segmented unit to "wake up" or force it into a lower activity mode, but not permanently. Segmented units will generally try to update their activity mode so that they are fully active whenever they are potentially being observed by players, minimally active when relevant to gameplay but not likely observed, and asleep when not relevant to gameplay.

Will never be lower than LuaSegmentedUnit::minimum_activity_mode.

### minimum_activity_mode :: Read|Write defines.segmented_unit_activity_mode

The lowest-level activity mode that the unit is allowed to be in. Set this field to prevent the segmented unit from falling asleep or entering minimal mode. Set this field to `nil` or asleep to reset this to the default and allow the engine to use whatever activity mode is appropriate.

Performance note: it is NOT recommended to force many segmented units to be fully active or minimally active simultaneously, as they can significantly impact performance depending on how they are configured. When using this feature, remember to reset this field to allow irrelevant units to go back to sleep.

### 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

- LuaBootstrap::raise_script_destroy_segmented_unit()
- LuaEntity::segmented_unit
- LuaSegment::unit
- LuaSegmentedUnit::clone()
- LuaSurface::create_segmented_unit()
- LuaSurface::get_segmented_units()
- LuaTerritory::get_segmented_units()
- RegistrationTarget
- on_segmented_unit_created
- on_segmented_unit_damaged
- on_segmented_unit_died
- script_raised_destroy_segmented_unit