@shipload/sdk 1.0.0-next.72 → 1.0.0-next.74

package/src/managers/shuttle.ts

@@ -0,0 +1,397 @@
+import {
+    Name,
+    UInt16,
+    UInt32,
+    UInt64,
+    type NameType,
+    type UInt16Type,
+    type UInt32Type,
+    type UInt64Type,
+} from '@wharfkit/antelope'
+import {BaseManager} from './base'
+import {ServerContract} from '../contracts'
+import {getItem} from '../data/catalog'
+import {ENTITY_DEPOT} from '../data/kind-registry'
+import {isCivicEntity} from '../influence/civic'
+import {projectEntity} from '../scheduling/projection'
+
+export type ShuttleMode = 'internal' | 'own' | 'ship' | 'bays'
+
+export type ShuttleReasonCode =
+    | 'workshop-capped'
+    | 'no-generator'
+    | 'not-equipped'
+    | 'job-cap'
+    | 'target-busy'
+    | 'cargo-wont-fit'
+    | 'depot-full'
+    | 'not-stored'
+    | 'no-storage'
+    | 'bays-booked'
+    | 'player-cap'
+    | 'queue-full'
+    | 'inputs-unavailable'
+    | 'ship-energy'
+    | 'dropoff-collision'
+    | 'ship-capped'
+    | 'departs'
+    | 'cargo-not-aboard'
+    | 'no-capacity'
+    | 'schedule-full'
+    | 'plot-recipe'
+    | 'not-ready'
+    | 'unknown'
+
+export interface ShuttleReason {
+    code: ShuttleReasonCode
+    reason: string
+    at?: Date
+    until?: Date
+    have?: number
+    need?: number
+    cap?: number
+    taskType?: number
+}
+
+export interface ShuttleOption {
+    shuttledBy?: string
+    mode: ShuttleMode
+    hostId: string
+    laneKey: number
+    duration: number
+    resolved: boolean
+    start?: Date
+    finish?: Date
+    bays: number
+    window?: {startsAt: Date; completesAt: Date}
+    energyCost?: number
+    blocked?: ShuttleReason
+}
+
+export interface ShuttleOptions {
+    blocked?: ShuttleReason
+    options: ShuttleOption[]
+    auto?: ShuttleOption
+}
+
+// contract strings verbatim from errors.hpp and placement.hpp
+const REASON_CODES: Record<string, ShuttleReasonCode> = {
+    'workshop has a pending plan-capper; cannot accept new jobs': 'workshop-capped',
+    'ship needs an energy source to book a craft job': 'no-generator',
+    'entity cannot recharge': 'no-generator',
+    'workshop has no fabricator installed': 'not-equipped',
+    'dock has no assembly arm installed': 'not-equipped',
+    'too many bookings waiting on materials at this building': 'job-cap',
+    'upgrade target is busy': 'target-busy',
+    'Entity must be idle to modify modules.': 'target-busy',
+    'target cargo would not fit the upgraded capacity': 'cargo-wont-fit',
+    'player storage allowance at this depot is exceeded': 'depot-full',
+    'player has no such item stored at this depot': 'not-stored',
+    'player has fewer of that item stored at this depot': 'not-stored',
+    'entity has no storage': 'no-storage',
+    'target entity has no storage': 'no-storage',
+    "the building's shuttle bays are fully booked": 'bays-booked',
+    'player already has the most transfers this building takes': 'player-cap',
+    'fabricator queue is full': 'queue-full',
+    'Cannot unload cargo that is not loaded.': 'inputs-unavailable',
+    'Insufficient inputs for recipe.': 'inputs-unavailable',
+    'Cargo debit exceeds available quantity.': 'inputs-unavailable',
+    'Craft requires more energy than entity has.': 'ship-energy',
+    'identical Workshop delivery already scheduled at this time; finish that delivery or change the shipment':
+        'dropoff-collision',
+    'cannot append: schedule is capped by a pending plan-capper': 'ship-capped',
+    'ship departs before the shuttle completes': 'departs',
+    'giver has insufficient giveable cargo': 'cargo-not-aboard',
+    'Entity cargo capacity would be exceeded.': 'no-capacity',
+    'lane queue is full': 'schedule-full',
+    'No recipe found for plot target.': 'plot-recipe',
+    'Item is not part of the plot target recipe.': 'plot-recipe',
+    'Deposit would exceed plot recipe requirement.': 'plot-recipe',
+    'craft job is not finished yet': 'not-ready',
+}
+
+export const BOOKING_LEVEL_CODES: ReadonlySet<ShuttleReasonCode> = new Set([
+    'workshop-capped',
+    'no-generator',
+    'not-equipped',
+    'job-cap',
+    'target-busy',
+    'cargo-wont-fit',
+    'depot-full',
+    'not-stored',
+    'no-storage',
+    'not-ready',
+])
+
+// never-shuttle rejections from resolve_civic_carrier; the query never omits, so the wrapper drops them here
+export const OMITTED_REASONS: ReadonlySet<string> = new Set([
+    'that ship has no shuttle bay',
+    'that ship belongs to another player',
+    'that ship is not here',
+    "only a Depot's public shuttle bays can take this",
+    "choose the building's own shuttle instead",
+    'counterpart has a pending plan-capper; cannot place a hold on it',
+    'entity not found',
+])
+
+export function shuttleReasonCode(reason: string): ShuttleReasonCode {
+    return REASON_CODES[reason] ?? 'unknown'
+}
+
+const MODES: ShuttleMode[] = ['internal', 'own', 'ship', 'bays']
+
+const modeRank = (o: ShuttleOption) => (o.mode === 'internal' || o.mode === 'own' ? 0 : 1)
+
+const finishRank = (o: ShuttleOption) => o.finish?.getTime() ?? Number.POSITIVE_INFINITY
+
+export function rankShuttleOptions(a: ShuttleOption, b: ShuttleOption): number {
+    const blocked = (o: ShuttleOption) => (o.blocked ? 1 : 0)
+    if (blocked(a) !== blocked(b)) return blocked(a) - blocked(b)
+    if (finishRank(a) !== finishRank(b)) return finishRank(a) < finishRank(b) ? -1 : 1
+    if (modeRank(a) !== modeRank(b)) return modeRank(a) - modeRank(b)
+    return Number(BigInt(a.hostId) - BigInt(b.hostId))
+}
+
+type RawOptions = ServerContract.Types.shuttle_options
+
+function toDate(tp: {toDate(): Date} | undefined): Date | undefined {
+    return tp ? tp.toDate() : undefined
+}
+
+function wireTime(tp: {toMilliseconds(): number; toDate(): Date}): Date | undefined {
+    return tp.toMilliseconds() === 0 ? undefined : tp.toDate()
+}
+
+function toNum(v: {toNumber(): number} | undefined): number | undefined {
+    return v === undefined ? undefined : v.toNumber()
+}
+
+function mapReason(r: ServerContract.Types.shuttle_rejection): ShuttleReason {
+    return {
+        code: shuttleReasonCode(r.reason),
+        reason: r.reason,
+        at: toDate(r.at),
+        until: toDate(r.until),
+        have: toNum(r.have),
+        need: toNum(r.need),
+        cap: toNum(r.cap),
+        taskType: toNum(r.task_type),
+    }
+}
+
+function mapOptions(raw: RawOptions): ShuttleOptions {
+    const options: ShuttleOption[] = []
+    for (const o of raw.options) {
+        const rejection = o.rejection ? mapReason(o.rejection) : undefined
+        if (rejection && OMITTED_REASONS.has(rejection.reason)) continue
+        const window =
+            o.window_starts_at && o.window_completes_at
+                ? {
+                      startsAt: toDate(o.window_starts_at)!,
+                      completesAt: toDate(o.window_completes_at)!,
+                  }
+                : undefined
+        const start = wireTime(o.start)
+        const finish = wireTime(o.finish)
+        options.push({
+            shuttledBy: o.shuttled_by ? o.shuttled_by.toString() : undefined,
+            mode: MODES[o.mode.toNumber()] ?? 'internal',
+            hostId: o.host_id.toString(),
+            laneKey: o.lane_key.toNumber(),
+            duration: o.duration.toNumber(),
+            resolved: o.resolved,
+            start,
+            finish,
+            bays: o.bays.toNumber(),
+            window,
+            energyCost: toNum(o.energy_cost),
+            blocked: rejection,
+        })
+    }
+    options.sort(rankShuttleOptions)
+    const first = options[0]?.blocked
+    const blocked =
+        first &&
+        BOOKING_LEVEL_CODES.has(first.code) &&
+        options.every((o) => o.blocked?.code === first.code)
+            ? first
+            : undefined
+    const auto = blocked ? undefined : options.find((o) => !o.blocked)
+    return {blocked, options, auto}
+}
+
+export type CandidateEntity = Pick<
+    ServerContract.Types.entity_row,
+    'id' | 'owner' | 'kind' | 'coordinates' | 'modules' | 'item_id' | 'lanes'
+>
+
+const SHUTTLE_CANDIDATE_CAP = 8
+
+function siteOf(entity: CandidateEntity) {
+    return projectEntity({...entity, cargo: [], cargomass: UInt32.from(0)}).location
+}
+
+function hasLoaderModule(entity: CandidateEntity): boolean {
+    return entity.modules.some(
+        (m) => m.installed && getItem(m.installed.item_id).moduleType === 'loader'
+    )
+}
+
+export function shuttleCandidates(
+    req: {building: CandidateEntity; shipId: UInt64Type; player: NameType},
+    entities: readonly CandidateEntity[],
+    civicOwner: NameType
+): string[] {
+    const {building, shipId, player} = req
+    const buildingId = UInt64.from(building.id)
+    const bookingShipId = UInt64.from(shipId)
+    const playerName = Name.from(player)
+    const site = siteOf(building)
+
+    const depots: UInt64[] = []
+    const ships: UInt64[] = []
+    const seen = new Set<string>()
+
+    for (const entity of entities) {
+        const id = UInt64.from(entity.id)
+        if (id.equals(buildingId) || id.equals(bookingShipId)) continue
+        if (seen.has(id.toString())) continue
+        if (!siteOf(entity).equals(site)) continue
+
+        if (isCivicEntity(entity, civicOwner)) {
+            if (Name.from(entity.kind).equals(ENTITY_DEPOT)) {
+                depots.push(id)
+                seen.add(id.toString())
+            }
+            continue
+        }
+
+        if (!Name.from(entity.owner).equals(playerName)) continue
+        if (!hasLoaderModule(entity)) continue
+        ships.push(id)
+        seen.add(id.toString())
+    }
+
+    const byId = (a: UInt64, b: UInt64) => Number(BigInt(a.toString()) - BigInt(b.toString()))
+    depots.sort(byId)
+    ships.sort(byId)
+
+    return [...depots, ...ships].slice(0, SHUTTLE_CANDIDATE_CAP).map((id) => id.toString())
+}
+
+function chainAssertion(e: unknown): string | undefined {
+    const detailsMessage = (e as {details?: {message?: string}[]}).details?.[0]?.message
+    const message = detailsMessage ?? (e instanceof Error ? e.message : String(e))
+    const match = message.match(/assertion failure with message:\s*(.*)/i)
+    return match ? match[1].trim() : undefined
+}
+
+export class ShuttleManager extends BaseManager {
+    private async query(
+        name:
+            | 'getcraftopts'
+            | 'getbuildopts'
+            | 'getclaimopts'
+            | 'getcbldopts'
+            | 'getstoreopts'
+            | 'gettakeopts',
+        data: unknown
+    ): Promise<ShuttleOptions> {
+        let raw: RawOptions
+        try {
+            raw = (await this.server.readonly(name as never, data as never)) as RawOptions
+        } catch (e) {
+            const reason = chainAssertion(e)
+            if (reason === undefined) throw e
+            return {
+                blocked: {code: shuttleReasonCode(reason), reason},
+                options: [],
+                auto: undefined,
+            }
+        }
+        return mapOptions(ServerContract.Types.shuttle_options.from(raw))
+    }
+
+    craft(req: {
+        shipId: UInt64Type
+        workshopId: UInt64Type
+        recipeId: UInt16Type
+        quantity: UInt32Type
+        inputs: ServerContract.ActionParams.Type.cargo_item[]
+        candidates: UInt64Type[]
+        recharge?: boolean
+    }): Promise<ShuttleOptions> {
+        return this.query('getcraftopts', {
+            ship_id: UInt64.from(req.shipId),
+            workshop_id: UInt64.from(req.workshopId),
+            recipe_id: UInt16.from(req.recipeId),
+            quantity: UInt32.from(req.quantity),
+            inputs: req.inputs,
+            candidates: req.candidates.map((c) => UInt64.from(c)),
+            recharge: req.recharge ?? false,
+        })
+    }
+
+    build(req: {
+        targetId: UInt64Type
+        dockId: UInt64Type
+        targetItemId: UInt16Type
+        inputs: ServerContract.ActionParams.Type.cargo_item[]
+        candidates: UInt64Type[]
+    }): Promise<ShuttleOptions> {
+        return this.query('getbuildopts', {
+            target_id: UInt64.from(req.targetId),
+            dock_id: UInt64.from(req.dockId),
+            target_item_id: UInt16.from(req.targetItemId),
+            inputs: req.inputs,
+            candidates: req.candidates.map((c) => UInt64.from(c)),
+        })
+    }
+
+    claim(req: {
+        jobId: UInt64Type
+        shipId: UInt64Type
+        candidates: UInt64Type[]
+    }): Promise<ShuttleOptions> {
+        return this.query('getclaimopts', {
+            job_id: UInt64.from(req.jobId),
+            ship_id: UInt64.from(req.shipId),
+            candidates: req.candidates.map((c) => UInt64.from(c)),
+        })
+    }
+
+    cancelBuild(req: {jobId: UInt64Type; candidates: UInt64Type[]}): Promise<ShuttleOptions> {
+        return this.query('getcbldopts', {
+            job_id: UInt64.from(req.jobId),
+            candidates: req.candidates.map((c) => UInt64.from(c)),
+        })
+    }
+
+    store(req: {
+        shipId: UInt64Type
+        depotId: UInt64Type
+        items: ServerContract.ActionParams.Type.cargo_item[]
+        candidates: UInt64Type[]
+    }): Promise<ShuttleOptions> {
+        return this.query('getstoreopts', {
+            ship_id: UInt64.from(req.shipId),
+            depot_id: UInt64.from(req.depotId),
+            items: req.items,
+            candidates: req.candidates.map((c) => UInt64.from(c)),
+        })
+    }
+
+    take(req: {
+        shipId: UInt64Type
+        depotId: UInt64Type
+        items: ServerContract.ActionParams.Type.cargo_item[]
+        candidates: UInt64Type[]
+    }): Promise<ShuttleOptions> {
+        return this.query('gettakeopts', {
+            ship_id: UInt64.from(req.shipId),
+            depot_id: UInt64.from(req.depotId),
+            items: req.items,
+            candidates: req.candidates.map((c) => UInt64.from(c)),
+        })
+    }
+}

