ui/phase-16: cargo routes inspector + map pick foundation
Add per-planet cargo routes (COL/CAP/MAT/EMP) to the inspector with a renderer-driven destination picker (faded out-of-reach planets, cursor-line anchor, hover-highlight) and per-route arrows on the map. The pick-mode primitives are exposed via `MapPickService` so ship-group dispatch in Phase 19/20 can reuse the same surface. Pass A — generic map foundation: - hit-test now sizes the click zone to `pointRadiusPx + slopPx` so the visible disc is always part of the target. - `RendererHandle` gains `onPointerMove`, `onHoverChange`, `setPickMode`, `getPickState`, `getPrimitiveAlpha`, `setExtraPrimitives`, `getPrimitives`. The click dispatcher is centralised: pick-mode swallows clicks atomically so the standard selection consumers do not race against teardown. - `MapPickService` (`lib/map-pick.svelte.ts`) wraps the renderer contract in a promise-shaped `pick(...)`. The in-game shell layout owns the service so sidebar and bottom-sheet inspectors see the same instance. - Debug-surface registry exposes `getMapPrimitives`, `getMapPickState`, `getMapCamera` to e2e specs without spawning a separate debug page after navigation. Pass B — cargo-route feature: - `CargoLoadType`, `setCargoRoute`, `removeCargoRoute` typed variants with `(source, loadType)` collapse rule on the order draft; round-trip through the FBS encoder/decoder. - `GameReport` decodes `routes` and the local player's drive tech for the inline reach formula (40 × drive). `applyOrderOverlay` upserts/drops route entries for valid/submitting/applied commands. - `lib/inspectors/planet/cargo-routes.svelte` renders the four-slot section. `Add` / `Edit` call `MapPickService.pick`, `Remove` emits `removeCargoRoute`. - `map/cargo-routes.ts` builds shaft + arrowhead primitives per cargo type; the map view pushes them through `setExtraPrimitives` so the renderer never re-inits Pixi on route mutations (Pixi 8 doesn't support that on a reused canvas). Docs: - `docs/cargo-routes-ux.md` covers engine semantics + UI map. - `docs/renderer.md` documents pick mode and the debug surface. - `docs/calc-bridge.md` records the Phase 16 reach waiver. - `PLAN.md` rewrites Phase 16 to reflect the foundation + feature split and the decisions baked in (map-driven picker, inline reach, optimistic overlay via `setExtraPrimitives`). Tests: - `tests/map-pick-mode.test.ts` — pure overlay-spec helper. - `tests/map-cargo-routes.test.ts` — `buildCargoRouteLines`. - `tests/inspector-planet-cargo-routes.test.ts` — slot rendering, picker invocation, collapse, cancel, remove. - Extensions to `order-draft`, `submit`, `order-load`, `order-overlay`, `state-binding`, `inspector-planet`, `inspector-overlay`, `game-shell-sidebar`, `game-shell-header`. - `tests/e2e/cargo-routes.spec.ts` — Playwright happy path: add COL, add CAP, remove COL, asserting both the inspector and the arrow count via `__galaxyDebug.getMapPrimitives()`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Ilia Denisov
@@ -63,6 +63,34 @@ outputs") is therefore intentionally not satisfied; the rewritten
|
||||
Phase 15 stage text records this decision and points back at this
|
||||
document.
|
||||
|
||||
## Phase 16 waiver
|
||||
|
||||
Phase 16 introduces ship-reach filtering for the cargo-route
|
||||
destination picker. The engine formula is trivial:
|
||||
|
||||
```
|
||||
flightDistance = driveTech * 40
|
||||
```
|
||||
|
||||
(`game/internal/model/game/race.go.FlightDistance`). The original
|
||||
Phase 16 stage text described surfacing this through `pkg/calc/`
|
||||
and `ui/core/calc/`; with the calc-bridge phase still deferred,
|
||||
implementing the bridge for one constant-time multiplication would
|
||||
be premature scaffolding. The picker therefore computes reach
|
||||
inline in TypeScript using
|
||||
`torusShortestDelta(planet.x, candidate.x, mapWidth)` and
|
||||
`Math.hypot` against `40 * report.localPlayerDrive`, where
|
||||
`localPlayerDrive` is decoded from the report's `Player` block by
|
||||
matching `Player.name` to `report.race`
|
||||
(`api/game-state.ts.findLocalPlayerDrive`).
|
||||
|
||||
When the calc-bridge phase ships, the inline formula is replaced
|
||||
with a single call into the bridge: `calc.Reach(driveTech)` becomes
|
||||
the source of truth for both the picker and the cargo-route arrow
|
||||
auto-removal at turn cutoff. Until then, the UI duplicates
|
||||
`flightDistance` knowingly — same precedent as the production
|
||||
forecast deferral above.
|
||||
|
||||
## Planned bridge shape (follow-up phase)
|
||||
|
||||
When the bridge phase lands, the contract should be:
|
||||
|
||||
@@ -0,0 +1,161 @@
|
||||
# Cargo routes UX
|
||||
|
||||
This document covers the cargo-route surface added in Phase 16: the
|
||||
four-slot inspector subsection, the map-driven destination pick, and
|
||||
the optimistic overlay that keeps the inspector and the map in lock-
|
||||
step with the local order draft. The user-visible spec lives in
|
||||
[`../PLAN.md`](../PLAN.md) Phase 16; the engine semantics are quoted
|
||||
from [`game/rules.txt`](../../game/rules.txt) section "Грузовые
|
||||
маршруты" (lines 808–843); this file is the source of truth for how
|
||||
the UI surfaces those rules.
|
||||
|
||||
## Engine semantics in one paragraph
|
||||
|
||||
A cargo route on a planet you own pairs a load-type slot
|
||||
(`COL`/`CAP`/`MAT`/`EMP`) with a destination planet. Once set, the
|
||||
engine loads transport ships at the source on every turn cutoff and
|
||||
sends them to the destination, draining the load-type stockpile
|
||||
("colonists" → population pool, "capital" → industry crates, "mat" →
|
||||
raw materials, "empty" → ships returning unloaded). When several
|
||||
slots are configured the engine processes them in
|
||||
`COL > CAP > MAT > EMP` priority order
|
||||
(`game/internal/controller/route.go.SendRoutedGroups`, line 101).
|
||||
Routes are constrained by reach: the destination must be no further
|
||||
than `40 × driveTech` world units along the torus-shortest path
|
||||
(`util.ShortDistance` ≤ `Race.FlightDistance()`), and a route whose
|
||||
destination becomes unreachable at the next turn is auto-removed
|
||||
(`RemoveUnreachableRoutes`).
|
||||
|
||||
## Four-slot inspector subsection
|
||||
|
||||
The cargo-routes subsection renders below the production controls
|
||||
on every owned planet inspector. Slots appear in
|
||||
`CARGO_LOAD_TYPE_VALUES` order (COL, CAP, MAT, EMP) so visual order
|
||||
matches the engine's load priority — players who scan top-down see
|
||||
the highest-priority cargo first.
|
||||
|
||||
Slot states:
|
||||
|
||||
- **Empty** — `(no route)` text plus a single `Add` button.
|
||||
- **Filled** — `→ {destination name}` plus `Edit` and `Remove`.
|
||||
|
||||
`Add` and `Edit` open a renderer-driven destination pick (see next
|
||||
section). `Remove` emits a `removeCargoRoute` command. The collapse
|
||||
rule on the order draft store ensures only one entry per
|
||||
`(source, loadType)` slot survives in the draft at any time, so a
|
||||
sequence of `Add → Edit → Remove` collapses to the latest verb only
|
||||
(matching the production-controls pattern from Phase 15).
|
||||
|
||||
Disabled state: every button is disabled when the
|
||||
`OrderDraftStore` or `MapPickService` context is missing (the
|
||||
component is mounted outside the in-game shell, in tests, etc.).
|
||||
|
||||
## Map-driven destination pick
|
||||
|
||||
The picker is renderer-side: the inspector calls
|
||||
`MapPickService.pick({sourcePlanetNumber, reachableIds})` and awaits a
|
||||
planet number (or `null` on cancel). Reach is computed inline against
|
||||
`localPlayerDrive` — see the calc-bridge waiver in
|
||||
[`calc-bridge.md`](./calc-bridge.md).
|
||||
|
||||
While a session is active:
|
||||
|
||||
- All planets whose ids are not in `reachableIds` and are not the
|
||||
source render at `alpha = 0.3`. The visual fade signals "not a
|
||||
valid destination" without removing the planet from the map.
|
||||
- The source planet keeps full alpha and gains an outline ring so
|
||||
the player sees where the route originates.
|
||||
- A line is drawn from the source to the cursor. On touch devices
|
||||
the line follows the finger during drag.
|
||||
- Hover over a reachable planet adds an outline highlight at
|
||||
`pointRadiusPx + 4` world units so the player can confirm which
|
||||
planet they are about to pick.
|
||||
|
||||
Resolution paths:
|
||||
|
||||
- Click on a reachable planet → `setCargoRoute` enters the draft;
|
||||
the inspector slot fills; the arrow appears immediately on the
|
||||
map (overlay route applied on the next render).
|
||||
- Click on empty space or a non-reachable planet → no-op (a
|
||||
forgiving rule for accidental taps mid-pan).
|
||||
- Press Escape, click the inspector's `Cancel pick` button, or
|
||||
unmount the active map view (e.g. switch tools, navigate away)
|
||||
→ session cancels; the slot stays as it was.
|
||||
|
||||
The inspector renders an inline status line `pick a destination on
|
||||
the map (Esc to cancel)` while the session is active so the player
|
||||
knows the click target and the cancel hotkey. The line vanishes as
|
||||
soon as the picker resolves.
|
||||
|
||||
## Optimistic map overlay
|
||||
|
||||
`applyOrderOverlay` projects every locally-valid, in-flight, or
|
||||
applied `setCargoRoute` / `removeCargoRoute` onto `report.routes`,
|
||||
re-runs `reportToWorld` (which appends `LinePrim` arrows from
|
||||
`buildCargoRouteLines`), and remounts the renderer when the routes-
|
||||
content fingerprint changes. The map active view captures camera
|
||||
centre + zoom before each remount and restores them when the game
|
||||
id is unchanged, so adding a route mid-pan does not jolt the view.
|
||||
|
||||
Arrows are drawn as a shaft plus two short arrowhead wings. Per-type
|
||||
styling (placeholder Phase 16 colours; final values land in Phase
|
||||
35 polish):
|
||||
|
||||
| Load type | Stroke colour | Notes |
|
||||
| --------- | ------------- | ------------------------ |
|
||||
| COL | `#4FC3F7` | brightest blue, highest priority |
|
||||
| CAP | `#FFB74D` | warm orange |
|
||||
| MAT | `#81C784` | green |
|
||||
| EMP | `#90A4AE` | dim grey, thinner stroke |
|
||||
|
||||
Arrow priority (COL=8, CAP=7, MAT=6, EMP=5) sits above all planet
|
||||
priorities (1..4), so two arrows that overlap exactly resolve to the
|
||||
higher-priority load type during hit-test. Planet primitives still
|
||||
win over arrows because the line ids carry a high-bit prefix
|
||||
(`0x80000000`) and the renderer keeps points at the kind tie-break
|
||||
position 0.
|
||||
|
||||
## Reach computation
|
||||
|
||||
Implementation: inline TypeScript using `torusShortestDelta` for
|
||||
each axis and `Math.hypot` for the distance, compared against `40 ×
|
||||
localPlayerDrive`. The local player's drive comes from the report's
|
||||
`Player` block, looked up by `name === report.race`
|
||||
(`api/game-state.ts.findLocalPlayerDrive`).
|
||||
|
||||
Why inline rather than via a Go calc bridge? See the Phase 15 / 16
|
||||
deferral note in [`calc-bridge.md`](./calc-bridge.md). The formula
|
||||
is trivial (`tech × 40`) and the WASM glue would be premature
|
||||
infrastructure; when the calc bridge phase lands the shared
|
||||
`pkg/calc.Reach` will replace this implementation.
|
||||
|
||||
## Tests
|
||||
|
||||
| Layer | File | What it covers |
|
||||
| ----------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
|
||||
| Order draft collapse | `tests/order-draft.test.ts` | `(source, loadType)` collapse rules across `set` and `remove`. |
|
||||
| Encode / decode round-trip | `tests/submit.test.ts`, `tests/order-load.test.ts` | `setCargoRoute` and `removeCargoRoute` ↔ FBS payloads; UNKNOWN load-type drops with a warn. |
|
||||
| Overlay | `tests/order-overlay.test.ts` | `applyOrderOverlay` upserts / drops route entries for valid / submitting / applied statuses. |
|
||||
| Inspector subsection | `tests/inspector-planet-cargo-routes.test.ts` | Slot rendering, pick invocation, emit, cancel, edit, remove, per-type independence. |
|
||||
| Map arrows | `tests/map-cargo-routes.test.ts` | `buildCargoRouteLines` shape on torus + no-wrap fixtures, per-type style, priority ordering. |
|
||||
| End-to-end | `tests/e2e/cargo-routes.spec.ts` | Mocked gateway: open inspector, dim outside reach, pick destination, arrow appears, reload. |
|
||||
|
||||
## File index
|
||||
|
||||
- `ui/frontend/src/lib/inspectors/planet/cargo-routes.svelte` —
|
||||
inspector subsection.
|
||||
- `ui/frontend/src/sync/order-types.ts` — `CargoLoadType`,
|
||||
`SetCargoRouteCommand`, `RemoveCargoRouteCommand`.
|
||||
- `ui/frontend/src/sync/order-draft.svelte.ts` — collapse rule.
|
||||
- `ui/frontend/src/sync/submit.ts` — encoder.
|
||||
- `ui/frontend/src/sync/order-load.ts` — decoder.
|
||||
- `ui/frontend/src/api/game-state.ts` — `routes` and
|
||||
`localPlayerDrive` decoding plus overlay extension.
|
||||
- `ui/frontend/src/map/cargo-routes.ts` — arrow geometry.
|
||||
- `ui/frontend/src/map/state-binding.ts` — appends route lines.
|
||||
- `ui/frontend/src/lib/active-view/map.svelte` — fingerprint guard
|
||||
+ camera preservation.
|
||||
- `ui/frontend/src/map/pick-mode.ts` and
|
||||
`ui/frontend/src/map/render.ts` — pick-mode foundation.
|
||||
- `ui/frontend/src/lib/map-pick.svelte.ts` — Svelte adapter.
|
||||
- `ui/docs/renderer.md` — pick-mode and debug-surface contract.
|
||||
+79
-6
@@ -116,7 +116,11 @@ target.
|
||||
|
||||
Per-primitive distance:
|
||||
|
||||
- **Point**: `distSq ≤ slopWorld²`.
|
||||
- **Point**: `distSq ≤ (pointRadiusPx + slopWorld)²`. The visible
|
||||
disc is part of the click target — a click on any pixel of the
|
||||
rendered planet registers as a hit, with `slopWorld` adding a
|
||||
small ergonomic margin on top. `pointRadiusPx` defaults to
|
||||
`DEFAULT_POINT_RADIUS_PX = 3` when unset.
|
||||
- **Filled circle**: `distSq ≤ (radius + slopWorld)²` where
|
||||
`radius` is in world units. The circle counts as filled when
|
||||
`style.fillColor` is set and `style.fillAlpha > 0`.
|
||||
@@ -220,6 +224,72 @@ If a future regression requires a programmatic perf gate, the
|
||||
right place is a Tier 2 (release-line) Playwright trace measuring
|
||||
average frame time over a scripted drag.
|
||||
|
||||
## Pick mode
|
||||
|
||||
Phase 16 introduced a generic *map-driven destination pick* the
|
||||
inspector uses for cargo routes and that ship-group dispatch
|
||||
(Phase 19/20) will reuse. The renderer owns the visual lifecycle;
|
||||
the Svelte side wraps it in a promise-shaped service.
|
||||
|
||||
Lifecycle (`RendererHandle.setPickMode(opts)`):
|
||||
|
||||
1. **Open** (`opts !== null`): renderer marks `pickModeActive`,
|
||||
sets `alpha = 0.3` on every primitive whose id is neither the
|
||||
source nor in `reachableIds`, mounts an overlay `Graphics` in
|
||||
the origin tile, and subscribes to pointer-move + hover-change
|
||||
+ viewport `clicked` + document `keydown`.
|
||||
2. **Tick** (every pointer-move and hover transition): the
|
||||
renderer asks `computePickOverlay(opts, cursorWorld,
|
||||
hoveredId, points, allIds)` (`src/map/pick-mode.ts`) for a
|
||||
draw spec — anchor ring + cursor line + optional hover
|
||||
outline + dim set — and re-paints the overlay.
|
||||
3. **Resolve**: a click on a primitive whose id is in
|
||||
`reachableIds` calls `opts.onPick(id)` and tears down. A click
|
||||
on empty space or a non-reachable primitive is a no-op
|
||||
(forgiving for accidental taps mid-pan). Escape (or the
|
||||
imperative `cancel()` on the returned handle) calls
|
||||
`opts.onPick(null)`.
|
||||
4. **Tear down**: alpha overrides are restored, the overlay
|
||||
`Graphics` is destroyed, every listener is detached, and
|
||||
`pickModeActive` returns to `false`. Existing `onClick`
|
||||
subscriptions are gated on `pickModeActive`, so the standard
|
||||
planet-selection path does not fire on the destination click.
|
||||
|
||||
The pure overlay-spec helper lives in `src/map/pick-mode.ts` and
|
||||
is covered by `tests/map-pick-mode.test.ts` without booting Pixi.
|
||||
The Pixi side (alpha mutation, `Graphics` overlay, listener
|
||||
hookup) is exercised in the in-browser e2e specs.
|
||||
|
||||
The Svelte adapter `MapPickService` (`src/lib/map-pick.svelte.ts`)
|
||||
turns the callback contract into `pick(request) → Promise<id |
|
||||
null>`. The map active view (`lib/active-view/map.svelte`)
|
||||
constructs the service, sets `MAP_PICK_CONTEXT_KEY`, and binds a
|
||||
resolver that translates `sourcePlanetNumber` to the underlying
|
||||
`PickModeOptions` (looking up the source coordinates from the
|
||||
current report). Inspector subsections call `service.pick(...)`
|
||||
and react to the resolved id.
|
||||
|
||||
## Debug surface
|
||||
|
||||
The DEV-only `__galaxyDebug` object (defined in
|
||||
`routes/__debug/store/+page.svelte`) exposes
|
||||
`getMapPrimitives()` and `getMapPickState()` so e2e specs can
|
||||
assert the renderer's current state without scraping pixels:
|
||||
|
||||
- `getMapPrimitives()` returns a snapshot of every primitive in
|
||||
the active world: id, kind, priority, current alpha
|
||||
(post-overlay), and the explicit fill / stroke colour from its
|
||||
`Style` (no theme fallback). Tests use this to count cargo
|
||||
arrows or to verify dim state during pick mode.
|
||||
- `getMapPickState()` returns `{ active, sourcePlanetNumber,
|
||||
reachableIds, hoveredId }` — the renderer's view of the
|
||||
current pick session.
|
||||
|
||||
The active map view registers providers on mount via
|
||||
`registerMapPrimitivesProvider` / `registerMapPickStateProvider`
|
||||
in `src/lib/debug-surface.svelte.ts`, deregisters on dispose, and
|
||||
the surface invokes them lazily on every read.
|
||||
|
||||
## Tests
|
||||
|
||||
- `tests/map-math.test.ts` — `clamp`, `torusShortestDelta`,
|
||||
@@ -227,11 +297,14 @@ average frame time over a scripted drag.
|
||||
- `tests/map-no-wrap.test.ts` — `clampCameraNoWrap`,
|
||||
`minScaleNoWrap`, `pivotZoom` (point-under-cursor invariant
|
||||
verified within float64 precision).
|
||||
- `tests/map-hit-test.test.ts` — 22 hand-built cases covering
|
||||
every rule from the algorithm above: hit/miss with default and
|
||||
custom slop, torus wrap copies, filled vs stroked circles,
|
||||
line endpoint clamping, priority/kind/id ordering, scale
|
||||
effect on slop.
|
||||
- `tests/map-hit-test.test.ts` — hand-built cases covering every
|
||||
rule from the algorithm above: hit/miss with default and
|
||||
custom slop (now including `pointRadiusPx`), torus wrap
|
||||
copies, filled vs stroked circles, line endpoint clamping,
|
||||
priority/kind/id ordering, scale effect on slop.
|
||||
- `tests/map-pick-mode.test.ts` — pure-state coverage for
|
||||
`computePickOverlay`: anchor / line / hover-outline / dim-set
|
||||
shape against representative pick configurations.
|
||||
- `tests/e2e/playground-map.spec.ts` — Pixi mount in real
|
||||
browsers, mode toggle, wheel zoom, no-wrap clamp after drag,
|
||||
hit-test plumbing.
|
||||
|
||||
Reference in New Issue
Block a user