@shipload/sdk 1.0.0-next.73 → 1.0.0-next.75

package/src/data/component-process.test.ts

@@ -0,0 +1,119 @@
+import {describe, expect, test} from 'bun:test'
+import {
+    ITEM_BEAM,
+    ITEM_ENGINE_T1,
+    ITEM_ORE_T1,
+    ITEM_PLATE,
+    ITEM_PLATE_T2,
+    ITEM_PROSPECTOR_T1A_PACKED,
+    ITEM_PROSPECTOR_T2A_PACKED,
+    ITEM_PROSPECTOR_T2B_PACKED,
+    ITEM_ROUSTABOUT_T1A_PACKED,
+    ITEM_STORAGE_T1,
+} from './item-ids'
+import {getComponents} from './catalog'
+import {getRecipe} from './recipes-runtime'
+import {completeComponentSet, getComponentProcess} from './component-process'
+import {resolveItem} from '../resolution/resolve-item'
+
+function inputsOf(itemId: number) {
+    const recipe = getRecipe(itemId)
+    if (!recipe) throw new Error(`no recipe for ${itemId}`)
+    return recipe.inputs
+}
+
+describe('component process', () => {
+    test('every component at every tier is refined or machined, five of each per tier', () => {
+        const tiers = new Set(getComponents().map((item) => item.tier))
+        for (const tier of tiers) {
+            const kinds = getComponents({tier}).map((item) => getComponentProcess(item.id))
+            expect(kinds.filter((k) => k === 'refined').length).toBe(5)
+            expect(kinds.filter((k) => k === 'machined').length).toBe(5)
+        }
+    })
+
+    test('the refined five are the single-resource components', () => {
+        const refined = getComponents({tier: 1})
+            .filter((item) => getComponentProcess(item.id) === 'refined')
+            .map((item) => item.name)
+            .sort()
+        expect(refined).toEqual(['Ceramic', 'Plasma Cell', 'Plate', 'Polymer', 'Sensor'])
+    })
+
+    test('the kind holds across tiers', () => {
+        expect(getComponentProcess(ITEM_PLATE)).toBe('refined')
+        expect(getComponentProcess(ITEM_PLATE_T2)).toBe('refined')
+        expect(getComponentProcess(ITEM_BEAM)).toBe('machined')
+    })
+
+    test('non-components and unknown ids have no kind', () => {
+        expect(getComponentProcess(ITEM_ORE_T1)).toBeUndefined()
+        expect(getComponentProcess(ITEM_ENGINE_T1)).toBeUndefined()
+        expect(getComponentProcess(ITEM_ROUSTABOUT_T1A_PACKED)).toBeUndefined()
+        expect(getComponentProcess(65535)).toBeUndefined()
+    })
+
+    test('resolveItem carries the kind for components only', () => {
+        expect(resolveItem(ITEM_BEAM).process).toBe('machined')
+        expect(resolveItem(ITEM_PLATE_T2).process).toBe('refined')
+        expect(resolveItem(ITEM_ORE_T1).process).toBeUndefined()
+    })
+})
+
+describe('completeComponentSet', () => {
+    test('recognises the hull First and Second step recipes', () => {
+        expect(completeComponentSet(inputsOf(ITEM_ROUSTABOUT_T1A_PACKED))).toEqual({
+            process: 'refined',
+            tier: 1,
+            quantity: 200,
+        })
+        expect(completeComponentSet(inputsOf(ITEM_PROSPECTOR_T1A_PACKED))).toEqual({
+            process: 'machined',
+            tier: 1,
+            quantity: 100,
+        })
+        expect(completeComponentSet(inputsOf(ITEM_PROSPECTOR_T2A_PACKED))).toEqual({
+            process: 'refined',
+            tier: 2,
+            quantity: 200,
+        })
+        expect(completeComponentSet(inputsOf(ITEM_PROSPECTOR_T2B_PACKED))).toEqual({
+            process: 'machined',
+            tier: 2,
+            quantity: 150,
+        })
+    })
+
+    test('a mixed module recipe is not a complete set', () => {
+        expect(completeComponentSet(inputsOf(ITEM_STORAGE_T1))).toBeNull()
+    })
+
+    test('unequal quantities keep the set but drop the shared quantity', () => {
+        const inputs = inputsOf(ITEM_ROUSTABOUT_T1A_PACKED).map((input, index) =>
+            index === 0 ? {...input, quantity: 50} : input
+        )
+        expect(completeComponentSet(inputs)).toEqual({process: 'refined', tier: 1, quantity: null})
+    })
+
+    test('one machined part among four refined is not a set', () => {
+        const inputs = inputsOf(ITEM_ROUSTABOUT_T1A_PACKED).map((input, index) =>
+            index === 0 ? {...input, itemId: ITEM_BEAM} : input
+        )
+        expect(completeComponentSet(inputs)).toBeNull()
+    })
+
+    test('a repeated family is not a set', () => {
+        const inputs = inputsOf(ITEM_ROUSTABOUT_T1A_PACKED).map((input) => ({
+            ...input,
+            itemId: ITEM_PLATE,
+        }))
+        expect(completeComponentSet(inputs)).toBeNull()
+    })
+
+    test('mixed tiers are not a set', () => {
+        const inputs = inputsOf(ITEM_ROUSTABOUT_T1A_PACKED).map((input, index) =>
+            index === 0 ? {...input, itemId: ITEM_PLATE_T2} : input
+        )
+        expect(completeComponentSet(inputs)).toBeNull()
+    })
+})

