btech.autopilot package on StompyMUX Documentation

add_order

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

Appends one validated typed order to an autopilot queue.

Function

Synopsis

btech.autopilot.add_order( autopilot, order )

Arguments

DbRef|Object autopilot: A registered BattleTech autopilot.
BtechAutopilotOrder order: One of the strict shapes below. No additional fields are accepted.

The name field must come from btech.autopilot.orders. Directions and modes use the corresponding typed constant namespaces.

{ name = orders.CHASE_TARGET|orders.DUMB_FOLLOW|orders.FOLLOW|orders.EMBARK|orders.PICK_UP, target = unit }
{ name = orders.DUMB_GOTO|orders.GOTO|orders.OLD_GOTO, x = 0..2147483647, y = 0..2147483647 }
{ name = orders.ENTER_BASE, direction = directions.NORTH|directions.EAST|directions.SOUTH|directions.WEST }
{ name = orders.LEAVE_BASE, heading = 0..359 }
{ name = orders.ROAM, mode = roam_modes.MAP }
{ name = orders.ROAM, mode = roam_modes.RADIUS, x = 0..2147483647, y = 0..2147483647, radius = 1..30 }
{ name = orders.AUTO_GUN, mode = autogun_modes.AUTOMATIC|autogun_modes.OFF }
{ name = orders.AUTO_GUN, mode = autogun_modes.TARGET, target = unit }
{ name = orders.DROP_OFF|orders.SHUT_DOWN|orders.START_UP|orders.UNIT_DISEMBARK }
{ name = orders.SPEED, percent = 1..100 }

Here orders, directions, roam_modes, and autogun_modes abbreviate their namespaces beneath btech.autopilot; they are not raw strings.

btech.autopilot.autogun_modes

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

btech.autopilot.autogun_modes is an immutable namespace of typed BtechAutopilotAutogunMode constants used by AUTO_GUN orders.

Function

Synopsis

btech.autopilot.autogun_modes.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechAutopilotAutogunMode constant: The typed automatic-gunnery mode represented by CONSTANT.

Raises

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

Notes

Constants belong to their namespace and the Lua runtime that created them.

Constant	Behavior
`AUTOMATIC`	Select targets automatically.
`OFF`	Disable automatic gunnery.
`TARGET`	Attack the supplied target unit.

Repeated lookups of the same mode compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups and attempts to modify a constant or the namespace raise mux.arg.invalid. Raw strings, constants of another kind, and values from another Lua runtime are rejected.

btech.autopilot.directions

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

btech.autopilot.directions is an immutable namespace of typed BtechAutopilotDirection constants used by ENTER_BASE orders.

Function

Synopsis

btech.autopilot.directions.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechAutopilotDirection constant: The typed direction represented by CONSTANT.

Raises

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

Notes

Constants belong to their namespace and the Lua runtime that created them.

Constant	Direction
`NORTH`	North.
`EAST`	East.
`SOUTH`	South.
`WEST`	West.

Repeated lookups of the same direction compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups and attempts to modify a constant or the namespace raise mux.arg.invalid. Raw strings, constants of another kind, and values from another Lua runtime are rejected.

btech.autopilot.orders

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

btech.autopilot.orders is an immutable namespace of typed BtechAutopilotOrderName constants. Use these values as the name discriminator accepted by add_order; raw strings are rejected.

Function

Synopsis

btech.autopilot.orders.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechAutopilotOrderName constant: The typed order name represented by CONSTANT.

Raises

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

Notes

Constants belong to their namespace and the Lua runtime that created them.

Constant	Order
`CHASE_TARGET`	Chase a target unit.
`DUMB_FOLLOW`	Follow a target without pathfinding.
`FOLLOW`	Follow a target using normal navigation.
`EMBARK`	Embark into a target unit.
`PICK_UP`	Pick up a target unit.
`DUMB_GOTO`	Move directly to map coordinates.
`GOTO`	Navigate to map coordinates.
`OLD_GOTO`	Use the legacy coordinate-navigation behavior.
`ENTER_BASE`	Enter a base from a direction.
`LEAVE_BASE`	Leave a base on a heading.
`ROAM`	Roam a map or radius.
`AUTO_GUN`	Configure automatic gunnery.
`DROP_OFF`	Drop off a carried unit.
`SHUT_DOWN`	Shut down the associated unit.
`START_UP`	Start the associated unit.
`UNIT_DISEMBARK`	Disembark the associated unit.
`SPEED`	Set the desired speed percentage.

Repeated lookups of the same order compare equal and stringify to their uppercase key; other values, constant kinds, and runtimes compare unequal. Unknown lookups and attempts to modify a constant or the namespace raise mux.arg.invalid. Constants belong to their namespace and current Lua runtime; a raw string or a different kind of BTech constant is rejected.

btech.autopilot.roam_modes

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

btech.autopilot.roam_modes is an immutable namespace of typed BtechAutopilotRoamMode constants used by ROAM orders.

Function

Synopsis

btech.autopilot.roam_modes.CONSTANT

Arguments

This namespace takes no arguments.

Returns

BtechAutopilotRoamMode constant: The typed roaming mode represented by CONSTANT.

Raises

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

Notes

