btech.unit on StompyMUX Documentation

apply_damage

Mon, 01 Jan 0001 00:00:00 +0000

Applies clustered damage to a live unit.

Function

Synopsis

btech.unit.apply_damage( unit, request )

Arguments

DbRef|Object unit: The live unit.
table request: The damage request.

The request requires these fields:

integer amount: The total damage to apply, from 1 to 1000.
integer cluster_size: The maximum damage in each cluster, from 1 to 1000.
integer direction_code: The attack direction code, from 0 to 21.

Codes 0 through 7 damage a fixed section; codes 8 through 15 target the corresponding section (code - 8) with the rear-hit flag. Section indices depend on the unit class:

armor

Mon, 01 Jan 0001 00:00:00 +0000

Returns a live unit’s armor and internal values.

Function

Synopsis

btech.unit.armor( unit, section )

Arguments

DbRef|Object unit: The live unit.
BtechSection|nil section: An optional typed constant from btech.unit.sections that is valid for the unit.

Returns

BtechArmorStatus status: The requested armor status.

Notes

When section is omitted, the returned armor, internal-structure, and rear- armor values are totals across all sections, and the record has no section field. When present, the returned section is the same typed constant and round-trips into section-taking functions.

assigned_pilot

Mon, 01 Jan 0001 00:00:00 +0000

Returns a live unit’s assigned pilot.

Function

Synopsis

