@shipload/sdk 1.0.0-next.47 → 1.0.0-next.49

package/src/index-module.ts

@@ -150,6 +150,8 @@ export type {ReserveTier, TierRange} from './derivation'
 export {getEffectiveReserve} from './derivation'
 export type {EffectiveReserveInput} from './derivation'
 
+export {eligibleUpgrades} from './derivation'
+
 export {getStatDefinitions, getStatName, resolveStats} from './derivation'
 export type {StatDefinition, NamedStats} from './derivation'
 
@@ -568,5 +570,21 @@ export type {DescribeOptions} from './resolution/display-name'
 
 export * from './subscriptions'
 
-export {planParallelGather, planParallelTransfer} from './planner'
-export type {LanePlanEntry, PlanTarget, GatherPlanEntity} from './planner'
+export {
+    allocateProportional,
+    buildGatherPlan,
+    gatherEnergyCost,
+    maxQtyForCharge,
+    planParallelTransfer,
+    splitCost,
+} from './planner'
+export type {
+    BuildGatherPlanOpts,
+    FillCap,
+    GatherCycle,
+    GatherLimpet,
+    GatherPlan,
+    GatherPlanEntity,
+    LanePlanEntry,
+    PlanTarget,
+} from './planner'

package/src/managers/actions.ts

@@ -21,6 +21,7 @@ import {Coordinates, PRECISION, type ClusterSlotType, type CoordinatesType} from
 import {ServerContract} from '../contracts'
 import {ATOMICASSETS_ABI, SHIPLOAD_COLLECTION} from '../nft/atomicassets'
 import {getItem} from '../data/catalog'
+import type {GatherPlan} from '../planner'
 
 const CHARGE_K = 1n
 const ENERGY_DIVISOR = 1_000_000n
@@ -394,6 +395,29 @@ export class ActionsManager extends BaseManager {
         })
     }
 
+    // Mirrors the contract's projected_energy walk: recharge (if due) then gathers, per cycle.
+    flattenGatherPlan(
+        plan: GatherPlan,
+        ctx: {sourceId: UInt64Type; destinationId: UInt64Type; stratum: UInt16Type}
+    ): Action[] {
+        const actions: Action[] = []
+        for (const cycle of plan.cycles) {
+            if (cycle.rechargeBefore) actions.push(this.recharge(ctx.sourceId))
+            for (const limpet of cycle.limpets) {
+                actions.push(
+                    this.gather(
+                        ctx.sourceId,
+                        ctx.destinationId,
+                        ctx.stratum,
+                        limpet.quantity,
+                        limpet.slot
+                    )
+                )
+            }
+        }
+        return actions
+    }
+
     warp(entityId: UInt64Type, destination: CoordinatesType): Action {
         const x = Int64.from(destination.x)
         const y = Int64.from(destination.y)
@@ -447,6 +471,25 @@ export class ActionsManager extends BaseManager {
         })
     }
 
