@shipload/sdk 1.0.0-next.5 → 1.0.0-next.50

package/src/planner/planner.test.ts

@@ -0,0 +1,325 @@
+import {UInt8, UInt16, UInt32, UInt64} from '@wharfkit/antelope'
+import {expect, test, describe} from 'bun:test'
+import {ServerContract} from '../contracts'
+import {
+    planParallelTransfer,
+    type GatherPlanEntity,
+    gatherEnergyCost,
+    splitCost,
+    maxQtyForCharge,
+    buildGatherPlan,
+} from './index'
+
+function gathererLane(
+    slotIndex: number,
+    yieldVal: number,
+    drain: number,
+    depth: number
+): ServerContract.Types.gatherer_lane {
+    return ServerContract.Types.gatherer_lane.from({
+        slot_index: UInt8.from(slotIndex),
+        yield: UInt16.from(yieldVal),
+        drain: UInt32.from(drain),
+        depth: UInt16.from(depth),
+        output_pct: UInt16.from(100),
+    })
+}
+
+function loaderLane(
+    slotIndex: number,
+    mass: number,
+    thrust: number
+): ServerContract.Types.loader_lane {
+    return ServerContract.Types.loader_lane.from({
+        slot_index: UInt8.from(slotIndex),
+        mass: UInt32.from(mass),
+        thrust: UInt16.from(thrust),
+        output_pct: UInt16.from(100),
+    })
+}
+
+function energyStats(capacity: number, recharge: number): ServerContract.Types.energy_stats {
+    return ServerContract.Types.energy_stats.from({
+        capacity: UInt32.from(capacity),
+        recharge: UInt32.from(recharge),
+    })
+}
+
+interface EntityOverrides {
+    gatherer_lanes?: ServerContract.Types.gatherer_lane[]
+    loader_lanes?: ServerContract.Types.loader_lane[]
+    generator?: ServerContract.Types.energy_stats
+    energy?: number
+    lanes?: ServerContract.Types.lane[]
+}
+
+function entity(overrides: EntityOverrides = {}): GatherPlanEntity {
+    return {
+        gatherer_lanes: overrides.gatherer_lanes ?? [],
+        loader_lanes: overrides.loader_lanes ?? [],
+        generator: overrides.generator,
+        energy: overrides.energy !== undefined ? UInt16.from(overrides.energy) : undefined,
+        lanes: overrides.lanes ?? [],
+        coordinates: ServerContract.Types.coordinates.from({x: 0, y: 0}),
+        cargo: [],
+        cargomass: UInt32.from(0),
+    }
+}
+
+const NOW = new Date('2026-06-21T00:00:00.000Z')
+
+describe('planParallelTransfer', () => {
+    test('two loader lanes: quantities proportional to thrust, sums to target', () => {
+        const THRUST1 = 100
+        const THRUST2 = 200
+        const QUANTITY = 90
+
+        const e = entity({
+            loader_lanes: [loaderLane(0, 500, THRUST1), loaderLane(1, 500, THRUST2)],
+        })
+
+        const plan = planParallelTransfer(e, {quantity: QUANTITY})
+
+        expect(plan).toHaveLength(2)
+        expect(plan.reduce((s, p) => s + p.quantity, 0)).toBe(QUANTITY)
+
+        const q1 = plan.find((p) => p.slot === 0)!.quantity
+        const q2 = plan.find((p) => p.slot === 1)!.quantity
+        expect(q2 / q1).toBeCloseTo(THRUST2 / THRUST1, 0)
+    })
+
+    test('no loader lanes: returns empty plan', () => {
+        const plan = planParallelTransfer(entity({loader_lanes: []}), {quantity: 10})
+        expect(plan).toHaveLength(0)
+    })
+
+    test('thrust=0 loader lane (no-loader/mobility case): returns empty plan', () => {
+        const plan = planParallelTransfer(entity({loader_lanes: [loaderLane(0, 500, 0)]}), {
+            quantity: 10,
+        })
+        expect(plan).toHaveLength(0)
+    })
+
+    test("'max' target: each loader lane gets >= 1 unit", () => {
+        const e = entity({
+            loader_lanes: [loaderLane(0, 500, 100), loaderLane(1, 500, 200)],
+        })
+        const plan = planParallelTransfer(e, 'max')
+        expect(plan.length).toBeGreaterThan(0)
+        for (const entry of plan) {
+            expect(entry.quantity).toBeGreaterThanOrEqual(1)
+        }
+    })
+})
+
+describe('cost helpers', () => {
+    const STRATUM = 100
+    const ITEM_MASS = 1000
+    const RICHNESS = 500
+
+    test('gatherEnergyCost is 0 for non-positive quantity and positive otherwise', () => {
+        const lane = gathererLane(0, 700, 1250, 5000)
+        expect(gatherEnergyCost(lane, 0, STRATUM, ITEM_MASS, RICHNESS)).toBe(0)
+        expect(gatherEnergyCost(lane, 100, STRATUM, ITEM_MASS, RICHNESS)).toBeGreaterThan(0)
+    })
+
+    test('splitCost across two lanes is monotonic non-decreasing in quantity', () => {
+        const reaching = [gathererLane(0, 700, 1250, 5000), gathererLane(1, 700, 1250, 5000)]
+        const c100 = splitCost(reaching, 100, STRATUM, ITEM_MASS, RICHNESS)
+        const c200 = splitCost(reaching, 200, STRATUM, ITEM_MASS, RICHNESS)
+        expect(c200).toBeGreaterThanOrEqual(c100)
+    })
+
+    test('maxQtyForCharge returns hi when the whole batch fits the charge', () => {
+        const reaching = [gathererLane(0, 700, 1250, 5000)]
+        // capacity huge → the full 500 fits
+        expect(maxQtyForCharge(reaching, 500, 1_000_000, STRATUM, ITEM_MASS, RICHNESS)).toBe(500)
+    })
+
+    test('maxQtyForCharge finds the boundary: result fits, result+1 does not', () => {
+        const reaching = [gathererLane(0, 700, 1250, 5000)]
+        const capacity = 40
+        const q = maxQtyForCharge(reaching, 100_000, capacity, STRATUM, ITEM_MASS, RICHNESS)
+        expect(splitCost(reaching, q, STRATUM, ITEM_MASS, RICHNESS)).toBeLessThanOrEqual(capacity)
+        expect(splitCost(reaching, q + 1, STRATUM, ITEM_MASS, RICHNESS)).toBeGreaterThan(capacity)
+    })
+})
+
+describe('buildGatherPlan', () => {
+    const STRATUM = 100
+    const OPTS = {
+        richness: 500,
+        itemMass: 1000,
+        holdRoom: 1_000_000,
+        reserveRemaining: 1_000_000,
+        now: NOW,
+    }
+
+    test('single cycle when the target fits one charge and energy is full', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 5000)],
+            generator: energyStats(1200, 2),
+            energy: 1200,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 100}, OPTS)
+        expect(plan.cycleCount).toBe(1)
+        expect(plan.totalOre).toBe(100)
+        expect(plan.cycles[0].rechargeBefore).toBe(false)
+        expect(plan.cycles[0].limpets).toHaveLength(1)
+        expect(plan.cycles[0].limpets[0].quantity).toBe(100)
+        expect(plan.cap).toBe('requested')
+    })
+
+    test('two limpets split one charge proportional to yield, finish within 1s of each other', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 200, 500, 5000), gathererLane(1, 400, 500, 5000)],
+            generator: energyStats(60_000, 2),
+            energy: 60_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 60}, OPTS)
+        expect(plan.cycleCount).toBe(1)
+        const [a, b] = plan.cycles[0].limpets
+        expect(a.quantity + b.quantity).toBe(60)
+        expect(b.quantity).toBeGreaterThan(a.quantity) // higher yield gets more
+        expect(Math.abs(a.durationSeconds - b.durationSeconds)).toBeLessThanOrEqual(2)
+    })
+
+    test('multi-cycle: fills beyond one charge; totalOre equals fill target; each cycle fits the charge', () => {
+        const CAP = 40
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 5000)],
+            generator: energyStats(CAP, 2),
+            energy: CAP,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 500}, OPTS)
+        expect(plan.cycleCount).toBeGreaterThan(1)
+        expect(plan.totalOre).toBe(500)
+        // every cycle's summed gather cost fits one full charge
+        for (const c of plan.cycles) {
+            const cost = splitCost(
+                e.gatherer_lanes,
+                c.batchOre,
+                STRATUM,
+                OPTS.itemMass,
+                OPTS.richness
+            )
+            expect(cost).toBeLessThanOrEqual(CAP)
+        }
+        // cycles after the first recharge to full
+        expect(plan.cycles.slice(1).every((c) => c.rechargeBefore)).toBe(true)
+        // limpet quantities across all cycles sum to the target
+        const gathered = plan.cycles.flatMap((c) => c.limpets).reduce((s, l) => s + l.quantity, 0)
+        expect(gathered).toBe(500)
+    })
+
+    test('cap reasons: hold binds, reserve binds, requested binds', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 5000)],
+            generator: energyStats(60_000, 2),
+            energy: 60_000,
+        })
+        expect(
+            buildGatherPlan(e, STRATUM, 'max', {...OPTS, holdRoom: 300, reserveRemaining: 9999}).cap
+        ).toBe('hold')
+        expect(
+            buildGatherPlan(e, STRATUM, 'max', {...OPTS, holdRoom: 9999, reserveRemaining: 200}).cap
+        ).toBe('reserve')
+        expect(buildGatherPlan(e, STRATUM, {quantity: 50}, OPTS).cap).toBe('requested')
+    })
+
+    test('total ETA sums per-cycle recharge + gather seconds', () => {
+        const CAP = 40
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 5000)],
+            generator: energyStats(CAP, 2),
+            energy: CAP,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 500}, OPTS)
+        const expected = plan.cycles.reduce((s, c) => s + c.rechargeSeconds + c.gatherSeconds, 0)
+        expect(plan.totalSeconds).toBe(expected)
+    })
+
+    test('excludes limpets that cannot reach the stratum and warns', () => {
+        const e = entity({
+            gatherer_lanes: [
+                gathererLane(0, 700, 1250, 5000), // reaches 100
+                gathererLane(1, 700, 1250, 50), // does not reach 100
+            ],
+            generator: energyStats(60_000, 2),
+            energy: 60_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 100}, OPTS)
+        expect(plan.cycles[0].limpets).toHaveLength(1)
+        expect(plan.cycles[0].limpets[0].slot).toBe(0)
+        expect(plan.warnings.some((w) => w.includes("can't reach"))).toBe(true)
+    })
+
+    test('reports structured limpet reach counts (all reaching)', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 5000), gathererLane(1, 700, 1250, 5000)],
+            generator: energyStats(60_000, 2),
+            energy: 60_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 50}, OPTS)
+        expect(plan.totalLimpets).toBe(2)
+        expect(plan.reachingCount).toBe(2)
+    })
+
+    test('reachingCount excludes limpets that cannot reach the stratum', () => {
+        const e = entity({
+            gatherer_lanes: [
+                gathererLane(0, 700, 1250, 5000), // reaches 100
+                gathererLane(1, 700, 1250, 50), // does not reach 100
+            ],
+            generator: energyStats(60_000, 2),
+            energy: 60_000,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 50}, OPTS)
+        expect(plan.totalLimpets).toBe(2)
+        expect(plan.reachingCount).toBe(1)
+    })
+
+    test('single-limpet ship still fills across cycles', () => {
+        const CAP = 40
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 5000)],
+            generator: energyStats(CAP, 2),
+            energy: CAP,
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 300}, OPTS)
+        expect(plan.cycles.every((c) => c.limpets.length === 1)).toBe(true)
+        expect(plan.totalOre).toBe(300)
+    })
+
+    test('throws when no gatherer reaches the stratum', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 50)],
+            generator: energyStats(1200, 2),
+            energy: 1200,
+        })
+        expect(() => buildGatherPlan(e, STRATUM, 'max', OPTS)).toThrow('no gatherer reaches')
+    })
+
+    test('zero fill target yields an empty plan (no cycles)', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 5000)],
+            generator: energyStats(1200, 2),
+            energy: 1200,
+        })
+        const plan = buildGatherPlan(e, STRATUM, 'max', {...OPTS, holdRoom: 0})
+        expect(plan.cycleCount).toBe(0)
+        expect(plan.totalOre).toBe(0)
+        expect(plan.cap).toBe('hold')
+    })
+
+    test('first cycle skips recharge when current energy already covers the small batch', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 700, 1250, 5000)],
+            generator: energyStats(60_000, 2),
+            energy: 60_000, // full
+        })
+        const plan = buildGatherPlan(e, STRATUM, {quantity: 50}, OPTS)
+        expect(plan.cycles[0].rechargeBefore).toBe(false)
+        expect(plan.cycles[0].rechargeSeconds).toBe(0)
+    })
+})