package/src/data/component-process.ts

@@ -0,0 +1,33 @@
+import {getItem} from './catalog'
+import {getItemFamily, type ComponentProcess} from './metadata'
+import type {RecipeInput} from './recipes-runtime'
+
+export const COMPONENT_PROCESS_ORDER: readonly ComponentProcess[] = ['refined', 'machined']
+
+export function getComponentProcess(itemId: number): ComponentProcess | undefined {
+    return getItemFamily(itemId)?.process
+}
+
+export interface CompleteComponentSet {
+    process: ComponentProcess
+    tier: number
+    quantity: number | null
+}
+
+export function completeComponentSet(inputs: readonly RecipeInput[]): CompleteComponentSet | null {
+    const parts = inputs.filter((input) => getComponentProcess(input.itemId) !== undefined)
+    if (parts.length !== 5) return null
+    const process = getComponentProcess(parts[0].itemId)
+    const tier = getItem(parts[0].itemId).tier
+    const families = new Set<string>()
+    for (const part of parts) {
+        const item = getItem(part.itemId)
+        if (getComponentProcess(part.itemId) !== process || item.tier !== tier) return null
+        families.add(item.family)
+    }
+    if (!process || families.size !== 5) return null
+    const quantity = parts.every((part) => part.quantity === parts[0].quantity)
+        ? parts[0].quantity
+        : null
+    return {process, tier, quantity}
+}

package/src/data/entities.json

@@ -108,12 +108,12 @@
     "slots": [
       {
         "type": "builder",
-        "outputPct": 200,
+        "outputPct": 75,
         "maxTier": 1
       },
       {
         "type": "builder",
-        "outputPct": 200,
+        "outputPct": 75,
         "maxTier": 1
       }
     ],

package/src/data/metadata.ts

@@ -1,9 +1,12 @@
 import items from './items.json'
 
