@shipload/sdk 2.0.0-rc2 → 2.0.0-rc21

package/src/subscriptions/manager.ts

@@ -0,0 +1,240 @@
+import {WebSocketConnection} from './connection'
+import type {
+    BoundingBox,
+    BoundsDeltaMessage,
+    ClientMessage,
+    ServerMessage,
+    SnapshotMessage,
+    SubscribeEntityMessage,
+    SubscribeMessage,
+    UnsubscribeEntityMessage,
+    UpdateBoundsMessage,
+    UpdateMessage,
+    WireEntity,
+} from './types'
+import {mapEntity, parseWireEntity} from './mappers'
+import type {Ship} from '../entities/ship'
+import type {Warehouse} from '../entities/warehouse'
+import type {Container} from '../entities/container'
+
+export type SubscriptionEntityType = 'ship' | 'warehouse' | 'container'
+export type EntityInstance = Ship | Warehouse | Container
+
+export interface SubscriptionsOptions {
+    url: string
+}
+
+export interface BoundsSubscriptionHandle {
+    readonly subId: string
+    unsubscribe(): void
+    updateBounds(bounds: BoundingBox): void
+    current: Map<number, EntityInstance>
+}
+
+export interface EntitySubscriptionHandle {
+    readonly subId: string
+    readonly entityType: SubscriptionEntityType
+    readonly entityId: string
+    unsubscribe(): void
+    current: EntityInstance | null
+}
+
+export class SubscriptionsManager {
+    private readonly conn: WebSocketConnection
+    private readonly entitySubs = new Map<
+        string,
+        {
+            type: SubscriptionEntityType
+            id: string
+            onUpdate: (e: EntityInstance) => void
+            handle: EntitySubscriptionHandle
+        }
+    >()
+    private readonly boundsSubs = new Map<
+        string,
+        {
+            onSnapshot?: (entities: EntityInstance[]) => void
+            onUpdate?: (entity: EntityInstance) => void
+            onBoundsDelta?: (entered: EntityInstance[], exited: number[]) => void
+            handle: BoundsSubscriptionHandle
+        }
+    >()
+    private subCounter = 0
+
+    constructor(opts: SubscriptionsOptions) {
+        this.conn = new WebSocketConnection({
+            url: opts.url,
+            onMessage: (m) => this.onMessage(m),
+        })
+        this.conn.connect()
+    }
+
+    close() {
+        this.conn.close()
+    }
+
+    private generateSubID(prefix: string): string {
+        this.subCounter += 1
+        return `${prefix}-${this.subCounter}-${Math.random().toString(36).slice(2, 8)}`
+    }
+
+    private sendMessage(msg: ClientMessage) {
+        this.conn.send(msg)
+    }
+
+    subscribeEntity(
+        type: SubscriptionEntityType,
+        id: string,
+        onUpdate: (e: EntityInstance) => void
+    ): EntitySubscriptionHandle {
+        const subId = this.generateSubID('ent')
+        const msg: SubscribeEntityMessage = {
+            type: 'subscribe_entity',
+            sub_id: subId,
+            entity_type: type,
+            entity_id: id,
+        }
+        const handle: EntitySubscriptionHandle = {
+            subId,
+            entityType: type,
+            entityId: id,
+            unsubscribe: () => this.unsubscribeEntity(subId),
+            current: null,
+        }
+        this.entitySubs.set(subId, {type, id, onUpdate, handle})
+        this.sendMessage(msg)
+        return handle
+    }
+
+    private unsubscribeEntity(subId: string) {
+        const entry = this.entitySubs.get(subId)
+        if (!entry) return
+        this.entitySubs.delete(subId)
+        const msg: UnsubscribeEntityMessage = {type: 'unsubscribe_entity', sub_id: subId}
+        this.sendMessage(msg)
+    }
+
+    subscribeBounds(
+        bounds: BoundingBox,
+        handlers: {
+            onSnapshot?: (entities: EntityInstance[]) => void
+            onUpdate?: (entity: EntityInstance) => void
+            onBoundsDelta?: (entered: EntityInstance[], exited: number[]) => void
+            owner?: string
+            prioritizeOwner?: string
+        }
+    ): BoundsSubscriptionHandle {
+        const subId = this.generateSubID('bnd')
+        const msg: SubscribeMessage = {
+            type: 'subscribe',
+            sub_id: subId,
+            bounds,
+            owner: handlers.owner,
+            prioritize_owner: handlers.prioritizeOwner,
+        }
+        const handle: BoundsSubscriptionHandle = {
+            subId,
+            unsubscribe: () => this.unsubscribeBounds(subId),
+            updateBounds: (b) => this.updateBounds(subId, b),
+            current: new Map(),
+        }
+        this.boundsSubs.set(subId, {
+            onSnapshot: handlers.onSnapshot,
+            onUpdate: handlers.onUpdate,
+            onBoundsDelta: handlers.onBoundsDelta,
+            handle,
+        })
+        this.sendMessage(msg)
+        return handle
+    }
+
+    private unsubscribeBounds(subId: string) {
+        this.boundsSubs.delete(subId)
+        this.sendMessage({type: 'unsubscribe', sub_id: subId})
+    }
+
+    private updateBounds(subId: string, bounds: BoundingBox) {
+        const msg: UpdateBoundsMessage = {type: 'update_bounds', sub_id: subId, bounds}
+        this.sendMessage(msg)
+    }
+
+    private onMessage(msg: ServerMessage) {
+        switch (msg.type) {
+            case 'snapshot':
+                this.handleSnapshot(msg)
+                break
+            case 'update':
+                this.handleUpdate(msg)
+                break
+            case 'bounds_delta':
+                this.handleBoundsDelta(msg)
+                break
+            case 'error':
+                this.handleError(msg)
+                break
+        }
+    }
+
+    private parseEntity(raw: WireEntity): EntityInstance {
+        const ei = parseWireEntity(raw)
+        return mapEntity(ei)
+    }
+
+    private handleSnapshot(msg: SnapshotMessage) {
+        const entSub = this.entitySubs.get(msg.sub_id)
+        if (entSub) {
+            if (msg.entities.length > 0) {
+                const ent = this.parseEntity(msg.entities[0])
+                entSub.handle.current = ent
+                entSub.onUpdate(ent)
+            }
+            return
+        }
+        const boundsSub = this.boundsSubs.get(msg.sub_id)
+        if (boundsSub) {
+            const ents = msg.entities.map((e) => this.parseEntity(e))
+            boundsSub.handle.current.clear()
+            for (const e of ents) boundsSub.handle.current.set(Number(e.id), e)
+            boundsSub.onSnapshot?.(ents)
+        }
+    }
+
+    private handleUpdate(msg: UpdateMessage) {
+        const ent = this.parseEntity(msg.entity)
+        for (const subId of msg.sub_ids) {
+            const entSub = this.entitySubs.get(subId)
+            if (entSub) {
+                entSub.handle.current = ent
+                entSub.onUpdate(ent)
+                continue
+            }
+            const boundsSub = this.boundsSubs.get(subId)
+            if (boundsSub) {
+                boundsSub.handle.current.set(msg.entity_id, ent)
+                boundsSub.onUpdate?.(ent)
+            }
+        }
+    }
+
+    private handleBoundsDelta(msg: BoundsDeltaMessage) {
+        const sub = this.boundsSubs.get(msg.sub_id)
+        if (!sub) return
+        const entered = msg.entered.map((e) => this.parseEntity(e))
+        for (const e of entered) sub.handle.current.set(Number(e.id), e)
+        for (const id of msg.exited) sub.handle.current.delete(id)
+        sub.onBoundsDelta?.(entered, msg.exited)
+    }
+
+    private handleError(msg: {sub_id?: string; error: string}) {
+        if (!msg.sub_id) return
+        const entSub = this.entitySubs.get(msg.sub_id)
+        if (entSub) {
+            this.entitySubs.delete(msg.sub_id)
+            return
+        }
+        const boundsSub = this.boundsSubs.get(msg.sub_id)
+        if (boundsSub) {
+            this.boundsSubs.delete(msg.sub_id)
+        }
+    }
+}

