@shipload/sdk 1.0.0-next.4 → 1.0.0-next.40

package/src/testing/projection-parity.ts

@@ -0,0 +1,167 @@
+import type {UInt16, UInt32} from '@wharfkit/antelope'
+import type {ServerContract} from '../contracts'
+import type {ProjectedEntity} from '../scheduling/projection'
+import {type CargoStack, cargoItemToStack, mergeStacks} from '../capabilities/storage'
+
+export interface ContractProjectedState {
+    owner: {toString(): string}
+    coordinates: ServerContract.Types.coordinates
+    energy?: UInt16
+    cargomass: UInt32
+    cargo: ServerContract.Types.cargo_view[]
+    hullmass?: UInt32
+    capacity?: UInt32
+    engines?: ServerContract.Types.movement_stats
+    generator?: ServerContract.Types.energy_stats
+    hauler?: ServerContract.Types.hauler_stats
+    gatherer_lanes: ServerContract.Types.gatherer_lane[]
+    crafter_lanes: ServerContract.Types.crafter_lane[]
+    loader_lanes: ServerContract.Types.loader_lane[]
+}
+
+export interface ProjectionComparisonOptions {
+    step?: number
+}
+
+export function assertProjectionEquals(
+    contract: ContractProjectedState,
+    sdk: ProjectedEntity,
+    options: ProjectionComparisonOptions = {}
+): void {
+    const mismatches: string[] = []
+
+    const record = (name: string, c: unknown, s: unknown) => {
+        if (c !== s) mismatches.push(`  ${name}: contract=${fmt(c)} sdk=${fmt(s)}`)
+    }
+
+    const recordStatBlock = (name: string, c: unknown, s: unknown) => {
+        const cPresent = c !== undefined && c !== null
+        const sPresent = s !== undefined && s !== null
+        if (cPresent !== sPresent) {
+            mismatches.push(
+                `  ${name}: contract=${cPresent ? 'present' : 'absent'} sdk=${sPresent ? 'present' : 'absent'}`
+            )
+            return
+        }
+        if (!cPresent) return
+        const cn = JSON.stringify(normaliseStatBlock(c))
+        const sn = JSON.stringify(normaliseStatBlock(s))
+        if (cn !== sn) mismatches.push(`  ${name}: contract=${cn} sdk=${sn}`)
+    }
+
+    record('coordinates.x', toNum(contract.coordinates.x), Number(sdk.location.x))
+    record('coordinates.y', toNum(contract.coordinates.y), Number(sdk.location.y))
+    record('energy', toNum(contract.energy), Number(sdk.energy))
+    record('cargomass', toNum(contract.cargomass), Number(sdk.cargoMass))
+    record('hullmass', toNum(contract.hullmass), Number(sdk.shipMass))
+    record('capacity', toNum(contract.capacity), sdk.capacity ? Number(sdk.capacity) : undefined)
+
+    recordStatBlock('engines', contract.engines, sdk.engines)
+    recordStatBlock('generator', contract.generator, sdk.generator)
+    recordStatBlock('hauler', contract.hauler, sdk.hauler)
+
+    const normLane = (l: {slot_index?: unknown; [k: string]: unknown}) =>
+        Object.fromEntries(
+            Object.entries(l)
+                .filter(([k]) => k !== 'slot_index')
+                .map(([k, v]) => [k, toNum(v) ?? 0])
+        )
+
+    const compareLanes = (name: string, cLanes: unknown[], sLanes: unknown[]) => {
+        if (cLanes.length !== sLanes.length) {
+            mismatches.push(`  ${name}.length: contract=${cLanes.length} sdk=${sLanes.length}`)
+            return
+        }
+        for (let i = 0; i < cLanes.length; i++) {
+            const cn = JSON.stringify(normLane(cLanes[i] as Record<string, unknown>))
+            const sn = JSON.stringify(normLane(sLanes[i] as Record<string, unknown>))
+            if (cn !== sn) mismatches.push(`  ${name}[${i}]: contract=${cn} sdk=${sn}`)
+        }
+    }
+
+    compareLanes('gatherer_lanes', contract.gatherer_lanes as unknown[], sdk.gathererLanes ?? [])
+    compareLanes('crafter_lanes', contract.crafter_lanes as unknown[], sdk.crafterLanes ?? [])
+    compareLanes('loader_lanes', contract.loader_lanes as unknown[], sdk.loaderLanes ?? [])
+
+    if (contract.cargo.length > 0 || sdk.cargo.length > 0) {
+        const contractCargo = normaliseCargo(mergeContractCargo(contract.cargo))
+        const sdkCargo = normaliseCargo(sdk.cargo)
+        if (contractCargo.length !== sdkCargo.length) {
+            mismatches.push(
+                `  cargo.length: contract=${contractCargo.length} sdk=${sdkCargo.length}`
+            )
+        } else {
+            for (let i = 0; i < contractCargo.length; i++) {
+                const c = contractCargo[i]
+                const s = sdkCargo[i]
+                if (c.itemId !== s.itemId || c.stats !== s.stats || c.quantity !== s.quantity) {
+                    mismatches.push(
+                        `  cargo[${i}]: contract={item:${c.itemId},stats:${c.stats},qty:${c.quantity}} sdk={item:${s.itemId},stats:${s.stats},qty:${s.quantity}}`
+                    )
+                }
+            }
+        }
+    }
+
+    if (mismatches.length > 0) {
+        const header =
+            options.step !== undefined
+                ? `projection divergence at step ${options.step}:`
+                : 'projection divergence:'
+        throw new Error([header, ...mismatches].join('\n'))
+    }
+}
+
+interface NormalisedStack {
+    itemId: number
+    stats: string
+    quantity: string
+}
+
+function mergeContractCargo(cargo: ServerContract.Types.cargo_view[]): CargoStack[] {
+    return cargo.reduce<CargoStack[]>(
+        (acc, row) =>
+            mergeStacks(acc, cargoItemToStack(row as unknown as ServerContract.Types.cargo_item)),
+        []
+    )
+}
+
+function normaliseCargo(cargo: CargoStack[]): NormalisedStack[] {
+    return cargo
+        .map((s) => ({
+            itemId: Number(s.item_id),
+            stats: BigInt(s.stats.toString()).toString(),
+            quantity: BigInt(s.quantity.toString()).toString(),
+        }))
+        .sort(stackSort)
+}
+
+function stackSort(a: NormalisedStack, b: NormalisedStack): number {
+    if (a.itemId !== b.itemId) return a.itemId - b.itemId
+    return a.stats < b.stats ? -1 : a.stats > b.stats ? 1 : 0
+}
+
+function toNum(v: unknown): number | undefined {
+    if (v === undefined || v === null) return undefined
+    if (typeof v === 'number') return v
+    if (typeof v === 'bigint') return Number(v)
+    if (typeof (v as {toNumber?: unknown}).toNumber === 'function') {
+        return (v as {toNumber(): number}).toNumber()
+    }
+    return Number(v as number)
+}
+
+function fmt(v: unknown): string {
+    if (v === undefined) return 'undefined'
+    if (v === null) return 'null'
+    return String(v)
+}
+
+function normaliseStatBlock(block: unknown): Record<string, number> {
+    const out: Record<string, number> = {}
+    const obj = block as Record<string, unknown>
+    for (const k of Object.keys(obj).sort()) {
+        out[k] = toNum(obj[k]) ?? 0
+    }
+    return out
+}