Constants belong to their namespace and the Lua runtime that created them.

Constant	Behavior
`MAP`	Roam across the current map.
`RADIUS`	Roam within a radius of the supplied coordinates.

clear_orders

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

Clears an autopilot’s order queue atomically when safe.

Function

Synopsis

btech.autopilot.clear_orders( autopilot )

Arguments

DbRef|Object autopilot: A registered BattleTech autopilot.

Returns

None.

Raises

mux.object.invalid or mux.object.unavailable for an invalid autopilot.
btech.operation.failed with reason active_order if the engaged queue is nonempty.

Notes

Failure leaves the entire queue unchanged. Disengage first to preserve safety when clearing a nonempty active queue.

disengage

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

Stops an engaged autopilot without discarding its association or orders.

Function

Synopsis

btech.autopilot.disengage( autopilot )

Arguments

DbRef|Object autopilot: A registered BattleTech autopilot.

Returns

None.

Raises

mux.object.invalid or mux.object.unavailable for an invalid autopilot.
btech.operation.failed with reason already_disengaged.

Notes

The associated unit and full queue remain intact. The authoritative engagement boolean is saved exactly in version 8 snapshots.

engage

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

Associates and engages an autopilot installed in a unit.

Function

Synopsis

btech.autopilot.engage( autopilot )

Arguments

DbRef|Object autopilot: A registered BattleTech autopilot physically contained by a registered unit.

Returns

None.

Raises

mux.object.invalid or mux.object.unavailable for an invalid autopilot.
btech.operation.failed with reason not_installed_in_unit, already_engaged, or association_conflict.

Notes

Another autopilot cannot claim the same unit, and a valid backlink to another unit is a conflict. Only unambiguous stale cached associations are repaired. Engagement is persisted explicitly in version 8 snapshots. Version 6 and 7 snapshots infer it once from the autogun or zombie flags, or from matching physical containment and backlinks when the queue is nonempty; subsequent saves use version 8. The guarded offline migration at game/data/migrations/btech-persistence-v8.sql applies the same inference. Stop the server and back up a populated database before running it.

event_stats

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

Counts pending events associated with an autopilot.

Function

Synopsis

local stats = btech.autopilot.event_stats( autopilot )

Arguments

DbRef|Object autopilot: A registered BattleTech autopilot.

Returns

BtechAutopilotEventStats: A fresh table with integer fields goto, leave, command, autogun, sensor, follow, enter_base, reply, profile, roam, and total. Every category is present, including zero counts.

Raises

mux.object.invalid if the object is not a registered autopilot.
mux.object.unavailable if its runtime state is unavailable.

Notes

The result is a snapshot; later event scheduling does not mutate it.

remove_order

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

Removes one queued autopilot order.

Function

Synopsis

btech.autopilot.remove_order( autopilot, position )

Arguments

DbRef|Object autopilot: A registered BattleTech autopilot.
integer position: The one-based queue position, from 1 through 100.

Returns

None.

Raises

mux.arg.invalid if position is not an integer in range.
mux.object.invalid or mux.object.unavailable for an invalid autopilot.
btech.operation.failed with reason active_order when position 1 is protected or order_not_found when no such position exists.

Notes

Position 1 is protected whenever an engaged autopilot has queued orders. Later pending orders can still be removed.

status

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

Returns a fresh structured snapshot of an autopilot.

Function

Synopsis

local status = btech.autopilot.status( autopilot )

Arguments

DbRef|Object autopilot: A registered BattleTech autopilot.

Returns

BtechAutopilotStatus: A new table containing optional Object fields container_unit, associated_unit, and map; association (none, ready, associated, or conflict); engaged; speed_percent; order_count; order_capacity (always 100); a dense typed orders array; and modes.

The modes are autogun_enabled, autogun_suspended, piloting_suspended, roaming, manual_sensors, chasing_target, chase_resume_pending, swarm_charging, and assigned_target, all booleans.

Raises

mux.object.invalid if the object is not a registered autopilot or a stored object relationship is corrupt.
mux.object.unavailable if its runtime state is unavailable.
btech.operation.failed with reason invalid_order_queue if stored orders cannot be decoded safely.

Notes

Each call returns new tables. Object relationships are native Object handles, not numeric database references; absent relationships are nil. Order name, direction, and mode fields are typed constants from the corresponding btech.autopilot namespaces. They compare and stringify like the input constants and can be passed back to add_order without conversion.

btech.autopilot package on StompyMUX Documentation

add_order

Function

Synopsis

Arguments

btech.autopilot.autogun_modes

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.autopilot.directions

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.autopilot.orders

Function

Synopsis

Arguments

Returns

Raises

Notes

btech.autopilot.roam_modes

Function

Synopsis

Arguments

Returns

Raises

Notes

clear_orders

Function

Synopsis

Arguments

Returns

Raises

Notes

See Also

disengage

Function

Synopsis

Arguments

Returns

Raises

Notes

See Also

engage

Function

Synopsis

Arguments

Returns

Raises

Notes

event_stats

Function

Synopsis

Arguments

Returns

Raises

Notes

remove_order

Function

Synopsis

Arguments

Returns

Raises

Notes

status

Function

Synopsis

Arguments

Returns

Raises

Notes