package/src/subscriptions/mappers.ts

@@ -0,0 +1,28 @@
+import {ServerContract} from '../contracts'
+import {Ship} from '../entities/ship'
+import {Warehouse} from '../entities/warehouse'
+import {Container} from '../entities/container'
+import type {WireEntity} from './types'
+
+export function mapEntity(ei: ServerContract.Types.entity_info): Ship | Warehouse | Container {
+    if (ei.type.equals('ship')) return new Ship(ei)
+    if (ei.type.equals('warehouse')) return new Warehouse(ei)
+    if (ei.type.equals('container')) return new Container(ei)
+    throw new Error(`mapEntity: unknown entity type ${ei.type.toString()}`)
+}
+
+export function parseWireEntity(raw: WireEntity): ServerContract.Types.entity_info {
+    const shaped: Record<string, unknown> = {...raw}
+
+    if (typeof shaped.type === 'number' && typeof shaped.type_name === 'string') {
+        shaped.type = shaped.type_name
+    }
+    delete shaped.type_name
+
+    if (shaped.entity_name === undefined && typeof shaped.name === 'string') {
+        shaped.entity_name = shaped.name
+    }
+    delete shaped.name
+
+    return ServerContract.Types.entity_info.from(shaped)
+}

package/src/subscriptions/types.ts

