btech package

require("btech") returns the built-in BattleTech API. It is available to running Lua callbacks, but not during @lua/check. The package adapts the server’s trusted BattleTech scripting handlers to Lua and invokes them with server authority.

Arguments use Lua strings, numbers, and booleans; object arguments are native dbrefs rather than Object handles. Invalid objects, arguments, or legacy error results raise Lua errors. Successful results are converted to the type documented for each function. Mutation-only operations return true. List operations split the legacy result on whitespace and |, convert numeric tokens (including #123) to Lua numbers, and return a flat array.

Functions

Unit data

Function	Description
`btech.armor_status`	Returns serialized armor values for one section of a live unit.
`btech.armor_status_ref`	Returns serialized armor values for one section of a unit template.
`btech.crit_slot`	Describes one critical slot on a live unit.
`btech.crit_slot_ref`	Describes one critical slot in a unit template.
`btech.section_status`	Returns serialized status for one section of a live unit.
`btech.crit_status`	Returns serialized critical-slot status for one section of a live unit.
`btech.crit_status_ref`	Returns serialized critical-slot status for one section of a unit template.
`btech.damage_mech`	Applies clustered damage to a live unit.
`btech.damages`	Returns the formatted repair-job description for a live unit.
`btech.engine_rating`	Returns the engine rating of a live unit.
`btech.engine_rating_ref`	Returns the engine rating of a unit template.
`btech.real_max_speed`	Returns a live unit’s effective maximum speed.
`btech.get_weight`	Returns a part’s weight in tons.
`btech.payload_ref`	Returns the weapon and ammunition payload of a unit template.
`btech.show_crit_status_ref`	Sends a template’s critical-status display to a player.
`btech.show_status_ref`	Sends a unit template’s status display to a player.
`btech.show_weapon_specs_ref`	Sends a unit template’s weapon-specification display to a player.
`btech.threshold`	Returns the configured experience threshold for a skill.
`btech.tic_weapons`	Lists the weapons assigned to a unit’s target-interlock circuit.
`btech.weapon_status`	Returns serialized weapon status for a live unit or one section.
`btech.weapon_status_ref`	Returns serialized weapon status for a unit template or one section.
`btech.weapon_stat`	Returns one numeric weapon-catalog statistic as text.

Unit mutation and loading

Function	Description
`btech.xcode_value`	Reads a script-visible native field from a live special object.
`btech.xcode_value_ref`	Reads a script-visible native field from a unit template.
`btech.load_map`	Loads a map file into a map object and clears its units and map objects.
`btech.load_mech`	Loads a unit template into a live unit object.
`btech.set_armor_status`	Sets one armor-status field on a live unit section.
`btech.set_max_speed`	Sets a live unit’s maximum speed and corrects its current speed.
`btech.set_tons`	Sets a live unit’s tonnage and original weight.
`btech.set_xcode_value`	Writes a script-writable native field on a live special object.
`btech.set_xy`	Places a live unit on a map at specified coordinates.
`btech.update_links`	Recursively updates links associated with a map.

Maps and geometry

Function	Description
`btech.range`	Calculates distance between units or map coordinates.
`btech.hex_emit`	Broadcasts a message from one map hex.
`btech.hex_in_blast_zone`	Tests whether a map hex lies in a configured blast zone.
`btech.hex_line_of_sight`	Tests whether a live unit has unobstructed line of sight to a map hex.
`btech.blast_zones`	Lists blast-zone coordinates and radii on a map.
`btech.mech_line_of_sight`	Tests line of sight between two live units.
`btech.map_elevation`	Returns the elevation of a map hex.
`btech.map_emit`	Broadcasts a message to all or nearby units on a map.
`btech.map_terrain`	Returns the terrain code of a map hex.
`btech.map_units`	Lists all units on a map or those within a 2D or 3D range.

Parts, stores, and economy

Function	Description
`btech.add_stores`	Adds a quantity of a part to an object’s stores.
`btech.fasa_base_cost_ref`	Calculates the FASA base cost of a unit template.
`btech.battle_value`	Calculates the battle value of a live unit.
`btech.battle_value_ref`	Calculates the battle value of a unit template.
`btech.battle_value2_ref`	Calculates the second-generation battle value of a unit template.
`btech.defensive_battle_value_ref`	Calculates the defensive battle-value component of a unit template.
`btech.offensive_battle_value_ref`	Calculates the offensive battle-value component of a unit template.
`btech.part_cost`	Returns the configured cost of a part.
`btech.part_type`	Returns the broad category of a part.
`btech.part_match`	Finds packed part IDs whose names match a string.
`btech.part_name`	Returns a name for a packed part ID.
`btech.part_categories`	Lists the canonical categories accepted by `btech.parts`.
`btech.parts`	Lists canonical long part names in one category.
`btech.part_weight`	Returns a part’s weight in tons.
`btech.remove_stores`	Removes a quantity of a part from an object’s stores.
`btech.set_part_cost`	Sets the configured cost of a part.
`btech.stores`	Returns a part quantity or lists an object’s stored parts.
`btech.stores_short`	Returns a part quantity or lists stored parts using short names.
`btech.unit_fixable`	Tests whether a live unit can be repaired.
`btech.unit_parts`	Lists the parts installed on a live unit.
`btech.unit_parts_ref`	Lists the parts installed in a unit template.

Characters and repair

Function	Description
`btech.char_list`	Lists character value names in a requested category.
`btech.char_value`	Gets a character attribute, skill level, target, experience, or experience threshold.
`btech.make_pilot_roll`	Makes a piloting roll and causes a fall when it fails.
`btech.repair_job_count`	Returns the number of pending repair jobs on a live unit.
`btech.set_char_value`	Sets a character value or adjusts skill experience.
`btech.tech_list`	Lists the parts needed to repair a live unit.
`btech.tech_list_ref`	Lists the parts needed to repair a unit template.
`btech.tech_status`	Returns formatted repair status for a live unit.
`btech.tech_time`	Runs the legacy technician-time query.
`btech.under_repair`	Tests whether a live unit has an active repair event.

Utilities

Function	Description
`btech.design_exists`	Tests whether a unit template exists.
`btech.id_to_dbref`	Resolves a two-character tactical ID on a unit’s map.
`btech.lag`	Returns the current BattleTech event lag.
`btech.mech_frequencies`	Lists the configured radio channels of a live unit.
`btech.zone_mechs`	Lists live unit objects assigned to a zone.