Struct LuaSegmentedUnit 

pub struct 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.

Implementations

impl LuaSegmentedUnit

pub fn acceleration(&self) -> f64

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.

pub fn activity_mode(&self) -> &str

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.

pub fn force(&self) -> LuaForce

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.

pub fn health(&self) -> f32

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

pub fn health_ratio(&self) -> f32

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

pub fn max_body_nodes(&self) -> u32

The maximum length of LuaSegmentedUnit::get_body_nodes.

pub fn max_health(&self) -> f32

The maximum health of the unit.

pub fn minimum_activity_mode(&self) -> &str

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.

pub fn object_name(&self) -> &str

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.

pub fn prototype(&self) -> LuaEntityPrototype

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

pub fn segments(&self) -> Vec<LuaSegment>

The segments that compose the unit.

pub fn speed(&self) -> f64

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.

pub fn surface(&self) -> LuaSurface

The surface on which the unit is located.

pub fn target_speed(&self) -> f64

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.

pub fn territory(&self) -> LuaTerritory

The territory that the unit is protecting.

pub fn unit_number(&self) -> u64

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.

pub fn valid(&self) -> bool

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.

pub fn clone( &self, params: LuaSegmentedUnitCloneParams, ) -> Option<LuaSegmentedUnit>

Clones this unit.

pub fn damage( &self, cause: Option<LuaEntity>, damage: f32, force: LuaAny, source: Option<LuaEntity>, type: Option<LuaAny>, ) -> f32

Damages the unit.

pub fn destroy(&self, params: LuaSegmentedUnitDestroyParams)

Destroys the segmented unit.

pub fn die( &self, cause: Option<LuaEntity>, damage_type: Option<LuaAny>, force: Option<LuaAny>, )

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).

pub fn get_ai_state(&self) -> 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.

pub fn get_body_nodes(&self) -> Vec<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.

pub fn move_forward(&self, distance: f64)

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.

pub fn set_ai_state(&self, state: SegmentedUnitAIState)

Sets the segmented unit’s AI.

pub fn set_body_nodes(&self, nodes: Vec<MapPosition>)

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.

Trait Implementations

impl Clone for LuaSegmentedUnit

fn clone(&self) -> LuaSegmentedUnit

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for LuaSegmentedUnit

impl Debug for LuaSegmentedUnit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LuaSegmentedUnit

fn default() -> LuaSegmentedUnit

Returns the “default value” for a type.

impl Eq for LuaSegmentedUnit

impl From<LuaSegmentedUnit> for LuaAny

fn from(_: LuaSegmentedUnit) -> Self

Converts to this type from the input type.

impl LuaObject for LuaSegmentedUnit

impl PartialEq for LuaSegmentedUnit

fn eq(&self, other: &LuaSegmentedUnit) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for LuaSegmentedUnit