@@ -0,0 +1,143 @@
+import type {ServerContract} from '../contracts'
+
+export type EntityInfo = ServerContract.Types.entity_info
+
+export interface BoundingBox {
+    min_x: number
+    min_y: number
+    max_x: number
+    max_y: number
+}
+
+export interface WireCoordinates {
+    x: number
+    y: number
+    z?: number
+}
+
+// --- Client → Server ---
+
+export type SubscribeMessage = {
+    type: 'subscribe'
+    sub_id: string
+    bounds?: BoundingBox
+    owner?: string
+    prioritize_owner?: string
+}
+
+export type UpdateBoundsMessage = {
+    type: 'update_bounds'
+    sub_id: string
+    bounds: BoundingBox
+}
+
+export type UnsubscribeMessage = {
+    type: 'unsubscribe'
+    sub_id: string
+}
+
+export type SubscribeEntityMessage = {
+    type: 'subscribe_entity'
+    sub_id: string
+    entity_type: 'ship' | 'warehouse' | 'container'
+    entity_id: string
+}
+
+export type UnsubscribeEntityMessage = {
+    type: 'unsubscribe_entity'
+    sub_id: string
+}
+
+export type SubscribeEventsMessage = {
+    type: 'subscribe_events'
+    sub_id: string
+    event_filter?: Record<string, unknown>
+}
+
+export type UnsubscribeEventsMessage = {
+    type: 'unsubscribe_events'
+    sub_id: string
+}
+
+export type PingMessage = {type: 'ping'}
+
+export type ClientMessage =
+    | SubscribeMessage
+    | UpdateBoundsMessage
+    | UnsubscribeMessage
+    | SubscribeEntityMessage
+    | UnsubscribeEntityMessage
+    | SubscribeEventsMessage
+    | UnsubscribeEventsMessage
+    | PingMessage
+
+// --- Server → Client ---
+
+export type AckMessage = {
+    type: 'subscribed' | 'unsubscribed' | 'bounds_updated'
+    sub_id: string
+}
+
+export type WireEntity = Record<string, unknown> & {
+    type: number
+    type_name: 'ship' | 'warehouse' | 'container'
+    id: string | number
+    owner: string
+    coordinates: WireCoordinates
+}
+
+export type SnapshotMessage = {
+    type: 'snapshot'
+    sub_id: string
+    seq: number
+    entities: WireEntity[]
+    truncated?: boolean
+}
+
+export type UpdateMessage = {
+    type: 'update'
+    sub_ids: string[]
+    entity_id: number
+    entity: WireEntity
+    seq: number
+}
+
+export type BoundsDeltaMessage = {
+    type: 'bounds_delta'
+    sub_id: string
+    entered: WireEntity[]
+    exited: number[]
+    seq: number
+    truncated?: boolean
+}
+
+export type EventMessage = {
+    type: 'event'
+    sub_id: string
+    catchup: boolean
+    events: Array<Record<string, unknown>>
+    seq?: number
+}
+
+export type EventCatchupCompleteMessage = {
+    type: 'event_catchup_complete'
+    sub_id: string
+}
+
+export type PongMessage = {type: 'pong'}
+
+export type ErrorMessage = {
+    type: 'error'
+    error: string
+    sub_id?: string
+}
+
+export type ServerMessage =
+    | AckMessage
+    | SnapshotMessage
+    | UpdateMessage
+    | BoundsDeltaMessage
+    | EventMessage
+    | EventCatchupCompleteMessage
+    | PongMessage
+    | ErrorMessage

