developer/galaxy-game
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

ui/phase-20: ship-group inspector actions

Browse Source 
Eight ship-group operations land on the inspector behind a single
inline-form panel: split, send, load, unload, modernize, dismantle,
transfer, join fleet. Each action either appends a typed command to
the local order draft or surfaces a tooltip explaining the
disabled state. Partial-ship operations emit an implicit
breakShipGroup command before the targeted action so the engine
sees a clean (Break, Action) pair on the wire.

`pkg/calc.BlockUpgradeCost` migrates from
`game/internal/controller/ship_group_upgrade.go` so the calc
bridge can wrap a pure pkg/calc formula; the controller now
imports it. The bridge surfaces the function as
`core.blockUpgradeCost`, which the inspector calls once per ship
block to render the modernize cost preview.

`GameReport.otherRaces` is decoded from the report's player block
(non-extinct, ≠ self) and feeds the transfer-to-race picker. The
planet inspector's stationed-ship rows become clickable for own
groups so the actions panel is reachable from the standard click
flow (the renderer continues to hide on-planet groups).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Ilia Denisov
2026-05-10 16:27:55 +02:00
parent f7109af55c
commit 3626998a33
36 changed files with 4033 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ui/docs/calc-bridge.md
+24 -18
View File
@@ -9,30 +9,33 @@ Go → WASM → TypeScript bridge mounted under `ui/core/calc/` and a
matching TS adapter in `ui/frontend/src/platform/core/`.
Phase 18 lands the **ship-math slice** of the bridge — everything
the ship-class designer needs to render its preview pane. Other
slices (production forecast, science research, ship build progress)
remain deferred to dedicated future phases. This document is the
running audit trail of what is live, what is missing, and how each
function maps to its `pkg/calc/` source.
the ship-class designer needs to render its preview pane. Phase 20
extends it with `BlockUpgradeCost` so the ship-group inspector can
preview modernize cost. Other slices (production forecast, science
research, ship build progress) remain deferred to dedicated future
phases. This document is the running audit trail of what is live,
what is missing, and how each function maps to its `pkg/calc/`
source.
## Live bridge surface (Phase 18)
## Live bridge surface
The Go module `galaxy/core/calc` (`ui/core/calc/ship.go`) exposes
seven thin wrappers around `pkg/calc/ship.go`. Each is a one-line
passthrough — the bridge contains zero math. The same seven names
appear on the JS-side `globalThis.galaxyCore` (registered in
thin wrappers around `pkg/calc/ship.go`. Each is a one-line
passthrough — the bridge contains zero math. The same names appear
on the JS-side `globalThis.galaxyCore` (registered in
`ui/wasm/main.go`) and on the typed `Core` interface
(`ui/frontend/src/platform/core/index.ts`).
| Bridge function | `pkg/calc/` source | JS return shape | Used by |
| ------------------ | --------------------------------------------------- | --------------- | -------------------------------- |
| `driveEffective` | `calc.DriveEffective(drive, driveTech)` | `number` | designer preview (`Speed` input) |
| `emptyMass` | `calc.EmptyMass(drive, weapons, armament, …)` | `number\|null` | designer preview (mass row) |
| `weaponsBlockMass` | `calc.WeaponsBlockMass(weapons, armament)` | `number\|null` | reserved for future stages |
| `fullMass` | `calc.FullMass(emptyMass, carryingMass)` | `number` | designer preview (full-load row) |
| `speed` | `calc.Speed(driveEffective, fullMass)` | `number` | designer preview (speed + range) |
| `cargoCapacity` | `calc.CargoCapacity(cargo, cargoTech)` | `number` | designer preview (cargo row) |
| `carryingMass` | `calc.CarryingMass(load, cargoTech)` | `number` | designer preview (full-load mass)|
| Bridge function | `pkg/calc/` source | JS return shape | Used by |
| ------------------- | -------------------------------------------------------- | --------------- | ---------------------------------------- |
| `driveEffective` | `calc.DriveEffective(drive, driveTech)` | `number` | designer preview (`Speed` input) |
| `emptyMass` | `calc.EmptyMass(drive, weapons, armament, …)` | `number\|null` | designer preview (mass row) |
| `weaponsBlockMass` | `calc.WeaponsBlockMass(weapons, armament)` | `number\|null` | designer preview, modernize cost preview |
| `fullMass` | `calc.FullMass(emptyMass, carryingMass)` | `number` | designer preview (full-load row) |
| `speed` | `calc.Speed(driveEffective, fullMass)` | `number` | designer preview (speed + range) |
| `cargoCapacity` | `calc.CargoCapacity(cargo, cargoTech)` | `number` | designer preview (cargo row) |
| `carryingMass` | `calc.CarryingMass(load, cargoTech)` | `number` | designer preview (full-load mass) |
| `blockUpgradeCost` | `calc.BlockUpgradeCost(blockMass, currentTech, target)` | `number` | ship-group inspector modernize preview |
`number|null` returns mirror the Go `(float64, bool)` signature: the
upstream validator rejects weapons/armament pairings with one zero
@@ -64,6 +67,8 @@ waivers below for the rationale on each deferral.
| `ShipProductionCost(shipEmptyMass float64) float64` | Production units required per unit of ship empty mass (×10). |
| `PlanetProduceShipMass(L, Mat, Res float64) float64` | Ship mass produced per turn given free production `L`, material stockpile `Mat`, resources `Res`.|
| `DriveEffective`, `Speed`, `EmptyMass`, `FullMass`, … | Ship-level derivations (`pkg/calc/ship.go`). |
| `BlockUpgradeCost(blockMass, currentTech, target)` | Production cost of upgrading a single ship block (Phase 20 migrated this from `controller`). |
| `FligthDistance(driveTech)`, `VisibilityDistance(...)` | Race-level reach formulas (`pkg/calc/race.go`). |
| `ValidateShipTypeValues`, `CheckShipTypeValueDWSC` | Ship-design validators (`pkg/calc/validator.go`). |
Nothing else lives in `pkg/calc/` today. Production-side formulas
@@ -79,6 +84,7 @@ whether the underlying Go function exists.
| UI feature | Go formula | In `pkg/calc/`? | Surfaced to TS? |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | :-------------: | :-------------: |
| Ship-class designer preview (Phase 18) | `EmptyMass`, `FullMass`, `Speed`, `DriveEffective`, `CargoCapacity`, `CarryingMass`, `WeaponsBlockMass` (`pkg/calc/ship.go`) | yes | yes |
| Ship-group modernize cost preview (Phase 20) | `BlockUpgradeCost` (`pkg/calc/ship.go`, migrated from `game/internal/controller/ship_group_upgrade.go`) | yes | yes |
| Free production potential (`freeIndustry`) | `Planet.ProductionCapacity` → `industry*0.75 + population*0.25` (`game/internal/model/game/planet.go`) | no | no |
| Industry production output per turn | `Planet.ProduceIndustry(freeProduction)` (`planet.go`); `freeProduction/5` modulo material constraint | no | no |
| Materials production output per turn | `Planet.ProduceMaterial(freeProduction)` (`planet.go`); `freeProduction * resources` | no | no |
ui/docs/ship-group-actions.md
+151
View File
@@ -0,0 +1,151 @@
# 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.
- **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.
## 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.