galaxy-game/ui/docs/ship-group-actions.md

Ship-group inspector actions

Phase 20 turns the read-only ship-group inspector (ui/frontend/src/lib/inspectors/ship-group.svelte) into an interactive command source for the player's own groups in orbit. This document is the running spec for the actions panel (ui/frontend/src/lib/inspectors/ship-group/actions.svelte): which actions exist, what gates each one, how partial-ship operations split a group on the fly, and what the modernize cost preview shows.

Reaching a group

The map renderer hides on-planet ship groups to avoid crowding the canvas. The player reaches an own on-planet group through the planet inspector's stationed ship groups subsection: clicking a row pivots the SelectionStore to the matching shipGroup.local ref, the sidebar swaps from the planet inspector to the ship-group inspector, and the actions panel mounts. In-flight (in-space) groups appear as map primitives and can be selected by clicking the rendered point.

Action surface

Action	Implicit-split?	Partial input	FBS payload	Engine reference
Split	—	ships count	CommandShipGroupBreak	controller/ship_group.go.breakGroup
Send	yes	ships count + destination	CommandShipGroupSend	controller/ship_group_send.go.shipGroupSend
Load	yes	ships count + cargo + quantity	CommandShipGroupLoad	controller/ship_group.go.shipGroupLoad
Unload	yes	ships count + quantity	CommandShipGroupUnload	controller/ship_group.go.shipGroupUnload
Modernize	yes	ships count + tech + level	CommandShipGroupUpgrade	controller/ship_group_upgrade.go.shipGroupUpgrade
Dismantle	yes	ships count + foreign-COL confirm	CommandShipGroupDismantle	controller/ship_group.go.shipGroupDismantle
Transfer	yes	ships count + acceptor race	CommandShipGroupTransfer	controller/ship_group.go.shipGroupTransfer
Join Fleet	—	fleet name (existing or new)	CommandShipGroupJoinFleet	controller/fleet.go.ShipGroupJoinFleet

"Implicit-split" means the inspector accepts a number of ships M < N and emits a CommandShipGroupBreak(id, newId, M) command before the action command, then targets the action at the freshly-minted newId. The FBS schema only carries a per-ship quantity on CommandShipGroupBreak; every other ship-group command applies to the whole group, so the implicit-split pattern is the only way to act on a subset without forcing the player to pre-split manually. Acceptance criteria: "splitting a group of N into K and N-K results in two valid commands" — that is exactly the (Break, Action) pair this pipeline emits.

Split and Join Fleet do not accept a partial ship count: Split is the break operation; Join Fleet attaches the whole group atomically (the engine handles a partial detach by issuing Split first, which the player drives explicitly).

Disabled-state rules

The inspector mirrors the engine's pre-conditions per command (see the references column above) and surfaces each as a disabled-button tooltip. Any state other than In_Orbit disables every action with ships are busy ({state}). Per-action gates:

• Send: requires the ship class to have a non-zero drive block (controller/ship_group_send.go:32); the picker pre-filters destinations by reach (localPlayerDrive * 40), so a valid pick is always within range. With no reachable planet, the action is disabled with the "no planets in drive range" tooltip. Click drops the inspector straight into map-pick mode; the form (ship count + confirm) appears only after the player chooses a destination — there is no destination control inside the form, so cancelling the picker leaves the inspector untouched.
• Load: requires the orbit planet to be owned by the player or unowned (controller/ship_group.go:215) and the ship class to have a cargo block (shipGroupLoad:220). The dropdown is pinned to the existing cargo type when the group is already partially loaded (the engine refuses cargo-type changes at shipGroupLoad:223).
• Unload: requires non-empty cargo. Colonists (COL) over a foreign planet are blocked (shipGroupUnload:283), with the matching tooltip in the disabled state.
• Modernize: requires the orbit planet to be own/unowned (shipGroupUpgrade:29) and at least one block whose race tech exceeds the group tech (otherwise nothing can be upgraded).
• Dismantle: always available in orbit. When the orbit is over a foreign planet AND the group carries colonists, the inline form replaces the normal "confirm" with "confirm — colonists die"; the player has to click twice to commit (engine reference shipGroupDismantle:177-179 — over a foreign planet, UnloadColonists is not called and the cargo is lost).
• Transfer: requires at least one non-extinct race other than the local player (sourced from GameReport.otherRaces).
• Join Fleet: existing-fleet picker is restricted to fleets in the same orbit (fleet.go:135-137); creating a new fleet always works.