package/src/travel/reach.ts

@@ -0,0 +1,23 @@
+export interface ReachStats {
+    generator?: {capacity: bigint}
+    engines?: {drain: bigint}
+    hauler?: {drain: bigint}
+}
+
+export function computePerLegReach(s: ReachStats, haulCount = 0): number {
+    const capacity = s.generator?.capacity
+    const drain = s.engines?.drain
+    if (capacity === undefined || drain === undefined || drain === 0n) {
+        throw new Error('entity has no usable engine/generator (cannot compute per-leg reach)')
+    }
+    const haulDrain = s.hauler && haulCount > 0 ? s.hauler.drain * BigInt(haulCount) : 0n
+    return Number(capacity) / Number(drain + haulDrain)
+}
+
+export function computeGroupPerLegReach(participants: ReachStats[], haulCount: number): number {
+    const movers = participants.filter((p) => p.engines !== undefined && p.engines.drain !== 0n)
+    if (movers.length === 0) {
+        throw new Error('group has no moving entity (cannot compute per-leg reach)')
+    }
+    return Math.min(...movers.map((p) => computePerLegReach(p, haulCount)))
+}

package/src/travel/route-planner.ts

@@ -0,0 +1,196 @@
+import {distanceBetweenPoints, findNearbyPlanets} from './travel'
+import {hasSystem} from '../utils/system'
+import {nearbyWormholes, wormholeAt} from '../derivation/wormhole'
+import {PRECISION} from '../types'
+import {Checksum256, type Checksum256Type} from '@wharfkit/antelope'
+
+export interface Coord {
+    x: number
+    y: number
+}
+
+export interface Neighbor {
+    coord: Coord
+    dist: number
+}
+
+export interface SystemGraph {
+    hasSystem(c: Coord): boolean
+    nearby(c: Coord, reachTiles: number): Neighbor[]
+}
+
+export interface RoutePlan {
+    ok: true
+    waypoints: Coord[]
+    legs: number
+    totalDistance: number
+}
+
+export type RouteFailureReason = 'empty-destination' | 'no-path' | 'max-legs'
+
+export interface RouteFailure {
+    ok: false
+    reason: RouteFailureReason
+    furthest?: Coord
+    legsNeeded?: number
+    partialWaypoints?: Coord[]
+}
+
+export type RouteResult = RoutePlan | RouteFailure
+
+export interface PlanRouteParams {
+    origin: Coord
+    dest: Coord
+    perLegReach: number
+    graph: SystemGraph
+    corridorSlack?: number
+    nodeBudget?: number
+    maxLegs?: number
+}
+
+const key = (c: Coord): string => `${c.x},${c.y}`
+const sameCoord = (a: Coord, b: Coord): boolean => a.x === b.x && a.y === b.y
+const dist = (a: Coord, b: Coord): number => Math.hypot(a.x - b.x, a.y - b.y)
+
+export const MAX_LEGS = 12
+
+export function planRoute(params: PlanRouteParams): RouteResult {
+    const {origin, dest, perLegReach, graph} = params
+    const corridorSlack = params.corridorSlack ?? perLegReach
+    const nodeBudget = params.nodeBudget ?? 5000
+    const maxLegs = params.maxLegs ?? MAX_LEGS
+
+    if (!graph.hasSystem(dest)) {
+        return {ok: false, reason: 'empty-destination'}
+    }
+
+    const straightLine = dist(origin, dest)
+    const heuristic = (c: Coord): number => Math.ceil(dist(c, dest) / perLegReach)
+
+    const gScore = new Map<string, number>([[key(origin), 0]])
+    const cameFrom = new Map<string, Coord>()
+    const frontier: {coord: Coord; g: number; f: number; remaining: number}[] = [
+        {coord: origin, g: 0, f: heuristic(origin), remaining: straightLine},
+    ]
+
+    let furthest = origin
+    let furthestRemaining = dist(origin, dest)
+    let expansions = 0
+    let cappedByMaxLegs = false
+
+    while (frontier.length > 0) {
+        let bestIdx = 0
+        for (let i = 1; i < frontier.length; i++) {
+            const a = frontier[i]
+            const b = frontier[bestIdx]
+            if (a.f < b.f || (a.f === b.f && a.remaining < b.remaining)) {
+                bestIdx = i
+            }
+        }
+        const current = frontier.splice(bestIdx, 1)[0]
+
+        if (sameCoord(current.coord, dest)) {
+            return reconstruct(cameFrom, origin, dest)
+        }
+
+        if (current.remaining < furthestRemaining) {
+            furthestRemaining = current.remaining
+            furthest = current.coord
+        }
+
+        if (++expansions > nodeBudget) break
+
+        for (const n of graph.nearby(current.coord, perLegReach)) {
+            const inCorridor =
+                dist(origin, n.coord) + dist(n.coord, dest) <= straightLine + corridorSlack
+            if (!inCorridor) continue
+
+            const tentativeG = current.g + 1
+            if (tentativeG > maxLegs) {
+                cappedByMaxLegs = true
+                continue
+            }
+            const nk = key(n.coord)
+            if (tentativeG < (gScore.get(nk) ?? Infinity)) {
+                gScore.set(nk, tentativeG)
+                cameFrom.set(nk, current.coord)
+                const remaining = dist(n.coord, dest)
+                frontier.push({
+                    coord: n.coord,
+                    g: tentativeG,
+                    f: tentativeG + Math.ceil(remaining / perLegReach),
+                    remaining,
+                })
+            }
+        }
+    }
+
+    if (cappedByMaxLegs) {
+        return {
+            ok: false,
+            reason: 'max-legs',
+            furthest,
+            partialWaypoints: reconstructWaypoints(cameFrom, origin, furthest),
+        }
+    }
+    return {
+        ok: false,
+        reason: 'no-path',
+        furthest,
+        partialWaypoints: reconstructWaypoints(cameFrom, origin, furthest),
+    }
+}
+
+function reconstructWaypoints(cameFrom: Map<string, Coord>, origin: Coord, target: Coord): Coord[] {
+    if (sameCoord(target, origin)) return []
+    const path: Coord[] = [target]
+    let cur = target
+    while (!sameCoord(cur, origin)) {
+        const prev = cameFrom.get(key(cur))
+        if (!prev) break
+        path.unshift(prev)
+        cur = prev
+    }
+    return path.slice(1)
+}
+
+function reconstruct(cameFrom: Map<string, Coord>, origin: Coord, dest: Coord): RoutePlan {
+    const path: Coord[] = [dest]
+    let cur = dest
+    let totalDistance = 0
+    while (!sameCoord(cur, origin)) {
+        const prev = cameFrom.get(key(cur))
+        if (!prev) break
+        totalDistance += dist(prev, cur)
+        path.unshift(prev)
+        cur = prev
+    }
+    const waypoints = path.slice(1)
+    return {ok: true, waypoints, legs: waypoints.length, totalDistance}
+}
+
+export function sdkSystemGraph(seed: Checksum256Type): SystemGraph {
+    const s = Checksum256.from(seed)
+    // Travelable nodes mirror the contract's is_travelable: systems plus wormhole mouths.
+    return {
+        hasSystem: (c) => hasSystem(s, {x: c.x, y: c.y}) || wormholeAt(s, c.x, c.y) !== null,
+        nearby: (c, reachTiles) => {
+            const seen = new Set<string>([`${c.x},${c.y}`])
+            const out: Neighbor[] = []
+            for (const d of findNearbyPlanets(s, {x: c.x, y: c.y}, reachTiles * PRECISION)) {
+                const coord = {x: Number(d.destination.x), y: Number(d.destination.y)}
+                const k = `${coord.x},${coord.y}`
+                if (seen.has(k)) continue
+                seen.add(k)
+                out.push({coord, dist: Number(d.distance) / PRECISION})
+            }
+            for (const coord of nearbyWormholes(s, c.x, c.y, reachTiles)) {
+                const k = `${coord.x},${coord.y}`
+                if (seen.has(k)) continue
+                seen.add(k)
+                out.push({coord, dist: Math.hypot(coord.x - c.x, coord.y - c.y)})
+            }
+            return out
+        },
+    }
+}