@shipload/sdk 0.7.1 → 2.0.0-rc1

package/src/travel/travel.ts

@@ -0,0 +1,425 @@
+/**
+ * Travel calculations for ship movement, energy usage, and flight times.
+ *
+ * Functions prefixed with `calc_` are contract-parity functions that mirror
+ * the C++ implementation in the server contract (schedule.cpp, ship.cpp).
+ * These use snake_case intentionally to match the contract naming convention
+ * and signal that they must produce identical results to the on-chain code.
+ *
+ * Functions prefixed with `calculate` are higher-level SDK helpers that may
+ * combine multiple contract calculations for convenience.
+ */
+
+import {
+    Checksum256,
+    Int64,
+    Int64Type,
+    UInt32,
+    UInt32Type,
+    UInt64,
+    UInt64Type,
+} from '@wharfkit/antelope'
+
+import {ServerContract} from '../contracts'
+import {
+    CargoMassInfo,
+    Distance,
+    INITIAL_SHIP_MASS,
+    MAX_ORBITAL_ALTITUDE,
+    MIN_ORBITAL_ALTITUDE,
+    PRECISION,
+    ShipLike,
+} from '../types'
+import {getGood} from '../market/goods'
+import {hasSystem} from '../utils/system'
+
+export function calc_orbital_altitude(mass: number): number {
+    if (mass <= INITIAL_SHIP_MASS) {
+        return MIN_ORBITAL_ALTITUDE
+    }
+
+    const ratio = mass / INITIAL_SHIP_MASS
+    const capRatio = 10.0
+    let scale = Math.log(ratio) / Math.log(capRatio)
+    scale = Math.min(scale, 1.0)
+
+    return MIN_ORBITAL_ALTITUDE + Math.floor((MAX_ORBITAL_ALTITUDE - MIN_ORBITAL_ALTITUDE) * scale)
+}
+
+export function distanceBetweenCoordinates(
+    origin: ServerContract.ActionParams.Type.coordinates,
+    destination: ServerContract.ActionParams.Type.coordinates
+): UInt64 {
+    return distanceBetweenPoints(origin.x, origin.y, destination.x, destination.y)
+}
+
+export function distanceBetweenPoints(
+    x1: Int64Type,
+    y1: Int64Type,
+    x2: Int64Type,
+    y2: Int64Type
+): UInt64 {
+    const x = Math.pow(x1 - x2, 2)
+    const y = Math.pow(y1 - y2, 2)
+    return UInt64.from(Math.sqrt(x + y) * PRECISION)
+}
+
+export function lerp(
+    origin: ServerContract.ActionParams.Type.coordinates,
+    destination: ServerContract.ActionParams.Type.coordinates,
+    time: number
+): ServerContract.ActionParams.Type.coordinates {
+    return {
+        x: (1 - time) * Number(origin.x) + time * Number(destination.x),
+        y: (1 - time) * Number(origin.y) + time * Number(destination.y),
+    }
+}
+
+export function rotation(
+    origin: ServerContract.ActionParams.Type.coordinates,
+    destination: ServerContract.ActionParams.Type.coordinates
+) {
+    return Math.atan2(destination.y - origin.y, destination.x - origin.x) * (180 / Math.PI) + 90
+}
+
+export function findNearbyPlanets(
+    seed: Checksum256,
+    origin: ServerContract.ActionParams.Type.coordinates,
+    maxDistance: UInt64Type = 20 * PRECISION
+): Distance[] {
+    const nearbySystems: Distance[] = []
+
+    const max = UInt64.from(maxDistance / PRECISION)
+    const xMin = Int64.from(origin.x).subtracting(max)
+    const xMax = Int64.from(origin.x).adding(max)
+    const yMin = Int64.from(origin.y).subtracting(max)
+    const yMax = Int64.from(origin.y).adding(max)
+
+    for (let x = Number(xMin); x <= Number(xMax); x++) {
+        for (let y = Number(yMin); y <= Number(yMax); y++) {
+            const samePlace = x === Number(origin.x) && y === Number(origin.y)
+            if (!samePlace) {
+                const distance = distanceBetweenPoints(origin.x, origin.y, x, y)
+                if (Number(distance) <= Number(maxDistance)) {
+                    const system = hasSystem(seed, {x, y})
+                    if (system) {
+                        nearbySystems.push({origin, destination: {x, y}, distance})
+                    }
+                }
+            }
+        }
+    }
+
+    return nearbySystems
+}
+
+export function calc_rechargetime(
+    capacity: UInt32Type,
+    energy: UInt32Type,
+    recharge: UInt32Type
+): UInt32 {
+    const cap = UInt32.from(capacity)
+    const eng = UInt32.from(energy)
+    if (eng.gte(cap)) return UInt32.zero
+    return cap.subtracting(eng).dividing(recharge)
+}
+
+export function calc_ship_rechargetime(ship: ShipLike): UInt32 {
+    return calc_rechargetime(ship.generator.capacity, ship.energy, ship.generator.recharge)
+}
+
+export function calc_flighttime(distance: UInt64Type, acceleration: number): UInt32 {
+    return UInt32.from(2 * Math.sqrt(Number(distance) / acceleration))
+}
+
+export function calc_loader_flighttime(ship: ShipLike, mass: UInt64, altitude?: number): UInt32 {
+    const z = altitude ?? ship.location.z?.toNumber() ?? calc_orbital_altitude(Number(mass))
+    return calc_flighttime(z, calc_loader_acceleration(ship, mass))
+}
+
+export function calc_loader_acceleration(ship: ShipLike, mass: UInt64): number {
+    return calc_acceleration(Number(ship.loaders.thrust), Number(mass) + Number(ship.loaders.mass))
+}
+
+export function calc_ship_flighttime(ship: ShipLike, mass: UInt64, distance: UInt64): UInt32 {
+    const acceleration = calc_ship_acceleration(ship, mass)
+    return calc_flighttime(distance, acceleration)
+}
+
+export function calc_ship_acceleration(ship: ShipLike, mass: UInt64): number {
+    return calc_acceleration(Number(ship.engines.thrust), Number(mass))
+}
+
+export function calc_acceleration(thrust: number, mass: number): number {
+    return (thrust / mass) * PRECISION
+}
+
+export function calc_ship_mass(ship: ShipLike, cargos: CargoMassInfo[]): UInt64 {
+    const mass = UInt64.from(0)
+
+    mass.add(ship.mass)
+
+    if (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))
+    }
+
+    return mass
+}
+
+export function calc_energyusage(distance: UInt64Type, drain: UInt32Type): UInt32 {
+    return UInt64.from(distance).dividing(PRECISION).multiplying(drain)
+}
+
+export function calculateTransferTime(
+    ship: ShipLike,
+    cargos: CargoMassInfo[],
+    quantities?: Map<number, number>
+): UInt32 {
+    let mass = UInt64.from(0)
+
+    for (const cargo of cargos) {
+        const qty = quantities?.get(Number(cargo.good_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)
+        }
+    }
+
+    if (mass.equals(UInt64.zero)) {
+        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)
+}
+
+export function calculateRefuelingTime(ship: ShipLike): UInt32 {
+    return calc_ship_rechargetime(ship)
+}
+
+export function calculateFlightTime(
+    ship: ShipLike,
+    cargos: CargoMassInfo[],
+    distance: UInt64Type
+): UInt32 {
+    const mass = calc_ship_mass(ship, cargos)
+    return calc_ship_flighttime(ship, mass, distance)
+}
+
+export interface LoadTimeBreakdown {
+    unloadTime: number
+    loadTime: number
+    totalTime: number
+    unloadMass: number
+    loadMass: number
+}
+
+export function calculateLoadTimeBreakdown(
+    ship: ShipLike,
+    cargos: CargoMassInfo[],
+    loadQuantities?: Map<number, number>,
+    unloadQuantities?: Map<number, number>
+): LoadTimeBreakdown {
+    let mass_unload = UInt64.from(0)
+    let mass_load = UInt64.from(0)
+
+    for (const cargo of cargos) {
+        const goodId = Number(cargo.good_id)
+        const loadQty = loadQuantities?.get(goodId) ?? 0
+        const unloadQty = unloadQuantities?.get(goodId) ?? 0
+
+        if (loadQty > 0 || unloadQty > 0) {
+            const good = getGood(cargo.good_id)
+
+            if (loadQty > 0) {
+                const cargo_mass = good.mass.multiplying(loadQty)
+                mass_load = UInt64.from(mass_load).adding(cargo_mass)
+            }
+            if (unloadQty > 0) {
+                const cargo_mass = good.mass.multiplying(unloadQty)
+                mass_unload = UInt64.from(mass_unload).adding(cargo_mass)
+            }
+        }
+    }
+
+    let unloadTime = 0
+    let loadTime = 0
+
+    if (mass_unload.gt(UInt64.zero)) {
+        const totalMass = UInt64.from(mass_unload).adding(ship.loaders.mass)
+        unloadTime = Number(calc_loader_flighttime(ship, totalMass))
+    }
+
+    if (mass_load.gt(UInt64.zero)) {
+        const totalMass = UInt64.from(mass_load).adding(ship.loaders.mass)
+        loadTime = Number(calc_loader_flighttime(ship, totalMass))
+    }
+
+    const numLoaders = Number(ship.loaders.quantity)
+    const totalTime = numLoaders > 0 ? (unloadTime + loadTime) / numLoaders : 0
+    const unloadTimePerLoader = numLoaders > 0 ? unloadTime / numLoaders : 0
+    const loadTimePerLoader = numLoaders > 0 ? loadTime / numLoaders : 0
+
+    return {
+        unloadTime: unloadTimePerLoader,
+        loadTime: loadTimePerLoader,
+        totalTime,
+        unloadMass: Number(mass_unload),
+        loadMass: Number(mass_load),
+    }
+}
+
+export interface EstimatedTravelTime {
+    flightTime: UInt32
+    rechargeTime: UInt32
+    loadTime: UInt32
+    unloadTime: UInt32
+    total: UInt32
+}
+
+export interface EstimateTravelTimeOptions {
+    needsRecharge?: boolean
+    loadMass?: UInt32Type
+    unloadMass?: UInt32Type
+}
+
+export function estimateTravelTime(
+    ship: ShipLike,
+    travelMass: UInt64Type,
+    distance: UInt64Type,
+    options: EstimateTravelTimeOptions = {}
+): EstimatedTravelTime {
+    const {needsRecharge = false, loadMass, unloadMass} = options
+
+    const flightTime = calc_ship_flighttime(ship, UInt64.from(travelMass), UInt64.from(distance))
+    const rechargeTime = needsRecharge ? calc_ship_rechargetime(ship) : UInt32.zero
+
+    let loadTime = UInt32.zero
+    let unloadTime = UInt32.zero
+
+    if (
+        loadMass &&
+        UInt32.from(loadMass).gt(UInt32.zero) &&
+        ship.loaders.quantity.gt(UInt32.zero)
+    ) {
+        const totalMass = UInt64.from(loadMass).adding(ship.loaders.mass)
+        loadTime = calc_loader_flighttime(ship, totalMass).dividing(ship.loaders.quantity)
+    }
+
+    if (
+        unloadMass &&
+        UInt32.from(unloadMass).gt(UInt32.zero) &&
+        ship.loaders.quantity.gt(UInt32.zero)
+    ) {
+        const totalMass = UInt64.from(unloadMass).adding(ship.loaders.mass)
+        unloadTime = calc_loader_flighttime(ship, totalMass).dividing(ship.loaders.quantity)
+    }
+
+    return {
+        flightTime,
+        rechargeTime,
+        loadTime,
+        unloadTime,
+        total: flightTime.adding(rechargeTime).adding(loadTime).adding(unloadTime),
+    }
+}
+
+export function estimateDealTravelTime(
+    ship: ShipLike,
+    shipMass: UInt64Type,
+    distance: UInt64Type,
+    loadMass: UInt32Type
+): UInt32 {
+    const needsRecharge = !hasEnergyForDistance(ship, distance)
+    const estimate = estimateTravelTime(ship, shipMass, distance, {
+        needsRecharge,
+        loadMass,
+    })
+    return estimate.total
+}
+
+export function hasEnergyForDistance(ship: ShipLike, distance: UInt64Type): boolean {
+    const energyNeeded = UInt64.from(distance).dividing(PRECISION).multiplying(ship.engines.drain)
+    return UInt64.from(ship.energy).gte(energyNeeded)
+}
+
+export interface TransferEntity {
+    location: {z?: {toNumber(): number} | number}
+    loaders?: {
+        thrust: {toNumber(): number} | number
+        mass: {toNumber(): number} | number
+        quantity: {toNumber(): number} | number
+    }
+}
+
+export function calc_transfer_duration(
+    source: TransferEntity,
+    dest: TransferEntity,
+    cargoMass: number
+): number {
+    if (cargoMass === 0) {
+        return 0
+    }
+
+    let totalThrust = 0
+    let totalLoaderMass = 0
+    let totalQuantity = 0
+
+    if (source.loaders) {
+        const thrust =
+            typeof source.loaders.thrust === 'number'
+                ? source.loaders.thrust
+                : source.loaders.thrust.toNumber()
+        const mass =
+            typeof source.loaders.mass === 'number'
+                ? source.loaders.mass
+                : source.loaders.mass.toNumber()
+        const qty =
+            typeof source.loaders.quantity === 'number'
+                ? source.loaders.quantity
+                : source.loaders.quantity.toNumber()
+        totalThrust += thrust * qty
+        totalLoaderMass += mass * qty
+        totalQuantity += qty
+    }
+
+    if (dest.loaders) {
+        const thrust =
+            typeof dest.loaders.thrust === 'number'
+                ? dest.loaders.thrust
+                : dest.loaders.thrust.toNumber()
+        const mass =
+            typeof dest.loaders.mass === 'number' ? dest.loaders.mass : dest.loaders.mass.toNumber()
+        const qty =
+            typeof dest.loaders.quantity === 'number'
+                ? dest.loaders.quantity
+                : dest.loaders.quantity.toNumber()
+        totalThrust += thrust * qty
+        totalLoaderMass += mass * qty
+        totalQuantity += qty
+    }
+
+    if (totalThrust === 0 || totalQuantity === 0) {
+        return 0
+    }
+
+    const sourceZ =
+        typeof source.location.z === 'number'
+            ? source.location.z
+            : source.location.z?.toNumber() ?? 0
+    const destZ =
+        typeof dest.location.z === 'number' ? dest.location.z : dest.location.z?.toNumber() ?? 0
+    const distance = Math.abs(sourceZ - destZ)
+
+    const totalMass = cargoMass + totalLoaderMass
+    const acceleration = calc_acceleration(totalThrust, totalMass)
+    const flightTime = 2 * Math.sqrt(distance / acceleration)
+
+    return Math.floor(flightTime / totalQuantity)
+}

