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

package/src/scheduling/unwrap.test.ts

@@ -0,0 +1,86 @@
+import {describe, expect, test} from 'bun:test'
+import {
+    derivedLoaders,
+    unwrapTransitDuration,
+    unwrapLoadDuration,
+    estimateUnwrapDuration,
+    incomingHoldMass,
+    projectedPeakCargomass,
+} from './unwrap'
+
+describe('unwrap duration mirror', () => {
+    test('derivedLoaders aggregates lanes like derived_loaders()', () => {
+        expect(derivedLoaders([])).toBeNull()
+        expect(
+            derivedLoaders([
+                {mass: 1000, thrust: 10},
+                {mass: 1400, thrust: 20},
+            ])
+        ).toEqual({mass: 1200, thrust: 30, quantity: 2}) // floor(2400/2)=1200, sum thrust, count
+    })
+
+    test('transit floors distance then flight time', () => {
+        // distance = floor(sqrt(3^2+4^2)*10000)=50000; accel=400/mass*10000; flight=floor(2*sqrt(d/accel))
+        const mass = 1000
+        const accel = (400 / mass) * 10000
+        const expected = Math.floor(2 * Math.sqrt(50000 / accel))
+        expect(unwrapTransitDuration(mass, {x: 0, y: 0}, {x: 3, y: 4})).toBe(expected)
+    })
+
+    test('load uses altitude z, adds loader mass, divides by quantity', () => {
+        const loaders = {mass: 1200, thrust: 30, quantity: 2}
+        const itemMass = 800
+        const accel = (30 / (itemMass + 1200)) * 10000
+        const flight = Math.floor(2 * Math.sqrt(3000 / accel))
+        expect(unwrapLoadDuration(loaders, itemMass, 3000)).toBe(Math.floor(flight / 2))
+    })
+
+    test('zero item mass and no loaders are safe', () => {
+        expect(unwrapTransitDuration(0, {x: 0, y: 0}, {x: 9, y: 9})).toBe(0)
+        expect(unwrapLoadDuration(null, 500, 3000)).toBe(0)
+    })
+
+    test('load altitude is floored so ground-level (z=0) destinations are not instant', () => {
+        const loaders = {mass: 500, thrust: 200, quantity: 1}
+        const atZero = unwrapLoadDuration(loaders, 1000, 0)
+        const at800 = unwrapLoadDuration(loaders, 1000, 800)
+        expect(atZero).toBeGreaterThan(0)
+        expect(atZero).toBe(at800)
+    })
+
+    test('estimateUnwrapDuration uses worst-loader baseline when dest has no loaders', () => {
+        // IRON (101); same coords so transit is 0 and the estimate is baseline load alone
+        const item = {itemId: 101, quantity: 10, modules: [], originX: 0, originY: 0}
+        const bareDest = {loader_lanes: [], coordinates: {x: 0, y: 0, z: 800}}
+
+        const bare = estimateUnwrapDuration(bareDest, item)
+        expect(bare).toBeGreaterThan(0)
+
+        const loadedDest = {
+            loader_lanes: [{mass: 500, thrust: 200}],
+            coordinates: {x: 0, y: 0, z: 800},
+        }
+        const loaded = estimateUnwrapDuration(loadedDest, item)
+        expect(loaded).toBeLessThanOrEqual(bare)
+
+        expect(unwrapLoadDuration(null, 500, 3000)).toBe(0)
+    })
+})
+
+test('incomingHoldMass sums incoming-kind hold mass', () => {
+    expect(incomingHoldMass([])).toBe(0)
+    // PUSH(2) + FLIGHT(5) count; BUILD(4) does not
+    expect(
+        incomingHoldMass([
+            {kind: 2, incoming_mass: 100},
+            {kind: 4, incoming_mass: 999},
+            {kind: 5, incoming_mass: 50},
+        ])
+    ).toBe(150)
+})
+
+test('projectedPeakCargomass tracks the running peak from cargomass', () => {
+    const entity = {cargomass: 1000, lanes: [], cargo: [], schedule: undefined} as never
+    // No pending tasks: peak = base + candidate add.
+    expect(projectedPeakCargomass(entity, new Date(0), 500)).toBe(1500)
+})

package/src/scheduling/unwrap.ts