+export type ComponentProcess = 'refined' | 'machined'
+
 export interface ItemFamily {
     name: string
     description: string
     color: string
+    process?: ComponentProcess
 }
 
 export interface EntityMetadata {
@@ -14,27 +17,27 @@ export const itemFamilies: Record<string, ItemFamily> = {
     // === Resources ===
     ore: {
         name: 'Ore',
-        description: 'Refines into Plate and Beam.',
+        description: 'Goes into Plate and Beam.',
         color: '#C26D3F',
     },
     crystal: {
         name: 'Crystal',
-        description: 'Refines into Sensors and Resonators.',
+        description: 'Goes into Sensors and Resonators.',
         color: '#4ADBFF',
     },
     gas: {
         name: 'Gas',
-        description: 'Refines into Plasma Cells and Reactors.',
+        description: 'Goes into Plasma Cells and Reactors.',
         color: '#B877FF',
     },
     regolith: {
         name: 'Regolith',
-        description: 'Refines into Ceramic and Frame.',
+        description: 'Goes into Ceramic and Frame.',
         color: '#C4A57B',
     },
     biomass: {
         name: 'Biomass',
-        description: 'Refines into Polymer and Resin.',
+        description: 'Goes into Polymer and Resin.',
         color: '#5A8B3E',
     },
 
@@ -43,51 +46,61 @@ export const itemFamilies: Record<string, ItemFamily> = {
         name: 'Plate',
         description: 'Goes into Cargo Holds, Containers, and hulls.',
         color: '#7B8D9E',
+        process: 'refined',
     },
     frame: {
         name: 'Frame',
         description: 'Goes into Limpet Bays, Cargo Holds, and hulls.',
         color: '#C4A57B',
+        process: 'machined',
     },
     'plasma-cell': {
         name: 'Plasma Cell',
         description: 'Goes into Engines, Battery Banks, and hulls.',
         color: '#E86344',
+        process: 'refined',
     },
     resonator: {
         name: 'Resonator',
         description: 'Goes into Power Cores, Tractor Beams, Warp Drives, and hulls.',
         color: '#4ADBFF',
+        process: 'machined',
     },
     beam: {
         name: 'Beam',
         description: 'Goes into Limpet Bays and hulls.',
         color: '#7B8D9E',
+        process: 'machined',
     },
     sensor: {
         name: 'Sensor',
         description: 'Goes into Fabricators, Assembly Arms, and hulls.',
         color: '#4ADBFF',
+        process: 'refined',
     },
     polymer: {
         name: 'Polymer',
         description: 'Goes into Shuttle Bays, Battery Banks, and hulls.',
         color: '#5A8B3E',
+        process: 'refined',
     },
     ceramic: {
         name: 'Ceramic',
         description: 'Goes into Assembly Arms, Containers, and hulls.',
         color: '#C4A57B',
+        process: 'refined',
     },
     reactor: {
         name: 'Reactor',
         description: 'Goes into Fabricators, Warp Drives, and hulls.',
         color: '#B877FF',
+        process: 'machined',
     },
     resin: {
         name: 'Resin',
         description: 'Goes into Tractor Beams and hulls.',
         color: '#5A8B3E',
+        process: 'machined',
     },
 
     // === Modules ===

package/src/index-module.ts

@@ -62,6 +62,22 @@ export {
     JobsManager,
     InfluenceManager,
 } from './managers'
+export {
+    ShuttleManager,
+    rankShuttleOptions,
+    shuttleReasonCode,
+    shuttleCandidates,
+    BOOKING_LEVEL_CODES,
+    OMITTED_REASONS,
+} from './managers/shuttle'
+export type {
+    ShuttleMode,
+    ShuttleOption,
+    ShuttleOptions,
+    ShuttleReason,
+    ShuttleReasonCode,
+    CandidateEntity,
+} from './managers/shuttle'
 export type {GridCell, ClusterCell, Cluster} from './managers'
 export type {
     CharterProgress,
@@ -125,7 +141,13 @@ export {
     categoryLabelFromIndex,
 } from './data/catalog'
 export {getItemFamily, itemFamilies, itemFamilyKey} from './data/metadata'
-export type {ItemFamily} from './data/metadata'
+export type {ComponentProcess, ItemFamily} from './data/metadata'
+export {
+    COMPONENT_PROCESS_ORDER,
+    completeComponentSet,
+    getComponentProcess,
+} from './data/component-process'
+export type {CompleteComponentSet} from './data/component-process'
 export {getCurrentEpoch, getEpochInfo} from './scheduling/epoch'
 export type {EpochInfo} from './scheduling/epoch'
 export {
@@ -341,6 +363,7 @@ export {
     jobDropoffTask,
     jobCancelRoute,
     buildJobCancelRoute,
+    hostedDropoff,
     jobCancellable,
     jobCancellationBlockReason,
     jobDeposited,
@@ -356,7 +379,10 @@ export type {
     JobStatusInput,
     JobCancelRoute,
     JobCancellationBlockReason,
+    JobRouteOptions,
+    HostedLeg,
     OwnedJob,
+    BuildJob,
     PickupInFlight,
 } from './scheduling/jobs'
 
@@ -400,6 +426,7 @@ export {
     cargoInputKey,
     hasSourceCoupling,
     hasIncomingCoupling,
+    isHostedCivicLeg,
 } from './scheduling/availability'
 export type {CargoInput, IncomingHoldEntity, IncomingSource} from './scheduling/availability'
 
@@ -409,7 +436,7 @@ export {calcClusterIntake, calcClustercraftDuration, INTAKE_RATE} from './capabi
 
 export {maxCraftable} from './capabilities/craftable'
 
-export {energyAtTime} from './scheduling/energy'
+export {energyAtTime, energyDrawsFunded} from './scheduling/energy'
 
 export * from './types/capabilities'
 export * from './types/entity'

package/src/influence/civic-shuttle.test.ts

@@ -12,6 +12,7 @@ import {
     pendingCivicTransfers,
     selectCivicShuttleBay,
     CIVIC_TRANSFER_PER_PLAYER_CAP,
+    type CivicShuttleBay,
 } from './civic-shuttle'
 
 type Lane = ServerContract.Types.lane
@@ -63,6 +64,32 @@ function shuttleTask(senderId: number, receiverId: number, group?: number): Task
     } as unknown as Task
 }
 
+function civicTask(type: number, couplings: unknown[]): Task {
+    return {
+        type: UInt8.from(type),
+        duration: UInt32.from(60),
+        cancelable: UInt8.from(2),
+        cargo: [],
+        couplings,
+    } as unknown as Task
+}
+
+function pullCoupling(id: number) {
+    return {
+        counterpart: {entity_id: UInt64.from(id), entity_type: UInt8.from(1)},
+        hold: UInt64.from(1),
+        kind: UInt8.from(HoldKind.PULL),
+    }
+}
+
+function pushCoupling(id: number) {
+    return {
+        counterpart: {entity_id: UInt64.from(id), entity_type: UInt8.from(1)},
+        hold: UInt64.from(1),
+        kind: UInt8.from(HoldKind.PUSH),
+    }
+}
+
 function makeLane(laneKey: number, tasks: Task[]): Lane {
     return {
         lane_key: UInt8.from(laneKey),
@@ -142,6 +169,13 @@ test('selectCivicShuttleBay takes the first free bay, then the lowest occupied o
     expect(selectCivicShuttleBay(modules, ITEM_DEPOT_T1_PACKED, bothBusy, T0)?.laneKey).toBe(1)
 })
 
+test('selectCivicShuttleBay picks the earliest finish, not the first free bay', () => {
+    const modules = depotModules()
+    const lanes = [makeLane(1, [shuttleTask(20, 21)])]
+    const fast = (bay: CivicShuttleBay) => (bay.slotIndex === 0 ? 10 : 500)
+    expect(selectCivicShuttleBay(modules, ITEM_DEPOT_T1_PACKED, lanes, T0, fast)?.slotIndex).toBe(0)
+})
+
 test('selectCivicShuttleBay returns nothing when the building has no loaders', () => {
     const modules = [makeModuleEntry(ITEM_STORAGE_T1, storageStats)]
     expect(selectCivicShuttleBay(modules, ITEM_DEPOT_T1_PACKED, [], T0)).toBeUndefined()
@@ -190,6 +224,30 @@ test('civicTransfersFrom counts only the ships a player sends from', () => {
     expect(civicTransfersFrom(entity, [99], T0).length).toBe(0)
 })
 
+test('civic legs on bays count toward the player cap', () => {
+    const depot = {
+        lanes: [makeLane(1, [civicTask(TaskType.CIVIC_WITHDRAW, [pushCoupling(7)])])],
+    } as never
+    expect(civicTransfersFrom(depot, [7]).length).toBe(1)
+})
+
+test('a civic deposit leg reports the same player id as sender and receiver', () => {
+    const depot = {
+        lanes: [makeLane(1, [civicTask(TaskType.CIVIC_DEPOSIT, [pullCoupling(7)])])],
+    } as never
+    const [transfer] = pendingCivicTransfers(depot, T0)
+    expect(String(transfer.senderId)).toBe('7')
+    expect(String(transfer.receiverId)).toBe('7')
+})
+
+test('a civic pickup leg is not callable while CANCEL_NEVER', () => {
+    const task = civicTask(TaskType.CIVIC_WITHDRAW, [pushCoupling(7)])
+    ;(task as unknown as {cancelable: unknown}).cancelable = UInt8.from(0)
+    const depot = {lanes: [makeLane(1, [task])]} as never
+    const [transfer] = pendingCivicTransfers(depot, T0)
+    expect(transfer.callable).toBe(false)
+})
+
 test('civicTransfersAtCap trips at the per-player cap', () => {
     const mine = Array.from({length: CIVIC_TRANSFER_PER_PLAYER_CAP}, (_, i) =>
         shuttleTask(20 + i, 50)

package/src/influence/civic-shuttle.ts

@@ -4,7 +4,7 @@ import {getItem} from '../data/catalog'
 import {JOB_QUEUE_CAP} from '../scheduling/jobs'
 import {laneKeyForModule, resolveLaneLoader} from '../scheduling/lanes'
 import {orderedTasks, type ScheduleData} from '../scheduling/schedule'
-import {HoldKind, TaskType} from '../types'
+import {HoldKind, TaskCancelable, TaskType} from '../types'
 
 type CargoItem = ServerContract.Types.cargo_item
 type Lane = ServerContract.Types.lane
@@ -22,7 +22,6 @@ export interface CivicShuttleBay {
     full: boolean
 }
 
-// a landed booking clears during the next civicshuttle, so only unfinished tasks occupy a bay
 function unfinishedTasks(lane: Lane | undefined, now: Date): number {
     if (!lane) return 0
     const startedMs = lane.schedule.started.toDate().getTime()
@@ -64,15 +63,38 @@ export function civicShuttleBays(
     return bays
 }
 
-// Mirrors worker_lane_key_or_mobility for loaders: first free bay, else the lowest bay.
+function laneEndMs(lane: Lane | undefined, nowMs: number): number {
+    if (!lane) return nowMs
+    let endSec = 0
+    for (const task of lane.schedule.tasks) endSec += task.duration.toNumber()
+    return Math.max(nowMs, lane.schedule.started.toDate().getTime() + endSec * 1000)
+}
+
+// Mirrors cargo.cpp pick_civic_bay: earliest finish among bays below the queue cap.
 export function selectCivicShuttleBay(
     modules: ModuleEntry[],
     entityItemId: number,
     lanes: Lane[],
-    now: Date = new Date()
+    now: Date = new Date(),
+    durationFor: (bay: CivicShuttleBay) => number = () => 0,
+    minStart?: Date
 ): CivicShuttleBay | undefined {
     const bays = civicShuttleBays(modules, entityItemId, lanes, now)
-    return bays.find((bay) => bay.queued === 0) ?? bays[0]
+    const nowMs = now.getTime()
+    const floorMs = Math.max(nowMs, minStart?.getTime() ?? nowMs)
+    let best: CivicShuttleBay | undefined
+    let bestEnd = Infinity
+    for (const bay of bays) {
+        if (bay.full) continue
+        const lane = lanes.find((l) => l.lane_key.toNumber() === bay.laneKey)
+        const start = Math.max(laneEndMs(lane, nowMs), floorMs)
+        const end = start + durationFor(bay) * 1000
+        if (end < bestEnd) {
+            best = bay
+            bestEnd = end
+        }
+    }
+    return best ?? bays[0]
 }
 
 export interface PendingCivicTransfer {
@@ -98,7 +120,31 @@ export function pendingCivicTransfers(
     }
     const out: PendingCivicTransfer[] = []
     for (const entry of orderedTasks(entity)) {
-        if (entry.task.type.toNumber() !== TaskType.SHUTTLE) continue
+        const type = entry.task.type.toNumber()
+        if (type === TaskType.CIVIC_DEPOSIT || type === TaskType.CIVIC_WITHDRAW) {
+            const side = entry.task.couplings[0]
+            if (!side) continue
+            const isTail = tailIndex.get(entry.laneKey) === entry.taskIndex
+            const complete = entry.completesAt.getTime() <= now.getTime()
+            out.push({
+                laneKey: entry.laneKey,
+                taskIndex: entry.taskIndex,
+                senderId: side.counterpart.entity_id,
+                receiverId: side.counterpart.entity_id,
+                cargo: entry.task.cargo,
+                startsAt: entry.startsAt,
+                completesAt: entry.completesAt,
+                isTail,
+                complete,
+                callable:
+                    isTail &&
+                    !complete &&
+                    !entry.task.entitygroup &&
+                    entry.task.cancelable.toNumber() !== TaskCancelable.NEVER,
+            })
+            continue
+        }
+        if (type !== TaskType.SHUTTLE) continue
         const pull = entry.task.couplings.find((c) => c.kind.toNumber() === HoldKind.PULL)
         const push = entry.task.couplings.find((c) => c.kind.toNumber() === HoldKind.PUSH)
         if (!pull || !push) continue

package/src/influence/duration.ts

@@ -1,9 +1,4 @@
-import type {NameType} from '@wharfkit/antelope'
-import type {ServerContract} from '../contracts'
-import {getEntityClass} from '../data/kind-registry'
 import {computeLoaderMass, computeLoaderThrust} from '../nft/description'
-import {laneKeyForModule, resolveLaneLoader} from '../scheduling/lanes'
-import {calc_onesided_duration} from '../travel/travel'
 import {MASS_STAT_SCALE, MASS_UNITS_PER_TONNE, PRECISION} from '../types'
 import {CIVIC_LOADER_STAT, CIVIC_LOADER_TIER, DEFAULT_ORBITAL_Z} from './constants'
 
@@ -39,63 +34,3 @@ export function contributeDuration(totalMass: number, altitudeZ = 0): number {
 export function contributeDurationForTonnes(tonnes: number, altitudeZ = 0): number {
     return contributeDuration(Math.floor(tonnes * MASS_UNITS_PER_TONNE), altitudeZ)
 }
-
-export const DEPOT_LOADER_SLOT = 0
-
-export interface DepotTransferParams {
-    depotModules: ServerContract.Types.module_entry[]
-    depotItemId: number
-    depotKind: NameType
-    depotZ: number
-    shipKind: NameType
-    shipZ: number
-    cargoMass: number
-}
-
-// Mirrors depot.cpp: the depot's slot-0 loader drives the transfer; 0 when no loader is installed.
-export function depotTransferDuration(params: DepotTransferParams): number {
-    const loader = resolveLaneLoader(
-        params.depotModules,
-        params.depotItemId,
-        laneKeyForModule(DEPOT_LOADER_SLOT)
-    )
-    if (!loader.valid) return 0
-    return calc_onesided_duration(
-        loader.thrust,
-        loader.mass,
-        params.shipZ,
-        params.depotZ,
-        getEntityClass(params.shipKind),
-        getEntityClass(params.depotKind),
-        params.cargoMass
-    )
-}
-
-export interface CivicDropoffParams {
-    buildingModules: ServerContract.Types.module_entry[]
-    buildingItemId: number
-    buildingKind: NameType
-    buildingZ: number
-    shipKind: NameType
-    shipZ: number
-    cargoMass: number
-}
-
-// Mirrors jobs.cpp craftjob: the building's slot-0 loader when one is installed, the civic loader when none is.
-export function civicDropoffDuration(params: CivicDropoffParams): number {
-    const loader = resolveLaneLoader(
-        params.buildingModules,
-        params.buildingItemId,
-        laneKeyForModule(DEPOT_LOADER_SLOT)
-    )
-    if (!loader.valid) return contributeDuration(params.cargoMass, params.shipZ)
-    return calc_onesided_duration(
-        loader.thrust,
-        loader.mass,
-        params.shipZ,
-        params.buildingZ,
-        getEntityClass(params.shipKind),
-        getEntityClass(params.buildingKind),
-        params.cargoMass
-    )
-}

package/src/influence/index.ts

@@ -26,24 +26,23 @@ export {
 export {
     componentBaseAtomic,
     componentEffortAtomic,
+    explainCargoItem,
     pricingFromWeights,
     resourceValueAtomic,
     valueCargoItem,
     valueContribution,
     weightedQualityAtomic,
+    type CargoValuation,
+    type ComponentValuation,
     type InfluencePricing,
+    type ResourceValuation,
     type ValuedItem,
 } from './valuation'
 export {
-    civicDropoffDuration,
     civicLoader,
     contributeDuration,
     contributeDurationForTonnes,
-    depotTransferDuration,
-    DEPOT_LOADER_SLOT,
-    type CivicDropoffParams,
     type CivicLoaderStats,
-    type DepotTransferParams,
 } from './duration'
 export {
     civicShuttleBays,