State-changing-command lock

Send, Modernize, Dismantle, and Transfer are state-changing at turn cutoff: the engine moves the group into StateLaunched, StateUpgrade, removes it, or marks it StateTransfer respectively. Issuing a follow-up action against the same group during the same draft window would race the engine's pre-condition check, so the inspector locks the group as soon as one of the four commands lands in the draft for that groupId:

• every action button on the group's inspector becomes disabled with the "an order is already queued" tooltip;
• a banner above the buttons row names the queued command (send / modernize / dismantle / transfer) and tells the player to cancel it in the order list to issue something else;
• removing the queued entry from the order tab releases the lock on the next render — the derivation watches draft.commands directly.

Load, Unload, Split, and Join Fleet do not lock the group: those four can stack legitimately during the same window. The group continues to appear in the planet inspector's stationed-ship list while locked — the player can still navigate to the inspector to read the state and find the order to cancel.

Map overlays for in-flight and pending-Send groups

Two dashed-line overlays run on the same renderer layer as the cargo-route arrows:

• Yellow dashed track for own ship groups currently in hyperspace, drawn from the origin planet to the destination (matches the colour of the in-space group point so the eye reads both as one entity).
• Green dashed track for every wire-valid sendShipGroup command in the order draft — drawn from the source group's orbit planet to the chosen destination. Disappears when the command is removed from the order tab, when the engine flips it rejected / invalid, or when the group has left orbit (the Send was applied and the in-space track replaces it).

Both tracks are wrap-aware via torusShortestDelta so a route across the seam takes the wrap. Neither participates in hit-test — the player still picks ship groups by clicking the group point, not the track.

Modernize cost preview

The form's preview line calls core.blockUpgradeCost({ blockMass, currentTech, targetTech }) once per ship block (drive, weapons, shields, cargo) and sums the per-ship totals before multiplying by the targeted ship count. Block masses come from the player's ShipClassSummary for the group's class:

• Drive / shields / cargo block mass = the corresponding ship- class field (raw value).
• Weapons block mass = core.weaponsBlockMass({ weapons, armament }) (Phase 18 bridge); returns null on the invalid weapons/armament pairing, in which case the row contributes zero.

For tech === "ALL" every block whose mass is non-zero contributes against the player's race tech as the target. For per-block tech (DRIVE / WEAPONS / SHIELDS / CARGO) only the chosen block contributes, with level as the target.

The preview hides when the form is invalid (tech !== "ALL" with non-positive level) or when Core has not yet booted — the bridge call is the only source of truth, so we surface "preview unavailable" rather than fall back to a JS re-implementation that could drift from the engine.

Wire shape

Every emitted command carries:

• id — client-minted UUID (crypto.randomUUID()), used by the order draft for status tracking; mirrored as CommandItem.cmdId on the wire.
• groupId — the source ship-group's UUID (or newGroupId when the action is the second half of an implicit split). On the wire it is the id field of every ship-group payload type.

Per-action additional fields are documented on the OrderCommand union in ui/frontend/src/sync/order-types.ts next to the JSDoc for each variant.

Decisions baked into Phase 20

• BlockUpgradeCost migrated to pkg/calc. The cost formula previously lived in game/internal/controller/ship_group_upgrade.go. To keep the ui/core/calc bridge a wrapper around pure pkg/calc/ formulas, the function moved to pkg/calc/ship.go and the controller now imports it (controller/ship_group_upgrade.go).
• GameReport.otherRaces. The transfer-to-race picker reads from a new GameReport.otherRaces: string[] field, populated by walking report.player[] and excluding the local race plus every extinct entry. Phase 22 (Races View) reuses the same field.
• Stationed-ship rows are clickable. The map deliberately hides on-planet groups; the planet inspector's stationed-ship rows now pivot the selection to the corresponding ship-group variant so the actions panel is reachable from the standard click flow.