@shipload/sdk 1.0.0-next.7 → 1.0.0-next.71

package/src/entity/hydrate.test.ts

@@ -0,0 +1,156 @@
+import {UInt64} from '@wharfkit/antelope'
+import {describe, expect, test} from 'bun:test'
+import {entityToRouteMover, hydrateEntityLanes} from './hydrate'
+
+describe('hydrateEntityLanes', () => {
+    test('maps camelCase gathererLanes to gatherer_lane with snake_case fields', () => {
+        const lanes = hydrateEntityLanes({
+            gathererLanes: [
+                {slotIndex: 2, yield: 700, drain: 1_250_000, depth: 5000, outputPct: 100},
+            ],
+        })
+        expect(lanes).toHaveLength(1)
+        expect(lanes[0].slot_index.toNumber()).toBe(2)
+        expect(lanes[0].yield.toNumber()).toBe(700)
+        expect(lanes[0].drain.toNumber()).toBe(1_250_000)
+        expect(lanes[0].depth.toNumber()).toBe(5000)
+        expect(lanes[0].output_pct.toNumber()).toBe(100)
+    })
+
+    test('falls back to a single synthetic lane from caps.gatherer when gathererLanes is absent', () => {
+        const lanes = hydrateEntityLanes({gatherer: {yield: 300, drain: 50, depth: 1000}})
+        expect(lanes).toHaveLength(1)
+        expect(lanes[0].slot_index.toNumber()).toBe(0)
+        expect(lanes[0].yield.toNumber()).toBe(300)
+        expect(lanes[0].drain.toNumber()).toBe(50)
+        expect(lanes[0].depth.toNumber()).toBe(1000)
+        expect(lanes[0].output_pct.toNumber()).toBe(100)
+    })
+
+    test('prefers gathererLanes over the caps.gatherer fallback when both are present', () => {
+        const lanes = hydrateEntityLanes({
+            gathererLanes: [{slotIndex: 1, yield: 10, drain: 20, depth: 30, outputPct: 40}],
+            gatherer: {yield: 999, drain: 999, depth: 999},
+        })
+        expect(lanes).toHaveLength(1)
+        expect(lanes[0].slot_index.toNumber()).toBe(1)
+    })
+
+    test('returns an empty array when there is no gatherer capability at all', () => {
+        expect(hydrateEntityLanes({})).toEqual([])
+    })
+
+    test('clamps out-of-range and non-integer fields to the contract field bounds', () => {
+        const lanes = hydrateEntityLanes({
+            gathererLanes: [
+                {
+                    slotIndex: -5,
+                    yield: 999_999,
+                    drain: -1,
+                    depth: 70_000.7,
+                    outputPct: Number.NaN,
+                },
+            ],
+        })
+        expect(lanes[0].slot_index.toNumber()).toBe(0)
+        expect(lanes[0].yield.toNumber()).toBe(65_535)
+        expect(lanes[0].drain.toNumber()).toBe(0)
+        expect(lanes[0].depth.toNumber()).toBe(65_535)
+        expect(lanes[0].output_pct.toNumber()).toBe(0)
+    })
+
+    test('clamps a slot index above the uint8 ceiling', () => {
+        const lanes = hydrateEntityLanes({
+            gathererLanes: [{slotIndex: 300, yield: 0, drain: 0, depth: 0, outputPct: 0}],
+        })
+        expect(lanes[0].slot_index.toNumber()).toBe(255)
+    })
+
+    test('clamps drain above the uint32 ceiling', () => {
+        const lanes = hydrateEntityLanes({
+            gathererLanes: [{slotIndex: 0, yield: 0, drain: 5_000_000_000, depth: 0, outputPct: 0}],
+        })
+        expect(lanes[0].drain.toNumber()).toBe(4_294_967_295)
+    })
+})
+
+describe('entityToRouteMover', () => {
+    test('sums hullmass, cargomass, and loader lane mass into total mass', () => {
+        const mover = entityToRouteMover(
+            {id: UInt64.from(1), energy: 500, cargomass: 200},
+            {
+                hullmass: 1000,
+                loaderLanes: [
+                    {slotIndex: 0, mass: 50, thrust: 10, outputPct: 100},
+                    {slotIndex: 1, mass: 25, thrust: 10, outputPct: 100},
+                ],
+            }
+        )
+        expect(mover.mass).toBe(1000 + 200 + 50 + 25)
+        expect(mover.energy).toBe(500)
+        expect(mover.ref).toEqual({entityType: 'ship', entityId: UInt64.from(1)})
+    })
+
+    test('derives hasMovement from the presence of both engines and a generator', () => {
+        const withMovement = entityToRouteMover(
+            {id: UInt64.from(1)},
+            {
+                hullmass: 0,
+                engines: {thrust: 100, drain: 10},
+                generator: {capacity: 1000, recharge: 10},
+            }
+        )
+        expect(withMovement.hasMovement).toBe(true)
+
+        const withoutMovement = entityToRouteMover({id: UInt64.from(1)}, {hullmass: 0})
+        expect(withoutMovement.hasMovement).toBe(false)
+    })
+
+    test('an explicit hasMovement opt overrides the derived value', () => {
+        const mover = entityToRouteMover(
+            {id: UInt64.from(1)},
+            {
+                hullmass: 0,
+                engines: {thrust: 100, drain: 10},
+                generator: {capacity: 1000, recharge: 10},
+            },
+            {hasMovement: false}
+        )
+        expect(mover.hasMovement).toBe(false)
+    })
+
+    test('narrows hauler down to capacity and efficiency, dropping drain and capacityByTier', () => {
+        const mover = entityToRouteMover(
+            {id: UInt64.from(1)},
+            {
+                hullmass: 0,
+                hauler: {
+                    capacity: 500,
+                    efficiency: 80,
+                    drain: 10,
+                    capacityByTier: [{tier: 1, capacity: 500}],
+                },
+            }
+        )
+        expect(mover.hauler).toEqual({capacity: 500, efficiency: 80})
+    })
+
+    test('defaults energy, priorMobilityEnd, and narrowBarrierEnd to zero when unset', () => {
+        const mover = entityToRouteMover({id: UInt64.from(1)}, {hullmass: 0})
+        expect(mover.energy).toBe(0)
+        expect(mover.priorMobilityEnd).toBe(0)
+        expect(mover.narrowBarrierEnd).toBe(0)
+    })
+
+    test('opts override entityType and scheduling fields', () => {
+        const mover = entityToRouteMover(
+            {id: UInt64.from(7)},
+            {hullmass: 0},
+            {entityType: 'starbase', priorMobilityEnd: 30, narrowBarrierEnd: 15, allLanesEnd: 45}
+        )
+        expect(mover.ref).toEqual({entityType: 'starbase', entityId: UInt64.from(7)})
+        expect(mover.priorMobilityEnd).toBe(30)
+        expect(mover.narrowBarrierEnd).toBe(15)
+        expect(mover.allLanesEnd).toBe(45)
+    })
+})