+    upgrade(
+        builderId: UInt64Type,
+        targetId: UInt64Type,
+        targetItemId: UInt16Type,
+        inputs: ServerContract.ActionParams.Type.cargo_item[],
+        slot?: UInt8Type
+    ): Action {
+        const params: ServerContract.ActionParams.upgrade = {
+            builder_id: UInt64.from(builderId),
+            target_id: UInt64.from(targetId),
+            target_item_id: UInt16.from(targetItemId),
+            inputs,
+        }
+        if (slot !== undefined) {
+            params.slot = UInt8.from(slot)
+        }
+        return this.server.action('upgrade', params)
+    }
+
     claimplot(entityId: UInt64Type, targetItemId: UInt16Type, slot: ClusterSlotType): Action {
         return this.server.action('claimplot', {
             builder_id: UInt64.from(entityId),

package/src/managers/flatten-gather-plan.test.ts

@@ -0,0 +1,80 @@
+import {expect, test, describe} from 'bun:test'
+import {makeClient} from '@wharfkit/mock-data'
+import {Serializer} from '@wharfkit/antelope'
+import type {GatherPlan} from '../planner'
+import {ActionsManager} from './actions'
+import {ServerContract} from '../contracts'
+
+const client = makeClient('https://jungle4.greymass.com')
+
+function makeActions() {
+    const realServer = new ServerContract.Contract({client})
+    const stubServer = {
+        account: realServer.account,
+        action: realServer.action.bind(realServer),
+    }
+    const context = {server: stubServer} as any
+    return new ActionsManager(context)
+}
+
+function fakePlan(): GatherPlan {
+    return {
+        cycles: [
+            {
+                rechargeBefore: false,
+                rechargeSeconds: 0,
+                gatherSeconds: 10,
+                batchOre: 30,
+                limpets: [
+                    {slot: 0, quantity: 20, durationSeconds: 10},
+                    {slot: 1, quantity: 10, durationSeconds: 8},
+                ],
+            },
+            {
+                rechargeBefore: true,
+                rechargeSeconds: 5,
+                gatherSeconds: 10,
+                batchOre: 30,
+                limpets: [{slot: 0, quantity: 30, durationSeconds: 10}],
+            },
+        ],
+        cycleCount: 2,
+        totalOre: 60,
+        totalSeconds: 25,
+        cap: 'requested',
+        reachingCount: 2,
+        totalLimpets: 2,
+        warnings: [],
+    }
+}
+
+describe('flattenGatherPlan', () => {
+    test('flattens cycles to [recharge?, gather x limpets] in order with slots', () => {
+        const actions = makeActions().flattenGatherPlan(fakePlan(), {
+            sourceId: 1,
+            destinationId: 1,
+            stratum: 100,
+        })
+        expect(actions.map((a) => a.name.toString())).toEqual([
+            'gather',
+            'gather',
+            'recharge',
+            'gather',
+        ])
+        expect(actions.filter((a) => a.name.toString() === 'recharge').length).toBe(1)
+        const gatherSlots = actions
+            .filter((a) => a.name.toString() === 'gather')
+            .map((a) => {
+                const decoded = Serializer.decode({data: a.data, type: ServerContract.Types.gather})
+                return Number(decoded.slot)
+            })
+        expect(gatherSlots).toEqual([0, 1, 0])
+    })
+
+    test('empty plan produces no actions', () => {
+        const empty = {...fakePlan(), cycles: [], cycleCount: 0, totalOre: 0}
+        expect(
+            makeActions().flattenGatherPlan(empty, {sourceId: 1, destinationId: 1, stratum: 100})
+        ).toHaveLength(0)
+    })
+})

package/src/nft/description.ts

@@ -104,7 +104,7 @@ export const computeBatteryBankCapacity = (
 export function entityDisplayName(itemId: number): string {
     switch (itemId) {
         case ITEM_SHIP_T1_PACKED:
-            return 'Ship'
+            return 'Roustabout'
         case ITEM_WAREHOUSE_T1_PACKED:
             return 'Warehouse'
         case ITEM_EXTRACTOR_T1_PACKED:

package/src/planner/index.ts

@@ -1,10 +1,7 @@
 import type {GathererStats} from '../types/capabilities'
 import type {ServerContract} from '../contracts'
-import {
-    calc_gather_duration,
-    calc_gather_energy,
-    GATHER_MASS_DIVISOR,
-} from '../capabilities/gathering'
+import {calc_gather_duration, calc_gather_energy} from '../capabilities/gathering'
+import {calc_rechargetime} from '../travel/travel'
 import {projectRemainingAt, type Projectable} from '../scheduling/projection'
 
 export interface LanePlanEntry {
@@ -19,26 +16,46 @@ export interface GatherPlanEntity extends Projectable {
     loader_lanes: ServerContract.Types.loader_lane[]
 }
 
-// massFactor=1 so plan-time cost is conservative; on-chain recomputes with real mass/richness.
-const PLAN_ITEM_MASS = GATHER_MASS_DIVISOR
-const PLAN_RICHNESS = 1000
+export interface GatherLimpet {
+    slot: number
+    quantity: number
+    durationSeconds: number
+}
 
-// 'max' ceiling; Phase 3 passes a real reserve/capacity cap instead.
-const MAX_PLAN_QTY = 10000
+export interface GatherCycle {
+    rechargeBefore: boolean
+    rechargeSeconds: number
+    limpets: GatherLimpet[]
+    gatherSeconds: number
+    batchOre: number
+}
 
-function gatherEnergyCost(
-    lane: ServerContract.Types.gatherer_lane,
-    quantity: number,
-    stratum: number
-): number {
-    const stats = lane as unknown as GathererStats
-    const dur = Number(
-        calc_gather_duration(stats, PLAN_ITEM_MASS, quantity, stratum, PLAN_RICHNESS)
-    )
-    return Number(calc_gather_energy(stats, dur))
+export type FillCap = 'reserve' | 'hold' | 'requested'
+
+export interface GatherPlan {
+    cycles: GatherCycle[]
+    cycleCount: number
+    totalOre: number
+    totalSeconds: number
+    cap: FillCap
+    reachingCount: number
+    totalLimpets: number
+    warnings: string[]
 }
 
-function allocateProportional(
+export interface BuildGatherPlanOpts {
+    richness: number
+    itemMass: number
+    holdRoom: number
+    reserveRemaining: number
+    now: Date
+}
+
+const MAX_CYCLES = 10_000
+
+const MAX_TRANSFER_QTY = 10000
+
+export function allocateProportional(
     lanes: {slot: number; weight: number}[],
     total: number
 ): LanePlanEntry[] {
@@ -60,53 +77,151 @@ function allocateProportional(
     return entries
 }
 
-export function planParallelGather(
+function laneStats(lane: ServerContract.Types.gatherer_lane): GathererStats {
+    return lane as unknown as GathererStats
+}
+
+export function gatherEnergyCost(
+    lane: ServerContract.Types.gatherer_lane,
+    quantity: number,
+    stratum: number,
+    itemMass: number,
+    richness: number
+): number {
+    if (quantity <= 0) return 0
+    const dur = Number(calc_gather_duration(laneStats(lane), itemMass, quantity, stratum, richness))
+    return Number(calc_gather_energy(laneStats(lane), dur))
+}
+
+export function splitCost(
+    reaching: ServerContract.Types.gatherer_lane[],
+    quantity: number,
+    stratum: number,
+    itemMass: number,
+    richness: number
+): number {
+    if (quantity <= 0) return 0
+    const weights = reaching.map((l) => ({
+        slot: l.slot_index.toNumber(),
+        weight: l.yield.toNumber(),
+    }))
+    const split = allocateProportional(weights, quantity)
+    return split.reduce((sum, e) => {
+        const lane = reaching.find((l) => l.slot_index.toNumber() === e.slot)!
+        return sum + gatherEnergyCost(lane, e.quantity, stratum, itemMass, richness)
+    }, 0)
+}
+
+// Binary search is exact because splitCost is monotonic non-decreasing in Q.
+export function maxQtyForCharge(
+    reaching: ServerContract.Types.gatherer_lane[],
+    hi: number,
+    capacity: number,
+    stratum: number,
+    itemMass: number,
+    richness: number
+): number {
+    if (hi <= 0) return 0
+    if (splitCost(reaching, hi, stratum, itemMass, richness) <= capacity) return hi
+    let lo = 0
+    let high = hi
+    while (lo < high) {
+        const mid = Math.ceil((lo + high) / 2)
+        if (splitCost(reaching, mid, stratum, itemMass, richness) <= capacity) lo = mid
+        else high = mid - 1
+    }
+    return lo
+}
+
+export function buildGatherPlan(
     entity: GatherPlanEntity,
-    target: PlanTarget,
     stratum: number,
-    now: Date
-): LanePlanEntry[] {
+    target: PlanTarget,
+    opts: BuildGatherPlanOpts
+): GatherPlan {
+    const {richness, itemMass, holdRoom, reserveRemaining, now} = opts
+    const warnings: string[] = []
+
     const reaching = entity.gatherer_lanes.filter((l) => l.depth.toNumber() >= stratum)
     if (reaching.length === 0) throw new Error('no gatherer reaches this stratum')
+    if (!entity.generator) throw new Error('entity has no generator')
 
-    // Projected energy nets out already-queued/in-flight task costs (contract projected_energy()).
-    const energy = entity.generator ? Number(projectRemainingAt(entity, now).energy) : Infinity
+    const blocked = entity.gatherer_lanes.length - reaching.length
+    if (blocked > 0) {
+        warnings.push(
+            `${blocked} of ${entity.gatherer_lanes.length} limpets can't reach this depth`
+        )
+    }
+
+    const capacity = entity.generator.capacity.toNumber()
+    const rechargeRate = entity.generator.recharge.toNumber()
+    let energy = Number(projectRemainingAt(entity, now).energy)
 
-    const requestedQty = target === 'max' ? MAX_PLAN_QTY : (target as {quantity: number}).quantity
+    const requested = target === 'max' ? Infinity : target.quantity
+    let fillTarget = requested
+    let cap: FillCap = 'requested'
+    if (holdRoom < fillTarget) {
+        fillTarget = holdRoom
+        cap = 'hold'
+    }
+    if (reserveRemaining < fillTarget) {
+        fillTarget = reserveRemaining
+        cap = 'reserve'
+    }
+    fillTarget = Math.max(0, Math.floor(fillTarget))
+
+    const cycles: GatherCycle[] = []
+    let remaining = fillTarget
+    let guard = 0
+    while (remaining > 0 && guard++ < MAX_CYCLES) {
+        const batch = maxQtyForCharge(reaching, remaining, capacity, stratum, itemMass, richness)
+        if (batch <= 0) {
+            warnings.push('a single gather cannot fit within one full charge')
+            break
+        }
 
-    // Ascending by yield so slice(1) sheds the lowest-yield lane first when energy-starved.
-    let activeLanes = reaching.slice().sort((a, b) => a.yield.toNumber() - b.yield.toNumber())
+        const costFull = splitCost(reaching, batch, stratum, itemMass, richness)
+        const rechargeBefore = energy < costFull
+        const rechargeSeconds = rechargeBefore
+            ? Number(calc_rechargetime(capacity, energy, rechargeRate))
+            : 0
+        if (rechargeBefore) energy = capacity
 
-    while (activeLanes.length > 0) {
-        const laneWeights = activeLanes.map((l) => ({
+        const weights = reaching.map((l) => ({
             slot: l.slot_index.toNumber(),
             weight: l.yield.toNumber(),
         }))
-
-        const proposed = allocateProportional(laneWeights, requestedQty)
-
-        const totalEnergyCost = proposed.reduce((sum, entry) => {
-            const lane = activeLanes.find((l) => l.slot_index.toNumber() === entry.slot)!
-            return sum + gatherEnergyCost(lane, entry.quantity, stratum)
+        const split = allocateProportional(weights, batch).filter((e) => e.quantity > 0)
+        const limpets: GatherLimpet[] = split.map((e) => {
+            const lane = reaching.find((l) => l.slot_index.toNumber() === e.slot)!
+            const dur = Number(
+                calc_gather_duration(laneStats(lane), itemMass, e.quantity, stratum, richness)
+            )
+            return {slot: e.slot, quantity: e.quantity, durationSeconds: dur}
+        })
+        const actualCost = limpets.reduce((sum, l) => {
+            const lane = reaching.find((r) => r.slot_index.toNumber() === l.slot)!
+            return sum + Number(calc_gather_energy(laneStats(lane), l.durationSeconds))
         }, 0)
+        energy = Math.max(0, energy - actualCost)
 
-        if (totalEnergyCost <= energy) {
-            return proposed.filter((e) => e.quantity > 0)
-        }
-
-        if (activeLanes.length === 1) {
-            const lane = activeLanes[0]
-            const energyPerUnit = gatherEnergyCost(lane, 1, stratum)
-            if (energyPerUnit === 0) return proposed.filter((e) => e.quantity > 0)
-            const maxQty = Math.min(requestedQty, Math.floor(energy / energyPerUnit))
-            if (maxQty <= 0) return []
-            return [{slot: lane.slot_index.toNumber(), quantity: maxQty}]
-        }
-
-        activeLanes = activeLanes.slice(1)
+        const gatherSeconds = limpets.reduce((m, l) => Math.max(m, l.durationSeconds), 0)
+        cycles.push({rechargeBefore, rechargeSeconds, limpets, gatherSeconds, batchOre: batch})
+        remaining -= batch
     }
 
-    return []
+    const totalOre = cycles.reduce((s, c) => s + c.batchOre, 0)
+    const totalSeconds = cycles.reduce((s, c) => s + c.rechargeSeconds + c.gatherSeconds, 0)
+    return {
+        cycles,
+        cycleCount: cycles.length,
+        totalOre,
+        totalSeconds,
+        cap,
+        reachingCount: reaching.length,
+        totalLimpets: entity.gatherer_lanes.length,
+        warnings,
+    }
 }
 
 export function planParallelTransfer(
@@ -116,7 +231,7 @@ export function planParallelTransfer(
     const lanes = entity.loader_lanes.filter((l) => l.thrust.toNumber() > 0)
     if (lanes.length === 0) return []
 
-    const requestedQty = target === 'max' ? MAX_PLAN_QTY : (target as {quantity: number}).quantity
+    const requestedQty = target === 'max' ? MAX_TRANSFER_QTY : target.quantity
 
     const laneWeights = lanes.map((l) => ({
         slot: l.slot_index.toNumber(),