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.

Destructive-command lock

Modernize, Dismantle, and Transfer are state-changing at turn cutoff: the engine moves the group into 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 three 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 (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.

Send, Load, Unload, Split, and Join Fleet do not lock the group: Send is naturally followed by an out-of-orbit state at turn cutoff (the engine's busy check fires next turn anyway), and the other 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.

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.