package/src/resolution/describe-module.ts

@@ -20,6 +20,7 @@ export interface ModuleDescription {
 export interface RenderDescriptionOptions {
     translate?: (id: string, fallback: string) => string
     formatNumber?: (n: number) => string
+    formatParam?: (paramName: string, value: number, descId: string) => string | undefined
 }
 
 interface TemplateSpec {
@@ -27,6 +28,7 @@ interface TemplateSpec {
     template: string
     params: readonly [string, string][]
     highlightKeys: readonly string[]
+    derive?: Record<string, (get: (label: string) => number) => number>
 }
 
 const TEMPLATES: Record<string, TemplateSpec> = {
@@ -53,43 +55,48 @@ const TEMPLATES: Record<string, TemplateSpec> = {
     gatherer: {
         id: 'module.gatherer.description',
         template:
-            'mines resources at {yield} speed to a max depth of {depth} with {speed} gather speed while draining {drain} energy per second',
+            'mines resources at {yield} yield to a max depth of {depth} while draining {drain} energy per minute',
         params: [
             ['yield', 'Yield'],
-            ['drain', 'Drain'],
             ['depth', 'Depth'],
-            ['speed', 'Speed'],
         ],
-        highlightKeys: ['yield', 'depth', 'speed', 'drain'],
+        highlightKeys: ['yield', 'depth', 'drain'],
+        derive: {
+            drain: (get) => Math.round((get('Drain') / 10000) * 60 * 10) / 10,
+        },
     },
-    loader: {
-        id: 'module.loader.description',
-        template:
-            '{quantity} loader that generates {thrust} thrust with a weight of {mass} per unit',
+    loading: {
+        id: 'module.loading.description',
+        template: 'generates {thrust} thrust with a weight of {mass} per unit',
         params: [
-            ['quantity', 'Quantity'],
             ['thrust', 'Thrust'],
             ['mass', 'Mass'],
         ],
-        highlightKeys: ['quantity', 'thrust', 'mass'],
+        highlightKeys: ['thrust', 'mass'],
     },
-    crafter: {
-        id: 'module.crafter.description',
-        template: 'manufactures items at {speed} speed while draining {drain} energy per second',
-        params: [
-            ['speed', 'Speed'],
-            ['drain', 'Drain'],
-        ],
+    crafting: {
+        id: 'module.crafting.description',
+        template: 'manufactures items at {speed} speed while draining {drain} energy per minute',
+        params: [['speed', 'Speed']],
         highlightKeys: ['speed', 'drain'],
+        derive: {
+            drain: (get) => Math.round(((get('Drain') * get('Speed')) / 150000) * 60 * 10) / 10,
+        },
     },
     storage: {
         id: 'module.storage.description',
-        template: 'boosts cargo capacity by {bonus}%',
-        params: [['bonus', 'Capacity Bonus']],
-        highlightKeys: ['bonus'],
+        template: 'adds {capacity} cargo capacity',
+        params: [['capacity', 'Cargo Capacity']],
+        highlightKeys: ['capacity'],
+    },
+    energy: {
+        id: 'module.energy-capacity.description',
+        template: 'adds {capacity} energy capacity',
+        params: [['capacity', 'Energy Capacity']],
+        highlightKeys: ['capacity'],
     },
-    hauler: {
-        id: 'module.hauler.description',
+    hauling: {
+        id: 'module.hauling.description',
         template:
             'locks onto up to {capacity} targets at {efficiency} efficiency while draining {drain} energy per distance travelled per target',
         params: [
@@ -111,6 +118,12 @@ export function describeModule(input: CapabilityInput): ModuleDescription | null
         const attr = input.attributes.find((a) => a.label === attrLabel)
         if (attr) params[paramName] = attr.value
     }
+    if (spec.derive) {
+        const get = (label: string) => input.attributes.find((a) => a.label === label)?.value ?? 0
+        for (const [paramName, fn] of Object.entries(spec.derive)) {
+            params[paramName] = fn(get)
+        }
+    }
     return {
         id: spec.id,
         template: spec.template,
@@ -127,8 +140,10 @@ export function describeModuleForItem(resolved: ResolvedItem): ModuleDescription
 }
 
 export function describeModuleForSlot(slot: ResolvedModuleSlot): ModuleDescription | null {
-    if (!slot.installed || !slot.name || !slot.attributes) return null
-    return describeModule({capability: slot.name, attributes: slot.attributes})
+    if (!slot.installed || !slot.attributes) return null
+    const capability = slot.capability ?? slot.name
+    if (!capability) return null
+    return describeModule({capability, attributes: slot.attributes})
 }
 
 export function renderDescription(
@@ -153,7 +168,10 @@ export function renderDescription(
         if (raw === undefined) {
             spans.push({text: `{${paramName}}`})
         } else {
-            const formatted = typeof raw === 'number' ? formatNumber(raw) : raw
+            const formatted =
+                typeof raw === 'number'
+                    ? (options?.formatParam?.(paramName, raw, desc.id) ?? formatNumber(raw))
+                    : raw
             const highlight = (desc.highlightKeys as readonly string[]).includes(paramName)
             spans.push(highlight ? {text: formatted, highlight: true} : {text: formatted})
         }

package/src/resolution/display-name.ts

@@ -1,22 +1,50 @@
 import type {ResolvedItem} from './resolve-item'
 import type {ResourceCategory} from '../types'
-import {CATEGORY_LABELS, TIER_ADJECTIVES} from '../types'
+import {
+    CATEGORY_LABELS,
+    RESOURCE_TIER_ADJECTIVES,
+    COMPONENT_TIER_PREFIXES,
+    MODULE_TIER_PREFIXES,
+} from '../types'
 import {formatMass as defaultFormatMass} from '../format'
 
-export interface DisplayNameInput {
-    itemType: 'resource' | 'component' | 'module' | 'entity' | string
+interface DisplayNameInputCommon {
     tier: number
     category?: ResourceCategory
     name: string
 }
 
-export function displayName(resolved: DisplayNameInput): string {
-    if (resolved.itemType === 'resource') {
-        const adj = TIER_ADJECTIVES[resolved.tier] ?? 'Unknown'
-        const cat = resolved.category ? CATEGORY_LABELS[resolved.category] : 'Resource'
-        return `${adj} ${cat}`
-    }
-    return resolved.name
+export type DisplayNameInput =
+    | (DisplayNameInputCommon & {itemType: 'resource' | 'component' | 'module' | 'entity' | string})
+    | (DisplayNameInputCommon & {type: string})
+
+function itemTypeOf(item: DisplayNameInput): string {
+    return 'itemType' in item ? item.itemType : item.type
+}
+
+function tierPrefix(item: DisplayNameInput): string | null {
+    const t = itemTypeOf(item)
+    if (t === 'resource') return RESOURCE_TIER_ADJECTIVES[item.tier] ?? null
+    if (t === 'component') return COMPONENT_TIER_PREFIXES[item.tier] ?? null
+    if (t === 'module') return MODULE_TIER_PREFIXES[item.tier] ?? null
+    return null
+}
+
+function rootName(item: DisplayNameInput): string {
+    if (itemTypeOf(item) !== 'resource') return item.name
+    return item.category ? CATEGORY_LABELS[item.category] : 'Resource'
+}
+
+// Tier-free display name: includes the resource tier adjective / component-module
+// prefix, but no "(T#)" suffix. Use this when the tier is shown separately.
+export function baseName(item: DisplayNameInput): string {
+    const prefix = tierPrefix(item)
+    const root = rootName(item)
+    return prefix ? `${prefix} ${root}` : root
+}
+
+export function displayName(item: DisplayNameInput): string {
+    return `${baseName(item)} (T${item.tier})`
 }
 
 export interface DescribeOptions {

package/src/resolution/resolve-item.test.ts

@@ -0,0 +1,48 @@
+import {expect, test} from 'bun:test'
+import {UInt16, UInt64} from '@wharfkit/antelope'
+import {resolveItem} from './resolve-item'
+import {encodeStats} from '../derivation/crafting'
+import {computeBaseHullmass, computeContainerCapabilities} from '../derivation/capabilities'
+import {
+    ITEM_EXTRACTOR_T1_PACKED,
+    ITEM_FACTORY_T1_PACKED,
+    ITEM_HUB_T1_PACKED,
+    ITEM_MASS_DRIVER_T1_PACKED,
+    ITEM_MASS_CATCHER_T1_PACKED,
+} from '../data/item-ids'
+
+function hullStats(strength: number, density: number, hardness: number): UInt64 {
+    return UInt64.from(encodeStats([strength, density, hardness]).toString())
+}
+
+const CONTAINER_ENTITIES = [
+    ['factory', ITEM_FACTORY_T1_PACKED],
+    ['extractor', ITEM_EXTRACTOR_T1_PACKED],
+    ['mass driver', ITEM_MASS_DRIVER_T1_PACKED],
+    ['mass catcher', ITEM_MASS_CATCHER_T1_PACKED],
+] as const
+
+for (const [label, itemId] of CONTAINER_ENTITIES) {
+    test(`resolveItem resolves ${label} hull capacity via container formula`, () => {
+        const stats = hullStats(300, 100, 400)
+        const resolved = resolveItem(UInt16.from(itemId), stats)
+        const hull = resolved.attributes?.find((g) => g.capability === 'Hull')
+        const capacity = hull?.attributes.find((a) => a.label === 'Capacity')?.value
+        const expected = computeContainerCapabilities({
+            strength: 300,
+            hardness: 400,
+            density: 100,
+        }).capacity
+        expect(capacity).toBe(expected)
+    })
+}
+
+test('resolveItem resolves the station hub with hullmass and zero cargo capacity', () => {
+    const stats = hullStats(300, 100, 400)
+    const resolved = resolveItem(UInt16.from(ITEM_HUB_T1_PACKED), stats)
+    const hull = resolved.attributes?.find((g) => g.capability === 'Hull')
+    expect(hull?.attributes.find((a) => a.label === 'Mass')?.value).toBe(
+        computeBaseHullmass({density: 100})
+    )
+    expect(hull?.attributes.find((a) => a.label === 'Capacity')?.value).toBe(0)
+})