@@ -0,0 +1,190 @@
+import type {UInt16Type, UInt32Type} from '@wharfkit/antelope'
+import {calcCargoItemMass} from '../capabilities/storage'
+import type {ServerContract} from '../contracts'
+import {PRECISION} from '../types'
+import * as sched from './schedule'
+import {taskCargoEffect} from './availability'
+import {candidateLaneCompletesAt} from './lanes'
+
+const NFT_TRANSIT_THRUST = 400
+const BASELINE_LOADER: DerivedLoaders = {mass: 2000, thrust: 1, quantity: 1}
+// ground-level entities (warehouses, z=0) still incur a base orbital climb of load effort
+const MIN_LOAD_Z = 800
+
+export interface DerivedLoaders {
+    mass: number
+    thrust: number
+    quantity: number
+}
+
+export function derivedLoaders(
+    lanes: {mass: UInt32Type | number; thrust: UInt16Type | number}[] | undefined
+): DerivedLoaders | null {
+    if (!lanes || lanes.length === 0) return null
+    let totalMass = 0
+    let totalThrust = 0
+    for (const l of lanes) {
+        totalMass += Number(l.mass)
+        totalThrust += Number(l.thrust)
+    }
+    const count = lanes.length
+    return {
+        mass: Math.floor(totalMass / count),
+        thrust: Math.min(totalThrust, 65_535),
+        quantity: count,
+    }
+}
+
+function acceleration(thrust: number, mass: number): number {
+    if (mass <= 0) return 0
+    return (thrust / mass) * PRECISION
+}
+
+function flightTime(distance: number, accel: number): number {
+    if (accel <= 0 || distance <= 0) return 0
+    return Math.floor(2 * Math.sqrt(distance / accel))
+}
+
+function distance2d(ax: number, ay: number, bx: number, by: number): number {
+    const dx = ax - bx
+    const dy = ay - by
+    return Math.floor(Math.sqrt(dx * dx + dy * dy) * PRECISION)
+}
+
+export function unwrapTransitDuration(
+    itemMass: number,
+    origin: {x: number; y: number},
+    dest: {x: number; y: number}
+): number {
+    if (itemMass <= 0) return 0
+    return flightTime(
+        distance2d(origin.x, origin.y, dest.x, dest.y),
+        acceleration(NFT_TRANSIT_THRUST, itemMass)
+    )
+}
+
+export function unwrapLoadDuration(
+    loaders: DerivedLoaders | null,
+    itemMass: number,
+    destZ: number
+): number {
+    if (!loaders || itemMass <= 0) return 0
+    const total = itemMass + loaders.mass
+    const flight = flightTime(Math.max(destZ, MIN_LOAD_Z), acceleration(loaders.thrust, total))
+    return Math.floor(flight / loaders.quantity)
+}
+
+export interface UnwrapItem {
+    itemId: number
+    quantity: number
+    modules: ServerContract.Types.module_entry[]
+    originX: number
+    originY: number
+}
+
+export interface UnwrapDestination {
+    loader_lanes?: {mass: UInt32Type | number; thrust: UInt16Type | number}[]
+    coordinates: {x: UInt32Type | number; y: UInt32Type | number; z?: UInt32Type | number}
+}
+
+export function estimateUnwrapDuration(dest: UnwrapDestination, item: UnwrapItem): number {
+    const itemMass = Number(
+        calcCargoItemMass({
+            item_id: item.itemId as never,
+            quantity: item.quantity as never,
+            modules: item.modules,
+        })
+    )
+    const loaders = derivedLoaders(dest.loader_lanes) ?? BASELINE_LOADER
+    const dz = Number(dest.coordinates.z ?? 0)
+    const load = unwrapLoadDuration(loaders, itemMass, dz)
+    const transit = unwrapTransitDuration(
+        itemMass,
+        {x: item.originX, y: item.originY},
+        {
+            x: Number(dest.coordinates.x),
+            y: Number(dest.coordinates.y),
+        }
+    )
+    return load + transit
+}
+
+// Hold kinds that count as incoming (mirror is_incoming_hold_kind in holds.hpp).
+const INCOMING_HOLD_KINDS = new Set<number>([2, 3, 5])
+
+export function incomingHoldMass(
+    holds:
+        | {kind: number | {toNumber(): number}; incoming_mass: number | {toNumber(): number}}[]
+        | undefined
+): number {
+    if (!holds) return 0
+    let total = 0
+    for (const h of holds) {
+        if (INCOMING_HOLD_KINDS.has(Number(h.kind))) total += Number(h.incoming_mass)
+    }
+    return total
+}
+
+type CargoItem = ServerContract.Types.cargo_item
+
+function cargoListMass(items: CargoItem[]): number {
+    let m = 0
+    for (const it of items) m += Number(calcCargoItemMass(it))
+    return m
+}
+
+export function projectedPeakCargomass(
+    entity: sched.ScheduleData & {cargomass: number | {toNumber(): number}},
+    at: Date,
+    addMass: number,
+    removeMass = 0
+): number {
+    const events: {t: number; delta: number}[] = []
+    for (const ordered of sched.orderedTasks(entity)) {
+        const eff = taskCargoEffect(ordered.task)
+        const delta = cargoListMass(eff.added) - cargoListMass(eff.removed)
+        events.push({t: ordered.completesAt.getTime(), delta})
+    }
+    events.push({t: at.getTime(), delta: addMass - removeMass})
+    events.sort((a, b) => (a.t !== b.t ? a.t - b.t : b.delta - a.delta))
+    let running = Number(entity.cargomass)
+    let peak = running
+    for (const e of events) {
+        running += e.delta
+        if (running < 0) running = 0
+        if (running > peak) peak = running
+    }
+    return Math.min(peak, 0xffff_ffff)
+}
+
+export function receiveFits(
+    dest: UnwrapDestination &
+        sched.ScheduleData & {
+            cargomass: number | {toNumber(): number}
+            capacity?: number | {toNumber(): number}
+            holds?: {
+                kind: number | {toNumber(): number}
+                incoming_mass: number | {toNumber(): number}
+            }[]
+        },
+    item: UnwrapItem,
+    now: Date
+): boolean {
+    const capacity = Number(dest.capacity ?? 0)
+    if (capacity <= 0) return false
+    const itemMass = Number(
+        calcCargoItemMass({
+            item_id: item.itemId as never,
+            quantity: item.quantity as never,
+            modules: item.modules,
+        })
+    )
+    const duration = estimateUnwrapDuration(dest, item)
+    const candidateCompletes = candidateLaneCompletesAt(dest, sched.LANE_MOBILITY, duration, now)
+    const peak = projectedPeakCargomass(
+        dest,
+        candidateCompletes,
+        itemMass + incomingHoldMass(dest.holds)
+    )
+    return peak <= capacity
+}

