@shipload/sdk 1.0.0-next.6 → 1.0.0-next.60

package/src/testing/projection-parity.ts

@@ -0,0 +1,167 @@
+import type {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?: UInt32
+    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,21 @@
+export interface ReachStats {
+    generator?: {capacity: bigint}
+    engines?: {drain: bigint}
+}
+
+export function computePerLegReach(s: ReachStats): 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)')
+    }
+    return Number(capacity) / Number(drain)
+}
+
+export function computeGroupPerLegReach(participants: ReachStats[]): 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(computePerLegReach))
+}

package/src/travel/route-planner.ts

@@ -0,0 +1,288 @@
+import {nearbyWormholes, wormholeAt} from '../derivation/wormhole'
+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 interface RouteLegInput {
+    from: Coord
+    to: Coord
+    distance: number
+    isDestination: boolean
+}
+
+/**
+ * Returns the elapsed-time search cost for a leg, or null when the leg is not contract-feasible.
+ */
+export type RouteLegCost = (leg: RouteLegInput) => number | null
+export type RouteHeuristicCost = (from: Coord, dest: Coord) => 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
+    legCost?: RouteLegCost
+    heuristicCost?: RouteHeuristicCost
+}
+
+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)
+    if (straightLine <= perLegReach) {
+        const directCost = params.legCost?.({
+            from: origin,
+            to: dest,
+            distance: straightLine,
+            isDestination: true,
+        })
+        if (directCost !== null) {
+            return {ok: true, waypoints: [dest], legs: 1, totalDistance: straightLine}
+        }
+    }
+    const heuristic = (c: Coord): number =>
+        params.heuristicCost?.(c, dest) ??
+        (params.legCost ? 0 : 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; legs: number; cost: number; f: number; remaining: number}[] = [
+        {coord: origin, legs: 0, cost: 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 (current.cost !== gScore.get(key(current.coord))) continue
+
+        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 tentativeLegs = current.legs + 1
+            if (tentativeLegs > maxLegs) {
+                cappedByMaxLegs = true
+                continue
+            }
+            const evaluatedCost = params.legCost?.({
+                from: current.coord,
+                to: n.coord,
+                distance: n.dist,
+                isDestination: sameCoord(n.coord, dest),
+            })
+            if (evaluatedCost === null) continue
+            const legCost = evaluatedCost ?? 1
+            if (!(legCost >= 0) || !Number.isFinite(legCost)) continue
+            const nk = key(n.coord)
+            const nextCost = current.cost + legCost
+            if (nextCost < (gScore.get(nk) ?? Infinity)) {
+                gScore.set(nk, nextCost)
+                cameFrom.set(nk, current.coord)
+                const remaining = dist(n.coord, dest)
+                frontier.push({
+                    coord: n.coord,
+                    legs: tentativeLegs,
+                    cost: nextCost,
+                    f: nextCost + heuristic(n.coord),
+                    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 interface ScanProvider {
+    getLocationType(seedHex: string, x: number, y: number): number
+    systemsInBox(
+        seedHex: string,
+        xMin: number,
+        yMin: number,
+        xMax: number,
+        yMax: number
+    ): {x: number; y: number; locType: number}[]
+}
+
+// Keyed by provider identity, so pass a stable one (the `@shipload/sdk/scan` namespace).
+const graphCache = new WeakMap<ScanProvider, Map<string, SystemGraph>>()
+
+export function sdkSystemGraph(seed: Checksum256Type, scan: ScanProvider): SystemGraph {
+    const s = Checksum256.from(seed)
+    const seedHex = s.toString()
+    let bySeed = graphCache.get(scan)
+    if (!bySeed) {
+        bySeed = new Map()
+        graphCache.set(scan, bySeed)
+    }
+    const cached = bySeed.get(seedHex)
+    if (cached) return cached
+    const graph = wasmSystemGraph(s, seedHex, scan)
+    bySeed.set(seedHex, graph)
+    return graph
+}
+
+const SCAN_BUCKET = 48
+
+function wasmSystemGraph(s: Checksum256, seedHex: string, scan: ScanProvider): SystemGraph {
+    // Per-bucket system cache: reused across the overlapping node queries A* makes (and across routes).
+    const bucketCache = new Map<string, {x: number; y: number}[]>()
+    const bucketSystems = (bx: number, by: number): {x: number; y: number}[] => {
+        const k = `${bx},${by}`
+        let v = bucketCache.get(k)
+        if (v === undefined) {
+            const xMin = bx * SCAN_BUCKET
+            const yMin = by * SCAN_BUCKET
+            v = scan
+                .systemsInBox(seedHex, xMin, yMin, xMin + SCAN_BUCKET - 1, yMin + SCAN_BUCKET - 1)
+                .map((cell) => ({x: cell.x, y: cell.y}))
+            bucketCache.set(k, v)
+        }
+        return v
+    }
+    return {
+        hasSystem: (c) =>
+            scan.getLocationType(seedHex, c.x, c.y) !== 0 || wormholeAt(s, c.x, c.y) !== null,
+        nearby: (c, reachTiles) => {
+            const r = Math.floor(reachTiles)
+            const seen = new Set<string>([`${c.x},${c.y}`])
+            const out: Neighbor[] = []
+            const bx0 = Math.floor((c.x - r) / SCAN_BUCKET)
+            const bx1 = Math.floor((c.x + r) / SCAN_BUCKET)
+            const by0 = Math.floor((c.y - r) / SCAN_BUCKET)
+            const by1 = Math.floor((c.y + r) / SCAN_BUCKET)
+            for (let bx = bx0; bx <= bx1; bx++) {
+                for (let by = by0; by <= by1; by++) {
+                    for (const cell of bucketSystems(bx, by)) {
+                        const dist = Math.hypot(cell.x - c.x, cell.y - c.y)
+                        if (dist > reachTiles) continue
+                        const k = `${cell.x},${cell.y}`
+                        if (seen.has(k)) continue
+                        seen.add(k)
+                        out.push({coord: {x: cell.x, y: cell.y}, dist})
+                    }
+                }
+            }
+            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
+        },
+    }
+}

package/src/travel/route-simulator.ts

@@ -0,0 +1,170 @@
+import type {UInt64Type} from '@wharfkit/antelope'
+import {PRECISION, TRAVEL_MAX_DURATION} from '../types'
+import {
+    calc_energyusage,
+    calc_group_flighttime,
+    calc_rechargetime,
+    distanceBetweenPoints,
+} from './travel'
+
+export interface RouteMoverInput {
+    ref: {entityType: string; entityId: UInt64Type}
+    hasMovement: boolean
+    engines?: {thrust: number; drain: number}
+    generator?: {capacity: number; recharge: number}
+    hauler?: {capacity: number; efficiency: number}
+    mass: number
+    energy: number
+    priorMobilityEnd: number
+    narrowBarrierEnd: number
+    /** Max end (seconds-from-now) over all this entity's lanes incl. worker/craft; gates recharges like the contract's all_lanes_end. Default 0. */
+    allLanesEnd?: number
+}
+
+export interface RouteLegSim {
+    from: {x: number; y: number}
+    to: {x: number; y: number}
+    distanceCells: number
+    energyCostByMover: Record<string, number>
+    rechargeBefore: boolean
+    rechargeSeconds: number
+    flightSeconds: number
+}
+
+export interface RouteSim {
+    legs: RouteLegSim[]
+    totalSeconds: number
+    reachable: boolean
+}
+
+export function simulateRoute(
+    movers: RouteMoverInput[],
+    waypoints: {x: number; y: number}[],
+    origin: {x: number; y: number},
+    recharge: boolean
+): RouteSim {
+    const totalThrust = movers
+        .filter((m) => m.hasMovement && m.engines)
+        .reduce((sum, m) => sum + m.engines!.thrust, 0)
+
+    const totalMass = movers.reduce((sum, m) => sum + m.mass, 0)
+
+    const haulCount = movers.filter((m) => !m.hasMovement).length
+
+    const pooledHaulCap = movers
+        .filter((m) => m.hasMovement && m.hauler)
+        .reduce((sum, m) => sum + m.hauler!.capacity, 0)
+
+    const weightedHaulEffNum = movers
+        .filter((m) => m.hasMovement && m.hauler)
+        .reduce((sum, m) => sum + m.hauler!.efficiency * m.hauler!.capacity, 0)
+
+    const energyByMover: Map<string, number> = new Map(
+        movers.map((m) => [String(m.ref.entityId), m.energy])
+    )
+
+    let reachable = true
+    const legs: RouteLegSim[] = []
+
+    const mobilityBarrier = movers
+        .filter((m) => m.hasMovement)
+        .reduce((mx, m) => Math.max(mx, m.priorMobilityEnd, m.narrowBarrierEnd), 0)
+
+    const rechargeFloor = movers
+        .filter((m) => m.hasMovement && m.generator)
+        .reduce((mx, m) => Math.max(mx, m.allLanesEnd ?? 0), 0)
+
+    let clock = 0
+
+    let from = origin
+    for (const to of waypoints) {
+        const distance = distanceBetweenPoints(from.x, from.y, to.x, to.y)
+        const distanceNum = Number(distance)
+        const distanceCells = distanceNum / PRECISION
+
+        const energyCostByMover: Record<string, number> = {}
+
+        for (const m of movers) {
+            if (!m.hasMovement || !m.engines) continue
+            const key = String(m.ref.entityId)
+            energyCostByMover[key] = Number(calc_energyusage(distance, m.engines.drain))
+        }
+
+        let rechargeBefore = false
+        let rechargeSeconds = 0
+
+        if (recharge) {
+            let maxDur = 0
+            for (const m of movers) {
+                if (!m.hasMovement || !m.generator) continue
+                const key = String(m.ref.entityId)
+                const curEnergy = energyByMover.get(key) ?? 0
+                const dur = Number(
+                    calc_rechargetime(m.generator.capacity, curEnergy, m.generator.recharge)
+                )
+                if (dur > maxDur) maxDur = dur
+            }
+            rechargeSeconds = maxDur
+            rechargeBefore = rechargeSeconds > 0
+
+            if (rechargeBefore) {
+                for (const m of movers) {
+                    if (!m.hasMovement || !m.generator) continue
+                    const key = String(m.ref.entityId)
+                    energyByMover.set(key, m.generator.capacity)
+                }
+                clock = Math.max(clock, rechargeFloor) + rechargeSeconds
+            }
+        }
+
+        for (const m of movers) {
+            if (!m.hasMovement || !m.engines) continue
+            const key = String(m.ref.entityId)
+            const cost = energyCostByMover[key] ?? 0
+            const curEnergy = energyByMover.get(key) ?? 0
+
+            if (recharge && m.generator) {
+                if (cost > m.generator.capacity) reachable = false
+            } else {
+                if (cost > curEnergy) reachable = false
+            }
+        }
+
+        const flightSeconds = Number(
+            calc_group_flighttime(
+                totalThrust,
+                haulCount,
+                pooledHaulCap,
+                weightedHaulEffNum,
+                totalMass,
+                distance
+            )
+        )
+
+        if (flightSeconds > TRAVEL_MAX_DURATION) reachable = false
+
+        for (const m of movers) {
+            if (!m.hasMovement || !m.engines) continue
+            const key = String(m.ref.entityId)
+            const cost = energyCostByMover[key] ?? 0
+            const curEnergy = energyByMover.get(key) ?? 0
+            energyByMover.set(key, Math.max(0, curEnergy - cost))
+        }
+
+        clock = Math.max(clock, mobilityBarrier) + flightSeconds
+
+        legs.push({
+            from,
+            to,
+            distanceCells,
+            energyCostByMover,
+            rechargeBefore,
+            rechargeSeconds,
+            flightSeconds,
+        })
+
+        from = to
+    }
+
+    return {legs, totalSeconds: clock, reachable}
+}