package/src/entity/hydrate.ts

@@ -0,0 +1,86 @@
+import type {UInt32Type, UInt64Type} from '@wharfkit/antelope'
+import {ServerContract} from '../contracts'
+import type {ComputedCapabilities} from '../derivation/capabilities'
+import type {RouteMoverInput} from '../travel/route-simulator'
+import type {GatherLane} from '../planner'
+
+const U8_MAX = 255
+const U16_MAX = 65_535
+const U32_MAX = 4_294_967_295
+
+function clampField(value: number, max: number): number {
+    return Math.min(max, Math.max(0, Math.floor(Number(value) || 0)))
+}
+
+export interface GathererLaneSource {
+    gathererLanes?: ComputedCapabilities['gathererLanes']
+    gatherer?: ComputedCapabilities['gatherer']
+}
+
+export function hydrateEntityLanes(caps: GathererLaneSource): GatherLane[] {
+    const lanes = caps.gathererLanes?.length
+        ? caps.gathererLanes
+        : caps.gatherer
+          ? [
+                {
+                    slotIndex: 0,
+                    yield: caps.gatherer.yield,
+                    drain: caps.gatherer.drain,
+                    depth: caps.gatherer.depth,
+                    outputPct: 100,
+                },
+            ]
+          : []
+    return lanes.map((lane) =>
+        ServerContract.Types.gatherer_lane.from({
+            slot_index: clampField(lane.slotIndex, U8_MAX),
+            yield: clampField(lane.yield, U16_MAX),
+            drain: clampField(lane.drain, U32_MAX),
+            depth: clampField(lane.depth, U16_MAX),
+            output_pct: clampField(lane.outputPct, U16_MAX),
+        })
+    )
+}
+
+export interface RouteMoverRow {
+    id: UInt64Type
+    energy?: UInt32Type | number
+    cargomass?: UInt32Type | number
+}
+
+export type RouteMoverCaps = Pick<
+    ComputedCapabilities,
+    'hullmass' | 'engines' | 'generator' | 'hauler' | 'loaderLanes'
+>
+
+export interface RouteMoverOpts {
+    entityType?: string
+    hasMovement?: boolean
+    priorMobilityEnd?: number
+    narrowBarrierEnd?: number
+    allLanesEnd?: number
+}
+
+export function entityToRouteMover(
+    row: RouteMoverRow,
+    caps: RouteMoverCaps,
+    opts: RouteMoverOpts = {}
+): RouteMoverInput {
+    const loaderMass = (caps.loaderLanes ?? []).reduce((sum, lane) => sum + Number(lane.mass), 0)
+    const mass = Number(row.cargomass ?? 0) + Number(caps.hullmass ?? 0) + loaderMass
+    return {
+        ref: {entityType: opts.entityType ?? 'ship', entityId: row.id},
+        hasMovement:
+            opts.hasMovement ?? (caps.engines !== undefined && caps.generator !== undefined),
+        engines: caps.engines,
+        generator: caps.generator,
+        hauler: caps.hauler
+            ? {capacity: caps.hauler.capacity, efficiency: caps.hauler.efficiency}
+            : undefined,
+        mass,
+        energy: Number(row.energy ?? 0),
+        priorMobilityEnd: opts.priorMobilityEnd ?? 0,
+        narrowBarrierEnd: opts.narrowBarrierEnd ?? 0,
+        allLanesEnd: opts.allLanesEnd,
+    }
+}

