Orders

Who can be given which order - decided by what the object can actually do. The comms "Can order" chip, the right-click popup and drag all ask this one module, so they cannot disagree about a unit.

An order is a MAST objective label whose type starts with objective/orders/. The label says what it needs and what it may be aimed at:

=== objective_escort
metadata: ```
display_name: Escort
type: objective/orders/move/escort
valid_for: allies
requires: move
```

Capabilities

Capability	An object has it when
move	it was not spawned behav_station or behav_selection
weapons	it is a turret, carries turret mounts, or is a mobile hull with beams or torpedo tubes (a stock-hull behav_station never fires - engine-measured)
anything else	an addon supplies it through orders_caps_provider(fn) - LegendaryMissions' hangar adds launch, wing_out, wing_delegable, wing_delegated

A mission overrides per object with orders_caps_set(obj, add=..., remove=...). The no_orders role blocks everything - use it for a story ship.

valid_for

Value	Accepts
self	no target, or the unit itself
allies	the unit's own side or an allied one
hostile	any other ship
marker	a marker object (the marker role - see markers)
point	an empty spot in space
any	any target but itself

Several may be listed: valid_for: allies, marker.

One menu entry per instance

orders_items(origin, selected, target) returns (label, instance, text) entries. An order whose label names instances: <function> appears once per instance the function returns - LegendaryMissions uses it so one "Launch @" label becomes "Launch Red wing (4/4)" and "Launch Gold wing (4/4)". The chosen key reaches the objective as order_instance.

Stance

orders_stance_set(obj, "hold" | "free") - hold fire or weapons free. A host passes it on to its turret mounts. turret_acquire honors it, and an explicit designation (a "Fire on" order) still stands during hold fire.

API

Who can be given which ORDERS - decided by what the object can actually do.

An order is a MAST objective label under objective/orders/ (the menus and drag routes build their buttons from them). This module answers the two questions every one of those menus asks, in ONE place, so the comms chip, the right-click popup and drag can never disagree:

orders_available(origin, selected, target)   the order labels that apply
orders_can_take(origin, selected)            is there any at all?

It used to be one role and one order set, so an allied STATION was offered "Head to location" and "Attack" - orders it has no engine, and on a stock hull no guns, to carry out. Now each order label says what it NEEDS, and each object says what it HAS:

requires: move, weapons        # order label metadata

CAPABILITIES are a small fixed vocabulary:

move      anything not spawned behav_station / behav_selection
weapons   a turret, a host with turret mounts, or a MOBILE hull with beams or tubes
          (engine-measured: a behav_station on a stock hull never fires)
launch    supplied by a provider (the hangar addon knows what is docked where)

Derived defaults, then per-object overrides (orders_caps_set), and the no_orders role still blocks everything.

give_orders_type on the object NARROWS the set by label-type prefix, so a ship class can have its own order set (objective/orders/escort) without a new capability.

STANCE (weapons free / hold fire) is stored here too, because both the turret brain in this library and the chase brains in a mission read it.

orders_available(origin, selected, target=None, labels=None, at_point=False)

The order labels origin may give selected, aimed at target.

target None (or selected itself) asks for the orders it gives ITSELF - full stop, hold fire - unless at_point says it is an empty spot in space, which only point and any orders accept. labels overrides the story lookup, for tests.

Returns [] when the origin may not command it at all.

orders_can_take(origin, selected, labels=None)

Does selected have ANY order origin could give it? What the "Can order" chip, the comms enable route and drag all ask. Ignores the target - any target will do.

orders_caps(obj)

The set of capabilities an object has: derived, then overridden.

Returns an empty set for a missing object.

orders_caps_provider(fn)

Register fn(obj_id) -> iterable of capability names, added to every object's derived set. How an addon contributes a capability this library cannot see (what craft are docked at a station). Idempotent. Returns fn so it works as a decorator.

orders_caps_set(obj, add=None, remove=None)

Override an object's capabilities. add/remove are a name, a comma string or a list; each call REPLACES the previous override of that kind. Pass "" to clear one.

orders_caps_set(freighter_id, remove="weapons")   # armed, but will not fight
orders_caps_set(platform_id, add="weapons")       # a hull this library misreads

orders_holding_fire(obj)

True while an object is ordered to hold fire.

orders_items(origin, selected, target=None, labels=None, at_point=False)

The menu entries for selected aimed at target: [(label, instance, text)].

Most orders are one entry, with instance None. An order whose label names an instances: provider - a function fn(selected_id, label) -> [(key, text)] - is one entry PER INSTANCE, so a station with two wings offers "Launch Red wing" and "Launch Gold wing" from a single label. The provider also decides which instances apply right now; an order with none is left off the menu. The chosen instance key travels to the objective as order_instance.

orders_may_command(origin, selected)

May origin give orders to selected AT ALL - before asking what it can do?

Not no_orders; then the defender role, or an NPC on the origin's own side or an allied one.

orders_mounted_turrets(obj)

The turret mounts welded to a host - where a STATION's weapon orders go.

orders_set_prefix(obj)

The label-type prefix an object's orders come from: its give_orders_type, or every order.

orders_stance(obj)

"free" (the default) or "hold".

orders_stance_set(obj, stance)

Weapons free or hold fire. A host passes it on to its turret mounts, since they are what does its shooting. Returns the stance set, or None for a bad value.