package/src/travel/travel.ts

@@ -14,6 +14,7 @@ import {
     Checksum256,
     Int64,
     Int64Type,
+    UInt16,
     UInt32,
     UInt32Type,
     UInt64,
@@ -22,24 +23,24 @@ import {
 
 import {ServerContract} from '../contracts'
 import {
+    BASE_ORBITAL_MASS,
     CargoMassInfo,
     Distance,
-    INITIAL_SHIP_MASS,
     MAX_ORBITAL_ALTITUDE,
     MIN_ORBITAL_ALTITUDE,
     PRECISION,
     ShipLike,
     TaskType,
 } from '../types'
-import {getGood} from '../market/goods'
+import {getItem} from '../market/items'
 import {hasSystem} from '../utils/system'
 
 export function calc_orbital_altitude(mass: number): number {
-    if (mass <= INITIAL_SHIP_MASS) {
+    if (mass <= BASE_ORBITAL_MASS) {
         return MIN_ORBITAL_ALTITUDE
     }
 
-    const ratio = mass / INITIAL_SHIP_MASS
+    const ratio = mass / BASE_ORBITAL_MASS
     const capRatio = 10.0
     let scale = Math.log(ratio) / Math.log(capRatio)
     scale = Math.min(scale, 1.0)
@@ -126,7 +127,12 @@ export function calc_rechargetime(
 }
 
 export function calc_ship_rechargetime(ship: ShipLike): UInt32 {
-    return calc_rechargetime(ship.generator.capacity, ship.energy, ship.generator.recharge)
+    if (!ship.generator) return UInt32.from(0)
+    return calc_rechargetime(
+        ship.generator.capacity,
+        ship.energy ?? UInt16.from(0),
+        ship.generator.recharge
+    )
 }
 
 export function calc_flighttime(distance: UInt64Type, acceleration: number): UInt32 {
@@ -139,7 +145,9 @@ export function calc_loader_flighttime(ship: ShipLike, mass: UInt64, altitude?:
 }
 
 export function calc_loader_acceleration(ship: ShipLike, mass: UInt64): number {
-    return calc_acceleration(Number(ship.loaders.thrust), Number(mass) + Number(ship.loaders.mass))
+    const thrust = ship.loaders ? Number(ship.loaders.thrust) : 0
+    const loaderMass = ship.loaders ? Number(ship.loaders.mass) : 0
+    return calc_acceleration(thrust, Number(mass) + loaderMass)
 }
 
 export function calc_ship_flighttime(ship: ShipLike, mass: UInt64, distance: UInt64): UInt32 {
@@ -148,7 +156,8 @@ export function calc_ship_flighttime(ship: ShipLike, mass: UInt64, distance: UIn
 }
 
 export function calc_ship_acceleration(ship: ShipLike, mass: UInt64): number {
-    return calc_acceleration(Number(ship.engines.thrust), Number(mass))
+    const thrust = ship.engines ? Number(ship.engines.thrust) : 0
+    return calc_acceleration(thrust, Number(mass))
 }
 
 export function calc_acceleration(thrust: number, mass: number): number {
@@ -160,12 +169,13 @@ export function calc_ship_mass(ship: ShipLike, cargos: CargoMassInfo[]): UInt64
 
     mass.add(ship.hullmass)
 
-    if (ship.loaders.quantity.gt(UInt32.zero)) {
+    if (ship.loaders && ship.loaders.quantity.gt(UInt32.zero)) {
         mass.add(ship.loaders.mass.multiplying(ship.loaders.quantity))
     }
 
     for (const cargo of cargos) {
-        mass.add(getGood(cargo.good_id).mass.multiplying(cargo.quantity))
+        const cargoMass = getItem(cargo.item_id).mass * Number(UInt32.from(cargo.quantity))
+        mass.add(UInt64.from(cargoMass))
     }
 
     return mass
@@ -183,11 +193,11 @@ export function calculateTransferTime(
     let mass = UInt64.from(0)
 
     for (const cargo of cargos) {
-        const qty = quantities?.get(Number(cargo.good_id)) ?? 0
+        const qty = quantities?.get(Number(cargo.item_id)) ?? 0
         if (qty > 0) {
-            const good_mass = getGood(cargo.good_id).mass
-            const cargo_mass = good_mass.multiplying(qty)
-            mass = UInt64.from(mass).adding(cargo_mass)
+            const good_mass = getItem(cargo.item_id).mass
+            const cargo_mass = good_mass * qty
+            mass = UInt64.from(mass).adding(UInt64.from(cargo_mass))
         }
     }
 
@@ -195,6 +205,7 @@ export function calculateTransferTime(
         return UInt32.from(0)
     }
 
+    if (!ship.loaders) return UInt32.from(0)
     mass = UInt64.from(mass).adding(ship.loaders.mass)
     const transfer_time = calc_loader_flighttime(ship, mass)
     return transfer_time.dividing(ship.loaders.quantity)
@@ -231,20 +242,20 @@ export function calculateLoadTimeBreakdown(
     let mass_load = UInt64.from(0)
 
     for (const cargo of cargos) {
-        const goodId = Number(cargo.good_id)
+        const goodId = Number(cargo.item_id)
         const loadQty = loadQuantities?.get(goodId) ?? 0
         const unloadQty = unloadQuantities?.get(goodId) ?? 0
 
         if (loadQty > 0 || unloadQty > 0) {
-            const good = getGood(cargo.good_id)
+            const good = getItem(cargo.item_id)
 
             if (loadQty > 0) {
-                const cargo_mass = good.mass.multiplying(loadQty)
-                mass_load = UInt64.from(mass_load).adding(cargo_mass)
+                const cargo_mass = good.mass * loadQty
+                mass_load = UInt64.from(mass_load).adding(UInt64.from(cargo_mass))
             }
             if (unloadQty > 0) {
-                const cargo_mass = good.mass.multiplying(unloadQty)
-                mass_unload = UInt64.from(mass_unload).adding(cargo_mass)
+                const cargo_mass = good.mass * unloadQty
+                mass_unload = UInt64.from(mass_unload).adding(UInt64.from(cargo_mass))
             }
         }
     }
@@ -252,17 +263,17 @@ export function calculateLoadTimeBreakdown(
     let unloadTime = 0
     let loadTime = 0
 
-    if (mass_unload.gt(UInt64.zero)) {
+    if (mass_unload.gt(UInt64.zero) && ship.loaders) {
         const totalMass = UInt64.from(mass_unload).adding(ship.loaders.mass)
         unloadTime = Number(calc_loader_flighttime(ship, totalMass))
     }
 
-    if (mass_load.gt(UInt64.zero)) {
+    if (mass_load.gt(UInt64.zero) && ship.loaders) {
         const totalMass = UInt64.from(mass_load).adding(ship.loaders.mass)
         loadTime = Number(calc_loader_flighttime(ship, totalMass))
     }
 
-    const numLoaders = Number(ship.loaders.quantity)
+    const numLoaders = ship.loaders ? Number(ship.loaders.quantity) : 0
     const totalTime = numLoaders > 0 ? (unloadTime + loadTime) / numLoaders : 0
     const unloadTimePerLoader = numLoaders > 0 ? unloadTime / numLoaders : 0
     const loadTimePerLoader = numLoaders > 0 ? loadTime / numLoaders : 0
@@ -307,6 +318,7 @@ export function estimateTravelTime(
     if (
         loadMass &&
         UInt32.from(loadMass).gt(UInt32.zero) &&
+        ship.loaders &&
         ship.loaders.quantity.gt(UInt32.zero)
     ) {
         const totalMass = UInt64.from(loadMass).adding(ship.loaders.mass)
@@ -316,6 +328,7 @@ export function estimateTravelTime(
     if (
         unloadMass &&
         UInt32.from(unloadMass).gt(UInt32.zero) &&
+        ship.loaders &&
         ship.loaders.quantity.gt(UInt32.zero)
     ) {
         const totalMass = UInt64.from(unloadMass).adding(ship.loaders.mass)
@@ -346,8 +359,9 @@ export function estimateDealTravelTime(
 }
 
 export function hasEnergyForDistance(ship: ShipLike, distance: UInt64Type): boolean {
+    if (!ship.engines) return false
     const energyNeeded = UInt64.from(distance).dividing(PRECISION).multiplying(ship.engines.drain)
-    return UInt64.from(ship.energy).gte(energyNeeded)
+    return UInt64.from(ship.energy ?? 0).gte(energyNeeded)
 }
 
 export interface TransferEntity {

package/src/types/capabilities.ts

@@ -20,12 +20,8 @@ export interface LoaderCapability {
     loaders: ServerContract.Types.loader_stats
 }
 
-export interface TradeCapability {
-    trade: ServerContract.Types.trade_stats
-}
-
-export interface ExtractorCapability {
-    extractor: ServerContract.Types.extractor_stats
+export interface GathererCapability {
+    gatherer: ServerContract.Types.gatherer_stats
 }
 
 export interface MassCapability {
@@ -42,8 +38,9 @@ export interface EntityCapabilities {
     engines?: ServerContract.Types.movement_stats
     generator?: ServerContract.Types.energy_stats
     loaders?: ServerContract.Types.loader_stats
-    trade?: ServerContract.Types.trade_stats
-    extractor?: ServerContract.Types.extractor_stats
+    gatherer?: ServerContract.Types.gatherer_stats
+    crafter?: ServerContract.Types.crafter_stats
+    hauler?: ServerContract.Types.hauler_stats
 }
 
 export interface EntityState {
@@ -66,14 +63,14 @@ export function capsHasLoaders(caps: EntityCapabilities): boolean {
     return caps.loaders !== undefined
 }
 
-export function capsHasTrade(caps: EntityCapabilities): boolean {
-    return caps.trade !== undefined
-}
-
-export function capsHasExtractor(caps: EntityCapabilities): boolean {
-    return caps.extractor !== undefined
+export function capsHasGatherer(caps: EntityCapabilities): boolean {
+    return caps.gatherer !== undefined
 }
 
 export function capsHasMass(caps: EntityCapabilities): boolean {
     return caps.hullmass !== undefined
 }
+
+export function capsHasHauler(caps: EntityCapabilities): boolean {
+    return caps.hauler !== undefined
+}

package/src/types/entity-traits.ts

@@ -11,7 +11,6 @@ export interface EntityTraits {
     isMovable: boolean
     hasEnergy: boolean
     hasLoaders: boolean
-    hasTrade: boolean
     notFoundError: string
 }
 
@@ -20,7 +19,7 @@ export const shipTraits: EntityTraits = {
     isMovable: true,
     hasEnergy: true,
     hasLoaders: true,
-    hasTrade: true,
+
     notFoundError: 'ship not found',
 }
 
@@ -29,7 +28,7 @@ export const warehouseTraits: EntityTraits = {
     isMovable: false,
     hasEnergy: false,
     hasLoaders: true,
-    hasTrade: false,
+
     notFoundError: 'warehouse not found',
 }
 
@@ -38,7 +37,7 @@ export const containerTraits: EntityTraits = {
     isMovable: true,
     hasEnergy: false,
     hasLoaders: false,
-    hasTrade: false,
+
     notFoundError: 'container not found',
 }
 

package/src/types/entity.ts

@@ -19,17 +19,20 @@ export interface Entity {
 }
 
 export type ShipEntity = Entity &
-    MovementCapability &
-    EnergyCapability &
+    Partial<MovementCapability> &
+    Partial<EnergyCapability> &
     StorageCapability &
-    LoaderCapability &
+    Partial<LoaderCapability> &
     MassCapability &
     ScheduleCapability & {
-        trade?: ServerContract.Types.trade_stats
-        extractor?: ServerContract.Types.extractor_stats
+        gatherer?: ServerContract.Types.gatherer_stats
     }
 
-export type WarehouseEntity = Entity & StorageCapability & LoaderCapability & ScheduleCapability
+export type WarehouseEntity = Entity &
+    StorageCapability &
+    Partial<LoaderCapability> &
+    MassCapability &
+    ScheduleCapability
 
 export type ContainerEntity = Entity & StorageCapability & MassCapability & ScheduleCapability