package/src/errors.ts

@@ -16,20 +16,18 @@ export const REQUIRES_POSITIVE_VALUE = 'Value must be greater than zero.'
 export const PLAYER_ALREADY_JOINED = 'Player has already joined the game.'
 export const PLAYER_NOT_JOINED = 'Player has not joined the game.'
 export const PLAYER_NOT_FOUND = 'Cannot find player for given account name.'
-export const STARTER_ALREADY_CLAIMED =
-    'Starter ship already claimed; destroy existing ships to re-claim.'
-export const SHIP_ALREADY_THERE = 'Ship cannot travel to the location its already at.'
+export const ENTITY_ALREADY_THERE = 'Entity cannot travel to the location it is already at.'
 export const SHIP_ALREADY_TRAVELING = 'Ship is already traveling.'
 export const SHIP_CANNOT_BUY_TRAVELING = 'Ship cannot buy goods while traveling.'
 export const SHIP_CANNOT_UPDATE_TRAVELING = 'Ship cannot be updated while traveling.'
-export const SHIP_INVALID_DESTINATION = 'Ship cannot travel, no system at specified destination.'
-export const SHIP_INVALID_TRAVEL_DURATION =
+export const ENTITY_INVALID_DESTINATION = 'Cannot travel: no system at specified destination.'
+export const ENTITY_INVALID_TRAVEL_DURATION =
     'This trip cannot be made as it would exceed the maximum travel duration.'
 export const SHIP_NOT_ARRIVED = 'Ship has not yet arrived at its destination.'
-export const SHIP_NOT_ENOUGH_ENERGY =
-    'Ship does not have enough energy to travel to the destination.'
-export const SHIP_NOT_ENOUGH_ENERGY_CAPACITY =
-    'Ship does not have enough energy capacity to travel.'
+export const ENTITY_NOT_ENOUGH_ENERGY =
+    'Entity does not have enough energy to travel to the destination.'
+export const ENTITY_NOT_ENOUGH_ENERGY_CAPACITY =
+    'Entity does not have enough energy capacity to travel.'
 export const SHIP_NOT_FOUND = 'Cannot find ship for given account.'
 export const SHIP_NOT_OWNED = 'Ship is not owned by this account.'
 export const NO_SCHEDULE = 'No scheduled tasks.'
@@ -38,19 +36,15 @@ export const SHIP_NO_COMPLETED_TASKS = 'No completed tasks to resolve.'
 export const RESOLVE_COUNT_EXCEEDS_COMPLETED = 'Requested resolve count exceeds completed tasks.'
 export const SHIP_CANNOT_CANCEL_TASK = 'Cannot cancel task that is immutable or in progress.'
 export const SHIP_NO_TASKS_TO_CANCEL = 'No tasks to cancel.'
-export const SHIP_INVALID_CARGO = 'Invalid cargo specified for load/unload.'
-export const SHIP_CARGO_NOT_OWNED = 'Cannot load cargo that is not owned.'
-export const SHIP_CARGO_NOT_LOADED = 'Cannot unload cargo that is not loaded.'
-export const SHIP_CAPACITY_EXCEEDED = 'Ship cargo capacity would be exceeded.'
+export const ENTITY_INVALID_CARGO = 'Invalid cargo specified for load/unload.'
+export const ENTITY_CARGO_NOT_OWNED = 'Cannot load cargo that is not owned.'
+export const ENTITY_CARGO_NOT_LOADED = 'Cannot unload cargo that is not loaded.'
 export const ENTITY_CAPACITY_EXCEEDED = 'Entity cargo capacity would be exceeded.'
 export const WAREHOUSE_NOT_FOUND = 'Cannot find warehouse for given id.'
 export const WAREHOUSE_ALREADY_AT_LOCATION = 'Warehouse already exists at this location.'
-export const WAREHOUSE_CAPACITY_EXCEEDED = 'Warehouse capacity would be exceeded.'
 export const CONTAINER_NOT_FOUND = 'Cannot find container for given id.'
