/** * Contextual hints: "what should this ship do next?" in plain language. * Pure function of a snapshot of state, so it is easy to test and reason about. * Hints suggest; the API's actions decide. A hint's `action` is only set when that * action is on offer right now, so the UI can render it as a one-click button. */ import type { ActiveShip, CaptainContract, MarketGood, Ship, Waypoint, WaypointKind } from '../types'; import { isActive, isDisabled } from '../types'; import { bestSellFor, sellRevenue, type MarketSnapshot, type TradeRoute } from './trade'; export type HintLevel = 'danger' | 'warn' | 'info'; export interface Hint { id: string; level: HintLevel; text: string; /** Action to offer as the hint's button (present in the ship's actions). */ action?: string; /** Waypoint the hint points at, to highlight or fly to. */ target?: string; } export interface AdviceContext { ship: ActiveShip; /** Names of the actions the API offers the ship right now. */ actions: readonly string[]; /** Kind of the waypoint the ship is at. */ here: WaypointKind | null; systemWaypoints: readonly Waypoint[]; /** Market of the station the ship is docked at. */ market: readonly MarketGood[] | null; snapshots: readonly MarketSnapshot[]; bestRoute: TradeRoute | null; contracts: readonly CaptainContract[]; codex: { have: number; of: number } | null; now: number; } export const LOW_FUEL = 0.25; export const LOW_HULL = 30; /** Only suggest carrying cargo elsewhere when it pays this much more per unit. */ const ELSEWHERE_MARGIN = 1.1; const MAX_HINTS = 3; const cr = (n: number) => `${Math.round(n).toLocaleString('en-US')} cr`; const ORDER: Record = { danger: 0, warn: 1, info: 2 }; export function adviseShip(ctx: AdviceContext): Hint[] { const { ship, actions } = ctx; const has = (a: string) => actions.includes(a); const offer = (a: string) => (has(a) ? a : undefined); const hints: Hint[] = []; const docked = ship.status === 'docked'; const free = ship.cargo.capacity - ship.cargo.units; if (isDisabled(ship)) { hints.push({ id: 'stranded', level: 'danger', text: 'Stranded: the hull is worn through. Call for a tow, or pay a station tug.', action: offer('distress') ?? offer('tug') }); return hints; } if (ship.status === 'in_transit') return hints; // --- safety first if (ship.fuel.capacity > 0 && ship.fuel.current / ship.fuel.capacity < LOW_FUEL) { const refuelHere = docked && has('refuel'); hints.push({ id: 'fuel', level: 'warn', text: `Fuel low (${ship.fuel.current}/${ship.fuel.capacity}). ${refuelHere ? 'Refuel before leaving.' : 'Refuel at the next station.'}`, action: refuelHere ? 'refuel' : undefined }); } if (ship.hull < LOW_HULL) { hints.push({ id: 'hull', level: 'warn', text: `Hull worn (${ship.hull}/100). ${docked && has('repair') ? 'Repair it here.' : 'Repair at a station before long trips.'}`, action: docked ? offer('repair') : undefined }); } // --- contracts: cargo that someone is waiting for for (const c of ctx.contracts) { if (c.status !== 'open') continue; const held = ship.cargo.items.find((i) => i.good === c.good)?.units ?? 0; if (!held) continue; const need = c.units - c.delivered; if (ship.waypoint === c.station && has('deliver')) { hints.push({ id: `contract-${c.id}`, level: 'info', text: `Deliver ${Math.min(held, need)} ${c.good} for contract ${c.id}.`, action: 'deliver' }); } else { hints.push({ id: `contract-${c.id}`, level: 'info', text: `Your ${c.good} is wanted at ${c.station} for a contract (${need} left).`, target: c.station }); } break; } // --- trading at a market if (docked && ctx.market) { const item = ship.cargo.items.find((i) => ctx.market!.some((g) => g.good === i.good)); if (item) { const here = ctx.market.find((g) => g.good === item.good)!; const elsewhere = bestSellFor(item.good, ctx.snapshots, ship.waypoint ?? undefined); if (elsewhere && elsewhere.price > here.sell * ELSEWHERE_MARGIN) { hints.push({ id: 'sell-elsewhere', level: 'info', text: `${item.good} fetches ${here.sell} cr here but ${elsewhere.price} cr at ${elsewhere.station}.`, target: elsewhere.station, action: offer('sell') }); } else { hints.push({ id: 'sell', level: 'info', text: `Sell ${item.units} ${item.good} here for about ${cr(sellRevenue(here, item.units))}.`, action: offer('sell') }); } } else if (ship.cargo.units === 0 && ctx.bestRoute) { const r = ctx.bestRoute; if (r.from === ship.waypoint) { hints.push({ id: 'trade', level: 'info', text: `Buy ${r.units} ${r.good} here and sell at ${r.to}: about +${cr(r.profit)}.`, action: offer('buy'), target: r.to }); } else { hints.push({ id: 'trade', level: 'info', text: `Best known run: ${r.good} from ${r.from} to ${r.to}, about +${cr(r.profit)}.`, target: r.from }); } } } // --- in orbit: what this waypoint is for if (ship.status === 'in_orbit') { if (ctx.here === 'station' && ship.cargo.units > 0 && has('dock')) { hints.push({ id: 'dock', level: 'info', text: 'Dock to sell your cargo.', action: 'dock' }); } if (ctx.here === 'asteroid_field' && free > 0 && has('extract')) { hints.push({ id: 'mine', level: 'info', text: `Mine here: ${free} units of space in the hold.`, action: 'extract' }); } if (ctx.here === 'derelict' && has('scan')) { const progress = ctx.codex ? ` (${ctx.codex.have}/${ctx.codex.of} recovered)` : ''; hints.push({ id: 'scan', level: 'info', text: `Scan the derelict for a Codex fragment${progress}.`, action: 'scan' }); } } const derelict = ctx.systemWaypoints.find((w) => w.kind === 'derelict'); const codexDone = ctx.codex !== null && ctx.codex.have >= ctx.codex.of; if (derelict && ctx.here !== 'derelict' && !codexDone) { hints.push({ id: 'derelict', level: 'info', text: `A derelict drifts at ${derelict.symbol}: fly there and scan it.`, target: derelict.symbol }); } if (hints.length === 0) { hints.push({ id: 'idle', level: 'info', text: 'Pick a waypoint on the map to plan a trip.' }); } return hints.sort((a, b) => ORDER[a.level] - ORDER[b.level]).slice(0, MAX_HINTS); } /** Badge for the fleet rail: does this ship need the player? */ export function attention(ship: Ship, now: number): HintLevel | null { if (!isActive(ship)) return null; if (isDisabled(ship)) return 'danger'; if (ship.status !== 'in_transit') { if (ship.fuel.capacity > 0 && ship.fuel.current / ship.fuel.capacity < LOW_FUEL) return 'warn'; if (ship.hull < LOW_HULL) return 'warn'; return 'info'; // idle, awaiting orders } return ship.route && Date.parse(ship.route.arrives) <= now ? 'info' : null; }