package/src/types.ts

@@ -1,16 +1,61 @@
-import {Struct, UInt16, UInt16Type, UInt64, UInt64Type} from '@wharfkit/antelope'
+import {Int64Type, Name, Struct, UInt16, UInt16Type, UInt32, UInt32Type} from '@wharfkit/antelope'
 import {ServerContract} from './contracts'
 
 export const PRECISION = 10000
-export const TRAVEL_MAXMASS_PENALTY = 5 // Penalty (in seconds) for exceeding the maximum mass per 1000 unit
 
-export interface CameraPosition extends ServerContract.ActionParams.Type.coordinates {
-    z: number
+export const INITIAL_SHIP_MASS = 500000
+export const MIN_ORBITAL_ALTITUDE = 800
+export const MAX_ORBITAL_ALTITUDE = 3000
+
+export interface ShipLike {
+    location: ServerContract.Types.coordinates
+    mass: UInt32
+    energy: UInt16
+    engines: ServerContract.Types.movement_stats
+    generator: ServerContract.Types.energy_stats
+    loaders: ServerContract.Types.loader_stats
+    capacity: UInt32
+}
+
+export interface CargoMassInfo {
+    good_id: UInt16Type
+    quantity: UInt32Type
+}
+
+export enum TaskType {
+    RECHARGE = 0,
+    LOAD = 1,
+    UNLOAD = 2,
+    FLIGHT = 3,
 }
 
-export interface Dimensions {
-    width: number
-    height: number
+export enum TaskCancelable {
+    NEVER = 0, // Task cannot be cancelled
+    BEFORE_START = 1, // Task can only be cancelled before it starts
+    ALWAYS = 2, // Task can always be cancelled
+}
+
+export const EntityType = {
+    SHIP: Name.from('ship'),
+    WAREHOUSE: Name.from('warehouse'),
+} as const
+
+export type EntityTypeName = (typeof EntityType)[keyof typeof EntityType]
+
+export type CoordinatesType =
+    | Coordinates
+    | ServerContract.Types.coordinates
+    | {x: Int64Type; y: Int64Type}
+
+export class Coordinates extends ServerContract.Types.coordinates {
+    static from(value: CoordinatesType): Coordinates {
+        return super.from(value) as Coordinates
+    }
+
+    equals(other: CoordinatesType): boolean {
+        const coords = Coordinates.from(other)
+        return this.x.equals(coords.x) && this.y.equals(coords.y)
+    }
 }
 
 export interface Distance {
@@ -27,18 +72,10 @@ export class Good extends Struct {
     name!: string
     @Struct.field('string')
     description!: string
-    @Struct.field(UInt64)
-    base_price!: UInt64
-    @Struct.field(UInt64)
-    mass!: UInt64
-}
-
-export interface GoodType {
-    id: UInt16Type
-    name: string
-    description: string
-    base_price: UInt64Type
-    mass: UInt64Type
+    @Struct.field(UInt32)
+    base_price!: UInt32
+    @Struct.field(UInt32)
+    mass!: UInt32
 }
 
 @Struct.type('GoodPrice')
@@ -47,10 +84,8 @@ export class GoodPrice extends Struct {
     id!: UInt16
     @Struct.field(Good)
     good!: Good
-    @Struct.field(UInt64)
-    price!: UInt64
-    @Struct.field(UInt64)
-    supply!: UInt64
+    @Struct.field(UInt32)
+    price!: UInt32
+    @Struct.field(UInt16)
+    supply!: UInt16
 }
-
-export interface Coordinates extends ServerContract.ActionParams.Type.coordinates {}

package/src/utils/system.ts

@@ -0,0 +1,27 @@
+import {Checksum256, Checksum256Type} from '@wharfkit/antelope'
+import {hash512} from './hash'
+import {CoordinatesType} from '../types'
+import syllables from '../data/syllables.json'
+
+export function getSystemName(gameSeed: Checksum256Type, location: CoordinatesType): string {
+    const seed = Checksum256.from(gameSeed)
+    if (!hasSystem(seed, location)) {
+        throw new Error("System doesn't exist at location")
+    }
+    const seedStr = `${location.x}${location.y}systemName`
+    const hashResult = hash512(seed, seedStr)
+    const syllableCount = 1 + (hashResult.array[0] % 3)
+    const name: string[] = []
+    for (let i = 0; i < syllableCount; i++) {
+        const index = hashResult.array[i] % syllables.length
+        const syllable = syllables[index]
+        name.push(i > 0 ? syllable.toLowerCase() : syllable)
+    }
+    return name.join('')
+}
+
+export function hasSystem(gameSeed: Checksum256Type, coordinates: CoordinatesType): boolean {
+    const seed = Checksum256.from(gameSeed)
+    const str = ['system', coordinates.x, coordinates.y].join('-')
+    return String(hash512(seed, str)).slice(0, 2) === '00'
+}

package/src/goods.ts

@@ -1,124 +0,0 @@
-import {UInt16, UInt16Type, UInt64} from '@wharfkit/antelope'
-import {Coordinates, Good, GoodType, PRECISION} from './types'
-
-// List of goods with titles and descriptions
-const goods: GoodType[] = [
-    {
-        id: 1,
-        name: 'FizzGlo',
-        description: 'Pops with flavor! A neon drink that makes your burps glow.',
-        base_price: 50,
-        mass: 35_000,
-    },
-    // {
-    //     id: 2,
-    //     name: 'ZapSnacks',
-    //     description: 'Electric taste! Spicy edible energy sparks for a tongue-tingling experience.',
-    //     base_price: 0,
-    //     mass: 0,
-    // },
-    {
-        id: 3,
-        name: 'Blob Buddies',
-        description: 'Squishy friends! Clingy, cute and mood-matching pet blobs for every home!',
-        base_price: 95,
-        mass: 60_000,
-    },
-    {
-        id: 4,
-        name: 'TuneTooth',
-        description: 'Whistle while you eat! Edible instrument treats that play tunes when chewed.',
-        base_price: 145,
-        mass: 75_000,
-    },
-    {
-        id: 5,
-        name: 'SunPods',
-        description: 'Miniature suns in your pocket providing on-demand light & warmth.',
-        base_price: 295,
-        mass: 135_000,
-    },
-    // {
-    //     id: 6,
-    //     name: 'Fuzzix',
-    //     description: 'Pocket-sized quantum fluff generator for instant comfy.',
-    //     base_price: 0,
-    //     mass: 0,
-    // },
-    {
-        id: 7,
-        name: 'GlowGo',
-        description: 'Ingestible bioluminescent jelly, your inside glows in the dark!',
-        base_price: 650,
-        mass: 255_000,
-    },
-    // {
-    //     id: 8,
-    //     name: 'KrackleKaps',
-    //     description: 'Capsules packed with tiny firecrackers, spice up meals and parties.',
-    //     base_price: 0,
-    //     mass: 0,
-    // },
-    {
-        id: 9,
-        name: 'PlasmaMints',
-        description: 'Hypercharged candy giving plasma breath capable of cutting through steel.',
-        base_price: 3450,
-        mass: 1_100_000,
-    },
-    {
-        id: 10,
-        name: 'TimeTreats',
-        description: 'Confectionery morsels releasing slow-mo effect over a limited period.',
-        base_price: 8500,
-        mass: 2_100_000,
-    },
-    {
-        id: 11,
-        name: 'QuantumQuencher',
-        description:
-            'Bottled hyper-fluid quenching thirst across multiple parallel realities simultaneously.',
-        base_price: 20_500,
-        mass: 4_100_000,
-    },
-    // {
-    //     id: 12,
-    //     name: 'TransmatterTruffles',
-    //     description: 'Delectable chocolates instantly teleporting consumers short distances.',
-    //     base_price: 0,
-    //     mass: 0,
-    // },
-    {
-        id: 13,
-        name: 'MemoryGum',
-        description: 'Chewable gum storing or replaying memories while being chewed.',
-        base_price: 52_500,
-        mass: 9_500_000,
-    },
-    {
-        id: 14,
-        name: 'SymbioSnack',
-        description: 'Edible alien larvae adopting owner’s taste preference upon consumption.',
-        base_price: 115_000,
-        mass: 16_000_000,
-    },
-]
-
-export const goodIds = goods.map((g) => g.id)
-
-export function getGood(good_id: UInt16Type): Good {
-    const good = goods.find((g) => UInt16.from(good_id).equals(g.id))
-    if (!good) {
-        throw new Error('Good does not exist')
-    }
-    return Good.from({
-        ...good,
-        id: UInt16.from(good.id),
-        base_price: UInt64.from(good.base_price),
-        mass: UInt64.from(good.mass).multiplying(PRECISION),
-    })
-}
-
-export function getGoods(): Good[] {
-    return goods.map((g) => getGood(g.id))
-}