-export const CONTAINER_CAPACITY_EXCEEDED = 'Container capacity would be exceeded.'
 export const DESTINATION_CAPACITY_EXCEEDED =
     'Destination entity does not have enough capacity for the gather.'
-export const CANCEL_PAIRED_HAS_PENDING = 'Cannot cancel transfer, paired entity has pending tasks.'
 export const GROUP_EMPTY = 'Group travel requires at least one entity.'
 export const GROUP_NO_THRUST = 'Group travel requires at least one entity with engines.'
 export const GROUP_NOT_SAME_LOCATION = 'All entities must be at the same location for group travel.'
@@ -62,6 +56,8 @@ export const GROUP_HAUL_CAPACITY_EXCEEDED =
     'Group travel requires sufficient hauler capacity for all non-self-propelled entities.'
 export const CANCEL_CONTAINS_GROUPED_TASK =
     'Cannot cancel range containing grouped task - cancel non-grouped tasks first.'
+export const WOULD_STRAND = 'Cancelling this would leave a later task without the cargo it needs.'
+export const WOULD_OVERFILL = 'Cancelling this would overfill the other entity with returned cargo.'
 export const WARP_NO_CAPABILITY = 'Entity does not have warp capability.'
 export const WARP_HAS_SCHEDULE = 'Entity must be idle to warp.'
 export const WARP_HAS_CARGO = 'Entity must have no cargo to warp.'
@@ -98,3 +94,12 @@ export const ITEM_NOT_AVAILABLE_AT_LOCATION = 'Item is not tradeable at ship loc
 export const INSUFFICIENT_BALANCE = 'Insufficient balance.'
 export const INSUFFICIENT_ITEM_QUANTITY = 'Insufficient quantity in cargo.'
 export const INSUFFICIENT_ITEM_SUPPLY = 'Insufficient supply of item at location.'
+
+export const VOTE_NOT_CITIZEN = 'player is not a citizen of this world'
+export const BALLOT_SETTLING = 'world is settling the last epoch'
+export const BALLOT_NOT_DUE = 'ballot is not due'
+export const BALLOT_NONE_DUE = 'no ballots are due'
+
+export function isSettling(error: unknown): boolean {
+    return error instanceof Error && error.message.includes(BALLOT_SETTLING)
+}

package/src/format.ts

@@ -1,12 +1,45 @@
-export function formatMass(kg: number): string {
-    const t = kg / 1000
-    const fixed = t.toFixed(2)
-    const trimmed = fixed.replace(/\.?0+$/, '')
-    return `${trimmed} t`
+import {MASS_UNITS_PER_TONNE} from './types'
+
+export function formatMass(mass: number): string {
+    if (mass === 0) return '0 t'
+    const sign = mass < 0 ? '-' : ''
+    const centitonnes = Math.abs(mass) * 10
+    const t = Math.floor(centitonnes / 100)
+    const frac = centitonnes % 100
+    if (frac === 0) return `${sign}${t} t`
+    const fracStr = String(frac).padStart(2, '0').replace(/0$/, '')
+    return `${sign}${t}.${fracStr} t`
+}
+
+export function formatMassDelta(mass: number): string {
+    if (mass === 0) return '0 t'
+    const sign = mass > 0 ? '+' : '-'
+    return `${sign}${formatMass(Math.abs(mass))}`
+}
+
+export function formatLocation(loc: {x: number; y: number}): string {
+    return `${loc.x}, ${loc.y}`
+}
+
+function trim(n: number, digits = 1): string {
+    return n.toFixed(digits).replace(/\.?0+$/, '')
+}
+
+export function formatMassScaled(mass: number): string {
+    if (mass === 0) return '0 t'
+    const sign = mass < 0 ? '-' : ''
+    const tonnes = Math.abs(mass) / MASS_UNITS_PER_TONNE
+    if (tonnes >= 1_000_000_000) return `${sign}${trim(tonnes / 1_000_000_000)}b t`
+    if (tonnes >= 1_000_000) return `${sign}${trim(tonnes / 1_000_000)}m t`
+    if (tonnes >= 1_000) return `${sign}${trim(tonnes / 1_000)}k t`
+    return formatMass(mass)
+}
+
+export function formatInfluence(atomic: bigint | number | string): string {
+    const points = BigInt(String(atomic)) / 10_000n
+    return `${points.toLocaleString('en-US')} pts`
 }
 
-export function formatMassDelta(kg: number): string {
-    if (kg === 0) return '0 t'
-    const sign = kg > 0 ? '+' : '-'
-    return `${sign}${formatMass(Math.abs(kg))}`
+export function formatNeedMultiplier(needFp: bigint | number | string): string {
+    return `×${(Number(BigInt(String(needFp))) / 10_000).toFixed(1)}`
 }