package/src/shipload.ts

@@ -7,8 +7,11 @@ import {GameContext} from './managers/context'
 import type {EntitiesManager} from './managers/entities'
 import type {PlayersManager} from './managers/players'
 import type {LocationsManager} from './managers/locations'
+import type {CoordinatesManager} from './managers/coordinates'
 import type {EpochsManager} from './managers/epochs'
 import type {ActionsManager} from './managers/actions'
+import type {ClusterManager} from './managers/cluster'
+import type {NftManager} from './managers/nft'
 import type {SubscriptionsManager} from './subscriptions/manager'
 import type {GameState} from './entities/gamestate'
 
@@ -17,6 +20,7 @@ interface ShiploadOptions {
     serverContractName?: string
     client?: APIClient
     subscriptionsUrl?: string
+    atomicAssetsAccount?: string
 }
 
 interface ShiploadConstructorOptions extends ShiploadOptions {
@@ -39,7 +43,12 @@ export class Shipload {
             ? serverContract
             : new ServerContract.Contract({client: apiClient})
 
-        this._context = new GameContext(apiClient, server, platform)
+        this._context = new GameContext(
+            apiClient,
+            server,
+            platform,
+            constructorOptions?.atomicAssetsAccount ?? 'atomicassets'
+        )
 
         if (constructorOptions?.subscriptionsUrl) {
             this._context.setSubscriptionsUrl(constructorOptions.subscriptionsUrl)
@@ -79,6 +88,10 @@ export class Shipload {
         return this._context.client
     }
 
+    get atomicAssetsAccount(): string {
+        return this._context.atomicAssetsAccount
+    }
+
     get server(): Contract {
         return this._context.server
     }
@@ -99,6 +112,10 @@ export class Shipload {
         return this._context.locations
     }
 
+    get coordinates(): CoordinatesManager {
+        return this._context.coordinates
+    }
+
     get epochs(): EpochsManager {
         return this._context.epochs
     }
@@ -107,6 +124,14 @@ export class Shipload {
         return this._context.actions
     }
 
+    get clusters(): ClusterManager {
+        return this._context.clusters
+    }
+
+    get nft(): NftManager {
+        return this._context.nft
+    }
+
     get subscriptions(): SubscriptionsManager {
         return this._context.subscriptions
     }

package/src/subscriptions/manager.cluster.test.ts

@@ -0,0 +1,51 @@
+import {afterEach, describe, expect, test} from 'bun:test'
+import {SubscriptionsManager} from './manager'
+import type {ServerMessage} from './types'
+
+function createManager(): SubscriptionsManager {
+    return new SubscriptionsManager({url: 'ws://localhost:0'})
+}
+
+function deliver(mgr: SubscriptionsManager, msg: ServerMessage) {
+    ;(mgr as unknown as {onMessage(m: ServerMessage): void}).onMessage(msg)
+}
+
+describe('cluster delta routing', () => {
+    let mgr: SubscriptionsManager | undefined
+
+    afterEach(() => {
+        mgr?.close()
+        mgr = undefined
+    })
+
+    test('routes a cluster frame to the matching entity subscription onCluster', () => {
+        mgr = createManager()
+        const received: unknown[] = []
+        const handle = mgr.subscribeEntity(42, {
+            onCluster: (p) => received.push(p),
+        })
+        deliver(mgr, {
+            type: 'cluster',
+            sub_id: handle.subId,
+            hub_id: 42,
+            seq: 7,
+            cells: [{gx: 0, gy: 1, entity: 99, type: 'warehouse'}],
+        })
+        expect(received).toEqual([
+            {
+                hubId: 42,
+                seq: 7,
+                cells: [{gx: 0, gy: 1, entity: 99, type: 'warehouse'}],
+                erased: false,
+            },
+        ])
+    })
+
+    test('an erased cluster frame yields cells:null, erased:true', () => {
+        mgr = createManager()
+        const received: unknown[] = []
+        const handle = mgr.subscribeEntity(42, {onCluster: (p) => received.push(p)})
+        deliver(mgr, {type: 'cluster', sub_id: handle.subId, hub_id: 42, seq: 8, erased: true})
+        expect(received).toEqual([{hubId: 42, seq: 8, cells: null, erased: true}])
+    })
+})