package/src/resolution/resolve-item.ts

@@ -4,7 +4,7 @@ import type {ResourceCategory} from '../types'
 import {getItem, getModules} from '../data/catalog'
 import {ENTITY_SHIP, getPackedEntityType} from '../data/kind-registry'
 import {getEntityLayout} from '../data/recipes-runtime'
-import {entityMetadata, itemMetadata} from '../data/metadata'
+import {entityMetadata, getItemFamily} from '../data/metadata'
 import {
     getModuleCapabilityType,
     isModuleItem,
@@ -370,7 +370,7 @@ function resolveEntity(
                     modName = modItem.name
                     modTier = modItem.tier
                 } catch {
-                    modName = itemMetadata[modItemId]?.name ?? 'Module'
+                    modName = getItemFamily(modItemId)?.name ?? 'Module'
                 }
                 const group = computeCapabilityGroup(modType, decodedStats, modTier, slot.outputPct)
                 return {

package/src/scheduling/availability.ts

@@ -106,7 +106,17 @@ export function incomingSources(
     return out
 }
 
+// Mirrors for_each_task_cargo's hosted_civic_leg guard: a hosted Drop-off/Pickup moves E's cargo, not the host's.
+export function isHostedCivicLeg(task: Task): boolean {
+    const type = task.type.toNumber()
+    return (
+        (type === TaskType.CIVIC_DEPOSIT || type === TaskType.CIVIC_WITHDRAW) &&
+        task.couplings.length > 0
+    )
+}
+
 export function taskCargoEffect(task: Task): CargoEffect {
+    if (isHostedCivicLeg(task)) return {added: [], removed: []}
     switch (taskCargoRule(task.type.toNumber())) {
         case 'all-in':
         case 'undeploy':

package/src/scheduling/energy.ts

@@ -1,6 +1,10 @@
+import type {ServerContract} from '../contracts'
 import {TaskType} from '../types'
 import {createProjectedEntity, type Projectable} from './projection'
-import {orderedTasks} from './schedule'
+import {orderedTasks, unappliedTasks} from './schedule'
+import {taskEnergyDrawNeedsCoordinates, taskEnergyEffect} from './task-effects'
+
+type Task = ServerContract.Types.task
 
 export function energyAtTime(entity: Projectable, now: Date): number {
     const projected = createProjectedEntity(entity)
@@ -45,3 +49,53 @@ export function energyAtTime(entity: Projectable, now: Date): number {
 
     return clamp(running)
 }
+
+// Mirrors calc_task_effect's energy branch (projection.cpp): the step this task's type applies to running energy.
+function applyTaskEnergyEffect(
+    taskType: number,
+    hasCoordinates: boolean,
+    capacity: number | undefined,
+    cost: number | undefined,
+    energy: number
+): number {
+    const effect = taskEnergyEffect(taskType)
+    if (effect === 'fills') return capacity !== undefined ? capacity : energy
+    if (effect === 'zeroes') return cost === undefined ? 0 : energy > cost ? energy - cost : 0
+    if (cost === undefined) return energy
+    if (effect === 'draws' && (!taskEnergyDrawNeedsCoordinates(taskType) || hasCoordinates)) {
+        return energy > cost ? energy - cost : 0
+    }
+    return energy
+}
+
+function taskCost(task: Task): number | undefined {
+    return task.energy_cost !== undefined ? Number(task.energy_cost) : undefined
+}
+
+// Walks tasks in schedule order, gating on funding at each draw; false on the first shortfall.
+function tasksFundedFrom(
+    tasks: readonly {task: Task}[],
+    capacity: number | undefined,
+    baseEnergy: number
+): boolean {
+    let energy = baseEnergy
+    for (const {task} of tasks) {
+        const cost = taskCost(task)
+        if (cost !== undefined && energy < cost) return false
+        energy = applyTaskEnergyEffect(
+            task.type.toNumber(),
+            task.coordinates !== undefined,
+            capacity,
+            cost,
+            energy
+        )
+    }
+    return true
+}
+
+// Mirrors walk_pending_energy(require_funded=true) / energy_draws_funded in projection.cpp.
+export function energyDrawsFunded(entity: Projectable, baseEnergy: number): boolean {
+    const projected = createProjectedEntity(entity)
+    const capacity = projected.generator ? Number(projected.generator.capacity) : undefined
+    return tasksFundedFrom(unappliedTasks(entity), capacity, baseEnergy)
+}