btech.unit.assigned_pilot( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

Object|nil pilot: The pilot, or nil when none is assigned.

battle_value

Mon, 01 Jan 0001 00:00:00 +0000

Calculates a live unit’s current battle value.

Function

Synopsis

btech.unit.battle_value( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

BtechBattleValue value: The total, offensive, and defensive values.

btech.unit.ammunition_modes

Mon, 01 Jan 0001 00:00:00 +0000

btech.unit.ammunition_modes is an immutable namespace of typed BtechAmmunitionMode constants.

Function

Synopsis

btech.unit.ammunition_modes.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechAmmunitionMode constant: The typed ammunition mode represented by CONSTANT.

Raises

Raises mux.arg.invalid for invalid lookup, mutation, raw strings, wrong-kind constants, or constants from another runtime.

Notes

Constants are immutable and local to the runtime that created them.

Constants
`LBX_CLUSTER`, `ARTEMIS_MINE`, `NARC_SMOKE`, `CLUSTER`, `MINE`, `SMOKE`, `INFERNO`, `SWARM`, `SWARM_1`, `INARC_EXPLOSIVE`, `INARC_HAYWIRE`, `INARC_ECM`, `INARC_NEMESIS`, `ARMOR_PIERCING`, `FLECHETTE`, `INCENDIARY`, `PRECISION`, `STINGER`, `CASELESS`, `SEMI_GUIDED`, `EXTENDED_RANGE`, `HIGH_EXPLOSIVE`, `MML_LRM`

Mode arrays accepted by configure_ammunition and set_weapon_modes contain these constants. Repeated lookups of the same mode compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups, mutation, raw strings, wrong-kind constants, and cross-runtime constants raise mux.arg.invalid where an argument is required.

btech.unit.fire_modes

Mon, 01 Jan 0001 00:00:00 +0000

btech.unit.fire_modes is an immutable namespace of typed BtechFireMode constants.

Function

Synopsis

btech.unit.fire_modes.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechFireMode constant: The typed fire mode represented by CONSTANT.

Raises

Raises mux.arg.invalid for invalid lookup, mutation, raw strings, wrong-kind constants, or constants from another runtime.

Notes

Constants are immutable and local to the runtime that created them.

Constants
`DESTROYED`, `DISABLED`, `BROKEN`, `DAMAGED`, `TARGETING_COMPUTER`, `REAR_MOUNT`, `HOTLOAD`, `HALF_TON`, `ONE_SHOT`, `ONE_SHOT_USED`, `ULTRA`, `RAPID_FIRE`, `GATLING`, `ROTARY_TWO_SHOT`, `ROTARY_FOUR_SHOT`, `ROTARY_SIX_SHOT`, `HEAT`, `BACKPACK`, `JETTISONED`, `OMNI_BASE`, `ROCKET_FIRED`

Mode arrays accepted by set_weapon_modes contain these constants. Repeated lookups of the same mode compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups, mutation, raw strings, wrong-kind constants, and cross-runtime constants raise mux.arg.invalid where an argument is required.

btech.unit.movement_types

Mon, 01 Jan 0001 00:00:00 +0000

btech.unit.movement_types is an immutable namespace of typed BtechMovementType constants.

Function

Synopsis

btech.unit.movement_types.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechMovementType constant: The typed movement class represented by CONSTANT.

Raises

Raises mux.arg.invalid for invalid lookup, mutation, or use as the wrong typed argument.

Notes

Constants are immutable and local to the runtime that created them.

Constants
`BIPED`, `TRACK`, `WHEEL`, `HOVER`, `VTOL`, `HULL`, `FOIL`, `FLY`, `QUAD`, `SUB`, `NONE`

Use these values with btech.unit.set_movement_type. Repeated lookups of the same movement type compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups, mutation, raw strings, wrong-kind constants, and constants from another Lua runtime raise mux.arg.invalid where an argument is required.

btech.unit.sections

Mon, 01 Jan 0001 00:00:00 +0000

btech.unit.sections is an immutable namespace of typed BtechSection constants. Section-taking functions validate that the selected section exists for the target unit or template.

Function

Synopsis

btech.unit.sections.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechSection constant: The typed section represented by CONSTANT.

Raises

Raises mux.arg.invalid for invalid lookup, mutation, or use as the wrong typed argument. Section-taking functions also reject sections absent from the selected layout.

Notes

Constants are immutable and local to the runtime that created them.

btech.unit.technology

Mon, 01 Jan 0001 00:00:00 +0000

btech.unit.technology is an immutable namespace of typed BtechTechnologyCode constants.

Function

Synopsis

btech.unit.technology.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechTechnologyCode constant: The typed technology code represented by CONSTANT.

Raises

Raises mux.arg.invalid for invalid lookup, mutation, raw strings, wrong-kind constants, or constants from another runtime.

Notes

Constants are immutable and local to the runtime that created them.

Group	Constants
Primary unit technology	`TRIPLE_STRENGTH_MYOMER`, `CLAN_ANTI_MISSILE`, `INNER_SPHERE_ANTI_MISSILE`, `DOUBLE_HEAT_SINKS`, `MASC`, `CLAN`, `FLIPPABLE_ARMS`, `C3_MASTER`, `C3_SLAVE`, `ARTEMIS_IV`, `ECM`, `BEAGLE_PROBE`, `SALVAGE`, `CARGO`, `SEARCH_LIGHT`, `LIGHT_ACTIVE_PROBE`, `ANTI_AIRCRAFT`, `NO_SENSORS`, `SIXTH_SENSE`, `FERRO_FIBROUS`, `ENDO_STEEL`, `XL_ENGINE`, `ICE_ENGINE`, `SINGLE_HEAT_SINKS`, `LIGHT_ENGINE`, `XXL_ENGINE`, `COMPACT_ENGINE`, `REINFORCED_INTERNAL`, `COMPOSITE_INTERNAL`, `HARDENED_ARMOR`, `CRITICAL_PROOF`
Secondary unit technology	`STEALTH_ARMOR`, `HEAVY_FERRO_FIBROUS`, `LASER_REFLECTIVE_ARMOR`, `REACTIVE_ARMOR`, `NULL_SIGNATURE_SYSTEM`, `C3I`, `SUPERCHARGER`, `IMPROVED_JUMP_JETS`, `MECHANICAL_JUMP_JETS`, `COMPACT_HEAT_SINKS`, `LASER_HEAT_SINKS`, `BLOODHOUND_PROBE`, `ANGEL_ECM`, `WATCHDOG`, `LIGHT_FERRO_FIBROUS`, `TAG`, `OMNIMECH`, `ARTEMIS_V`, `CAMOUFLAGE`, `CARRIER`, `WATERPROOF`, `XL_GYRO`, `HEAVY_DUTY_GYRO`, `COMPACT_GYRO`, `TARGETING_COMPUTER`, `SMALL_COCKPIT`
Infantry technology	`SWARM_ATTACK`, `MOUNT_FRIENDS`, `ANTI_LEG_ATTACK`, `PURIFIER_STEALTH`, `KAGE_STEALTH`, `ACHILEUS_STEALTH`, `INFILTRATOR_STEALTH`, `INFILTRATOR_II_STEALTH`, `MUST_JETTISON_PACK`, `CAN_JETTISON_PACK`

Use these values with add_technology and remove_technology. Infantry constants require a battlesuit. Repeated lookups of the same technology compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups, mutation, raw strings, wrong-kind constants, and cross-runtime constants raise mux.arg.invalid where an argument is required.

btech.unit.technology_groups

Mon, 01 Jan 0001 00:00:00 +0000

btech.unit.technology_groups is an immutable namespace of typed BtechTechnologyGroup constants.

Function

Synopsis

btech.unit.technology_groups.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechTechnologyGroup constant: The typed clearing group represented by CONSTANT.

Raises

Raises mux.arg.invalid for invalid lookup, mutation, raw strings, wrong-kind constants, or constants from another runtime.

Notes

Constants are immutable and local to the runtime that created them.

Constant	Group cleared by `clear_technologies`
`UNIT`	Primary and secondary unit technologies.
`INFANTRY`	Battlesuit infantry technologies.
`ALL`	Unit and infantry technologies.

Repeated lookups of the same group compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups, mutation, raw strings, wrong-kind constants, and cross-runtime constants raise mux.arg.invalid where an argument is required.

btech.unit.types

Mon, 01 Jan 0001 00:00:00 +0000

btech.unit.types is an immutable namespace of typed BtechUnitType constants.

Function

Synopsis

btech.unit.types.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechUnitType constant: The typed unit class represented by CONSTANT.

Raises

Raises mux.arg.invalid for invalid lookup, mutation, or use as the wrong typed argument.

Notes

Constants are immutable and local to the runtime that created them.

Constants
`MECH`, `VEHICLE`, `VTOL`, `NAVAL`, `SPHEROID_DROPSHIP`, `AERO_FIGHTER`, `MECHWARRIOR`, `AERODYNE_DROPSHIP`, `BATTLESUIT`

Use these values with btech.unit.set_unit_type. Repeated lookups of the same unit type compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups, mutation, raw strings, wrong-kind constants, and constants from another Lua runtime raise mux.arg.invalid where an argument is required.

critical_slots

Mon, 01 Jan 0001 00:00:00 +0000

Lists a live unit section’s critical slots.

Function

Synopsis

btech.unit.critical_slots( unit, section )

Arguments

DbRef|Object unit: The live unit.
BtechSection section: A typed constant from btech.unit.sections that is valid for the unit.

Returns

BtechCriticalSlot[] slots: The critical-slot records. Each record’s section, fire_modes, and ammunition_modes fields contain typed constants from the corresponding btech.unit namespaces and can be reused as inputs without conversion.

display_name

Mon, 01 Jan 0001 00:00:00 +0000

Returns a live unit’s display-name override.

Function

Synopsis

btech.unit.display_name( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

string|nil name: The override, or nil when unset.

effective_max_speed

Mon, 01 Jan 0001 00:00:00 +0000

Returns a live unit’s effective maximum speed.

Function

Synopsis

btech.unit.effective_max_speed( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

number movement_points: The effective maximum speed in movement points.

Use effective_max_speed_kph when kilometers per hour are required.

engine

Mon, 01 Jan 0001 00:00:00 +0000

Returns a live unit’s engine configuration.

Function

Synopsis

btech.unit.engine( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

BtechEngine engine: The rating and suspension factor.

installed_parts

Mon, 01 Jan 0001 00:00:00 +0000

Lists parts represented by non-destroyed critical slots on a live unit.

Function

Synopsis

btech.unit.installed_parts( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

BtechPartStack[] parts: The installed parts and quantities.

Notes

Destroyed critical slots are omitted.

Consecutive weapon slots in the same section with the same part and brand are grouped as one weapon installation. Consequently, separate identical one-slot weapons installed in adjacent slots are reported with a combined quantity of one.

load_template

Mon, 01 Jan 0001 00:00:00 +0000

Loads a unit template into a live unit.

Function

Synopsis

btech.unit.load_template( unit, reference )

Arguments

DbRef|Object unit: The live unit.
string reference: The non-empty unit-template reference. It cannot contain .., /, or \.

Returns

None.

Notes

A missing template raises btech.template.not_found. A template that exists but is malformed raises btech.template.invalid.

markings

Mon, 01 Jan 0001 00:00:00 +0000

Returns a live unit’s markings.

Function

Synopsis

btech.unit.markings( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

string|nil markings: The markings, or nil when unset.

payload

Mon, 01 Jan 0001 00:00:00 +0000

Lists weapons and ammunition represented by non-destroyed critical slots on a live unit.

Function

Synopsis

btech.unit.payload( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

BtechPartStack[] parts: The payload parts and quantities.

Notes

Destroyed critical slots are omitted.

piloting_check

Mon, 01 Jan 0001 00:00:00 +0000

Makes a piloting check and applies a failed result.

Function

Synopsis

btech.unit.piloting_check( unit, options )

Arguments

DbRef|Object unit: The live unit.
table options: The piloting-check options.

The options table requires these fields:

integer roll_modifier: The modifier applied to the unit’s piloting skill roll. Use a gameplay modifier from -100 through 100; values outside this range are unsupported.
integer damage_modifier: The number of fall levels applied when the piloting check fails. Use a value from 0 through 100; values outside this range are unsupported because the fall-damage calculation and damage application are not designed for them.

Returns

boolean succeeded: Whether the check succeeded.

preferred_id

Mon, 01 Jan 0001 00:00:00 +0000

Returns a live unit’s preferred tactical ID.

Function

Synopsis

btech.unit.preferred_id( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

string|nil id: The ID, or nil when unset.

radio_channels

Mon, 01 Jan 0001 00:00:00 +0000

Lists a live unit’s configured radio channels.

Function

Synopsis

btech.unit.radio_channels( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

BtechRadioChannel[] channels: The radio-channel records.

section_condition

Mon, 01 Jan 0001 00:00:00 +0000

Returns a live unit section’s current condition.

Function

Synopsis

btech.unit.section_condition( unit, section )

Arguments

DbRef|Object unit: The live unit.
BtechSection section: A typed constant from btech.unit.sections that is valid for the unit.

Returns

"operational"|"destroyed"|"flooded" condition: "operational", "destroyed", or "flooded".

set_armor

Mon, 01 Jan 0001 00:00:00 +0000

Configures selected armor fields for one live unit section.

Function

Synopsis

btech.unit.set_armor( unit, section, patch )

Arguments

DbRef|Object unit: The live unit.
BtechSection section: A typed constant from btech.unit.sections that is valid for the unit.
table patch: One or more of armor, internal, and rear_armor.

Returns

None.

Notes

Every supplied value must be an integer from 0 through 255. Each supplied value becomes both the section’s current and original value. rear_armor remains configurable on any existing section for compatibility with stored unit data. Outside a Mech’s center, left, and right torsos, that value is inert in combat and the immediate btech.repair.apply operation refuses to change it; scheduled technician repairs may still restore the configured stored value.

set_assigned_pilot

Mon, 01 Jan 0001 00:00:00 +0000

Sets or clears a live unit’s assigned pilot.

Function

Synopsis

btech.unit.set_assigned_pilot( unit, pilot )

Arguments

DbRef|Object unit: The live unit.
DbRef|Object|nil pilot: A player to assign as the pilot, or nil to clear the assignment.

Returns

None.

set_display_name

Mon, 01 Jan 0001 00:00:00 +0000

Sets or clears a live unit’s display-name override.

Function

Synopsis

btech.unit.set_display_name( unit, name )

Arguments

DbRef|Object unit: The live unit.
string|nil name: A display name from 1 to 120 bytes, or nil to clear it.

Returns

None.

set_markings

Mon, 01 Jan 0001 00:00:00 +0000

Sets or clears a live unit’s markings.

Function

Synopsis

btech.unit.set_markings( unit, markings )

Arguments

DbRef|Object unit: The live unit.
string|nil markings: The markings as a non-empty string of at most 16,383 bytes, or nil to clear them.

Returns

None.

set_max_speed

Mon, 01 Jan 0001 00:00:00 +0000

Sets a live unit’s maximum speed.

Function

Synopsis

btech.unit.set_max_speed( unit, movement_points )

Arguments

DbRef|Object unit: The live unit.
number movement_points: The new maximum speed in movement points, from 0 to 10000.

Returns

None.

Notes

After setting the limit, this function corrects the unit’s movement state. If necessary, it immediately clamps the desired and current speeds to the new maximum and recalculates cargo weight.

set_preferred_id

Mon, 01 Jan 0001 00:00:00 +0000

Sets or clears a live unit’s preferred tactical ID.

Function

Synopsis

btech.unit.set_preferred_id( unit, id )

Arguments

DbRef|Object unit: The live unit.
string|nil id: Exactly two ASCII letters, or nil to clear the tactical ID. Letters are stored in uppercase.

Returns

None.

set_tonnage

Mon, 01 Jan 0001 00:00:00 +0000

Sets a live unit’s tonnage and original weight.

Function

Synopsis

btech.unit.set_tonnage( unit, tons )

Arguments

DbRef|Object unit: The live unit.
integer tons: The tonnage, from 1 through 2,097,151 (INT_MAX / 1024).

Returns

None.

technologies

Mon, 01 Jan 0001 00:00:00 +0000

Lists a live unit’s configured and inferred technologies.

Function

Synopsis

btech.unit.technologies( unit )

Arguments

DbRef|Object unit: The live unit.

Returns

BtechTechnology[] technologies: The technology records. code is a typed constant from btech.unit.technology, group is one of the literal strings primary, secondary, or infantry, and name remains a human-readable string. The code round-trips into add_technology and remove_technology; group describes the technology catalog and is not a btech.unit.technology_groups clear-operation constant.

tic_weapons

Mon, 01 Jan 0001 00:00:00 +0000

Lists the weapons assigned to a target-interlock circuit.

Function

Synopsis

btech.unit.tic_weapons( unit, tic )

Arguments

DbRef|Object unit: The live unit.
integer tic: The zero-based circuit number, from 0 through 3.

Returns

BtechMountedWeapon[] weapons: The assigned mounted weapons.

Unit administration

Mon, 01 Jan 0001 00:00:00 +0000

These functions configure live units using typed constants and request tables. Raw strings are rejected for sections, unit and movement types, technologies, technology groups, and fire or ammunition modes.

restore

btech.unit.restore(unit)

Loads the unit’s model template, cancels its events, and clears line-of-sight state.

save_template

btech.unit.save_template(unit, reference)

Saves the unit beneath the configured template directory. reference must be a non-empty resource name without path components.

effective_max_speed_kph

local speed = btech.unit.effective_max_speed_kph(unit)

Returns effective maximum speed in kilometers per hour.

weapons

Mon, 01 Jan 0001 00:00:00 +0000

Lists the weapons mounted on a live unit.

Function

Synopsis

btech.unit.weapons( unit, section )

Arguments

DbRef|Object unit: The live unit.
BtechSection|nil section: An optional typed constant from btech.unit.sections that is valid for the unit.

Returns

BtechMountedWeapon[] weapons: The mounted weapons. Each section field is a typed BtechSection constant and can be reused as an input.

btech.unit on StompyMUX Documentation

apply_damage

Function

Synopsis

Arguments

armor

Function

Synopsis

Arguments

Returns

Notes

assigned_pilot

Function

Synopsis

Arguments

Returns

See Also

battle_value

Function

Synopsis

Arguments

Returns

See Also

btech.unit.ammunition_modes

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.unit.fire_modes

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.unit.movement_types

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.unit.sections

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.unit.technology

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.unit.technology_groups

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.unit.types

Function

Synopsis

Arguments

Returns

Raises

Notes

critical_slots

Function

Synopsis

Arguments

Returns

See Also

display_name

Function