@shipload/sdk 1.0.0-next.3 → 1.0.0-next.30

package/src/testing/projection-parity.ts

@@ -0,0 +1,143 @@
+import type {UInt16, UInt32} from '@wharfkit/antelope'
+import type {ServerContract} from '../contracts'
+import type {ProjectedEntity} from '../scheduling/projection'
+import {type CargoStack, cargoItemToStack, mergeStacks} from '../capabilities/storage'
+
+export interface ContractProjectedState {
+    owner: {toString(): string}
+    coordinates: ServerContract.Types.coordinates
+    energy?: UInt16
+    cargomass: UInt32
+    cargo: ServerContract.Types.cargo_view[]
+    hullmass?: UInt32
+    capacity?: UInt32
+    engines?: ServerContract.Types.movement_stats
+    loaders?: ServerContract.Types.loader_stats
+    generator?: ServerContract.Types.energy_stats
+    hauler?: ServerContract.Types.hauler_stats
+}
+
+export interface ProjectionComparisonOptions {
+    step?: number
+}
+
+export function assertProjectionEquals(
+    contract: ContractProjectedState,
+    sdk: ProjectedEntity,
+    options: ProjectionComparisonOptions = {}
+): void {
+    const mismatches: string[] = []
+
+    const record = (name: string, c: unknown, s: unknown) => {
+        if (c !== s) mismatches.push(`  ${name}: contract=${fmt(c)} sdk=${fmt(s)}`)
+    }
+
+    const recordStatBlock = (name: string, c: unknown, s: unknown) => {
+        const cPresent = c !== undefined && c !== null
+        const sPresent = s !== undefined && s !== null
+        if (cPresent !== sPresent) {
+            mismatches.push(
+                `  ${name}: contract=${cPresent ? 'present' : 'absent'} sdk=${sPresent ? 'present' : 'absent'}`
+            )
+            return
+        }
+        if (!cPresent) return
+        const cn = JSON.stringify(normaliseStatBlock(c))
+        const sn = JSON.stringify(normaliseStatBlock(s))
+        if (cn !== sn) mismatches.push(`  ${name}: contract=${cn} sdk=${sn}`)
+    }
+
+    record('coordinates.x', toNum(contract.coordinates.x), Number(sdk.location.x))
+    record('coordinates.y', toNum(contract.coordinates.y), Number(sdk.location.y))
+    record('energy', toNum(contract.energy), Number(sdk.energy))
+    record('cargomass', toNum(contract.cargomass), Number(sdk.cargoMass))
+    record('hullmass', toNum(contract.hullmass), Number(sdk.shipMass))
+    record('capacity', toNum(contract.capacity), sdk.capacity ? Number(sdk.capacity) : undefined)
+
+    recordStatBlock('engines', contract.engines, sdk.engines)
+    recordStatBlock('loaders', contract.loaders, sdk.loaders)
+    recordStatBlock('generator', contract.generator, sdk.generator)
+    recordStatBlock('hauler', contract.hauler, sdk.hauler)
+
+    if (contract.cargo.length > 0 || sdk.cargo.length > 0) {
+        const contractCargo = normaliseCargo(mergeContractCargo(contract.cargo))
+        const sdkCargo = normaliseCargo(sdk.cargo)
+        if (contractCargo.length !== sdkCargo.length) {
+            mismatches.push(
+                `  cargo.length: contract=${contractCargo.length} sdk=${sdkCargo.length}`
+            )
+        } else {
+            for (let i = 0; i < contractCargo.length; i++) {
+                const c = contractCargo[i]
+                const s = sdkCargo[i]
+                if (c.itemId !== s.itemId || c.stats !== s.stats || c.quantity !== s.quantity) {
+                    mismatches.push(
+                        `  cargo[${i}]: contract={item:${c.itemId},stats:${c.stats},qty:${c.quantity}} sdk={item:${s.itemId},stats:${s.stats},qty:${s.quantity}}`
+                    )
+                }
+            }
+        }
+    }
+
+    if (mismatches.length > 0) {
+        const header =
+            options.step !== undefined
+                ? `projection divergence at step ${options.step}:`
+                : 'projection divergence:'
+        throw new Error([header, ...mismatches].join('\n'))
+    }
+}
+
+interface NormalisedStack {
+    itemId: number
+    stats: string
+    quantity: string
+}
+
+function mergeContractCargo(cargo: ServerContract.Types.cargo_view[]): CargoStack[] {
+    return cargo.reduce<CargoStack[]>(
+        (acc, row) =>
+            mergeStacks(acc, cargoItemToStack(row as unknown as ServerContract.Types.cargo_item)),
+        []
+    )
+}
+
+function normaliseCargo(cargo: CargoStack[]): NormalisedStack[] {
+    return cargo
+        .map((s) => ({
+            itemId: Number(s.item_id),
+            stats: BigInt(s.stats.toString()).toString(),
+            quantity: BigInt(s.quantity.toString()).toString(),
+        }))
+        .sort(stackSort)
+}
+
+function stackSort(a: NormalisedStack, b: NormalisedStack): number {
+    if (a.itemId !== b.itemId) return a.itemId - b.itemId
+    return a.stats < b.stats ? -1 : a.stats > b.stats ? 1 : 0
+}
+
+function toNum(v: unknown): number | undefined {
+    if (v === undefined || v === null) return undefined
+    if (typeof v === 'number') return v
+    if (typeof v === 'bigint') return Number(v)
+    if (typeof (v as {toNumber?: unknown}).toNumber === 'function') {
+        return (v as {toNumber(): number}).toNumber()
+    }
+    return Number(v as number)
+}
+
+function fmt(v: unknown): string {
+    if (v === undefined) return 'undefined'
+    if (v === null) return 'null'
+    return String(v)
+}
+
+function normaliseStatBlock(block: unknown): Record<string, number> {
+    const out: Record<string, number> = {}
+    const obj = block as Record<string, unknown>
+    for (const k of Object.keys(obj).sort()) {
+        out[k] = toNum(obj[k]) ?? 0
+    }
+    return out
+}

package/src/travel/travel.ts

@@ -28,12 +28,17 @@ import {
     type Distance,
     MAX_ORBITAL_ALTITUDE,
     MIN_ORBITAL_ALTITUDE,
+    MIN_TRANSFER_DISTANCE_ORBITAL_VESSEL,
+    MIN_TRANSFER_DISTANCE_PLANETARY_STRUCTURE,
     PRECISION,
     type ShipLike,
     TaskType,
 } from '../types'
+import {EntityClass} from '../data/kind-registry'
 import {getItem} from '../data/catalog'
 import {hasSystem} from '../utils/system'
+import * as scheduleModel from '../scheduling/schedule'
+import type {ScheduleData} from '../scheduling/schedule'
 
 export function calc_orbital_altitude(mass: number): number {
     if (mass <= BASE_ORBITAL_MASS) {
@@ -77,6 +82,60 @@ export function lerp(
     }
 }
 
+export interface FloatPosition {
+    x: number
+    y: number
+}
+
+export function easeFlightProgress(t: number): number {
+    if (t <= 0) return 0
+    if (t >= 1) return 1
+    return t < 0.5 ? 2 * t * t : 1 - 2 * (1 - t) * (1 - t)
+}
+
+export function flightSpeedFactor(t: number): number {
+    if (t <= 0 || t >= 1) return 0
+    return t < 0.5 ? 4 * t : 4 * (1 - t)
+}
+
+export function interpolateFlightPosition(
+    origin: {x: Int64Type | number; y: Int64Type | number},
+    destination: {x: Int64Type | number; y: Int64Type | number},
+    taskProgress: number,
+    options?: {easing?: 'physics' | 'linear'}
+): FloatPosition {
+    const t = options?.easing === 'linear' ? taskProgress : easeFlightProgress(taskProgress)
+    return {
+        x: (1 - t) * Number(origin.x) + t * Number(destination.x),
+        y: (1 - t) * Number(origin.y) + t * Number(destination.y),
+    }
+}
+
+export function getInterpolatedPosition(
+    entity: HasScheduleAndLocation,
+    taskIndex: number,
+    taskProgress: number
+): FloatPosition {
+    const tasks = mobilityTasks(entity)
+    if (tasks.length === 0) {
+        return {x: Number(entity.coordinates.x), y: Number(entity.coordinates.y)}
+    }
+    if (taskIndex < 0) {
+        const settled = getFlightOrigin(entity, tasks.length)
+        return {x: Number(settled.x), y: Number(settled.y)}
+    }
+    const task = tasks[taskIndex]
+    if (!task.type.equals(TaskType.TRAVEL) || !task.coordinates) {
+        const origin = getFlightOrigin(entity, taskIndex)
+        return {x: Number(origin.x), y: Number(origin.y)}
+    }
+    return interpolateFlightPosition(
+        getFlightOrigin(entity, taskIndex),
+        task.coordinates,
+        taskProgress
+    )
+}
+
 export function rotation(
     origin: ServerContract.ActionParams.Type.coordinates,
     destination: ServerContract.ActionParams.Type.coordinates
@@ -366,6 +425,7 @@ export function hasEnergyForDistance(ship: ShipLike, distance: UInt64Type): bool
 
 export interface TransferEntity {
     location: {z?: {toNumber(): number} | number}
+    entityClass: EntityClass
     loaders?: {
         thrust: {toNumber(): number} | number
         mass: {toNumber(): number} | number
@@ -373,20 +433,22 @@ export interface TransferEntity {
     }
 }
 
-export interface HasScheduleAndLocation {
+export interface HasScheduleAndLocation extends ScheduleData {
     coordinates: ServerContract.ActionParams.Type.coordinates
-    schedule?: ServerContract.Types.schedule
+}
+
+function mobilityTasks(entity: HasScheduleAndLocation): ServerContract.Types.task[] {
+    return scheduleModel.mobilityLane(entity)?.schedule.tasks ?? []
 }
 
 export function getFlightOrigin(
     entity: HasScheduleAndLocation,
     flightTaskIndex: number
 ): ServerContract.ActionParams.Type.coordinates {
-    if (!entity.schedule) return entity.coordinates
-
+    const tasks = mobilityTasks(entity)
     let origin = entity.coordinates
-    for (let i = 0; i < flightTaskIndex && i < entity.schedule.tasks.length; i++) {
-        const task = entity.schedule.tasks[i]
+    for (let i = 0; i < flightTaskIndex && i < tasks.length; i++) {
+        const task = tasks[i]
         if (task.type.equals(TaskType.TRAVEL) && task.coordinates) {
             origin = task.coordinates
         }
@@ -397,10 +459,9 @@ export function getFlightOrigin(
 export function getDestinationLocation(
     entity: HasScheduleAndLocation
 ): ServerContract.ActionParams.Type.coordinates | undefined {
-    if (!entity.schedule) return undefined
-
-    for (let i = entity.schedule.tasks.length - 1; i >= 0; i--) {
-        const task = entity.schedule.tasks[i]
+    const tasks = mobilityTasks(entity)
+    for (let i = tasks.length - 1; i >= 0; i--) {
+        const task = tasks[i]
         if (task.type.equals(TaskType.TRAVEL) && task.coordinates) {
             return task.coordinates
         }
@@ -408,16 +469,21 @@ export function getDestinationLocation(
     return undefined
 }
 
+/** Returns chain-tile coordinates (rounded). For visual position use getInterpolatedPosition. */
 export function getPositionAt(
     entity: HasScheduleAndLocation,
     taskIndex: number,
     taskProgress: number
 ): ServerContract.ActionParams.Type.coordinates {
-    if (!entity.schedule || entity.schedule.tasks.length === 0 || taskIndex < 0) {
+    const tasks = mobilityTasks(entity)
+    if (tasks.length === 0) {
         return entity.coordinates
     }
+    if (taskIndex < 0) {
+        return getFlightOrigin(entity, tasks.length)
+    }
 
-    const task = entity.schedule.tasks[taskIndex]
+    const task = tasks[taskIndex]
 
     if (!task.type.equals(TaskType.TRAVEL) || !task.coordinates) {
         return getFlightOrigin(entity, taskIndex)
@@ -433,6 +499,12 @@ export function getPositionAt(
     }
 }
 
+export function minTransferDistance(entityClass: EntityClass): number {
+    return entityClass === EntityClass.OrbitalVessel
+        ? MIN_TRANSFER_DISTANCE_ORBITAL_VESSEL
+        : MIN_TRANSFER_DISTANCE_PLANETARY_STRUCTURE
+}
+
 export function calc_transfer_duration(
     source: TransferEntity,
     dest: TransferEntity,
@@ -490,7 +562,12 @@ export function calc_transfer_duration(
             : (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 rawDistance = Math.abs(sourceZ - destZ)
+    const minDistance = Math.max(
+        minTransferDistance(source.entityClass),
+        minTransferDistance(dest.entityClass)
+    )
+    const distance = rawDistance < minDistance ? minDistance : rawDistance
 
     const totalMass = cargoMass + totalLoaderMass
     const acceleration = calc_acceleration(totalThrust, totalMass)

package/src/types/capabilities.ts

@@ -29,6 +29,7 @@ export interface MassCapability {
 }
 
 export interface ScheduleCapability {
+    lanes?: ServerContract.Types.lane[]
     schedule?: ServerContract.Types.schedule
 }
 

package/src/types/index.ts

@@ -1,3 +1,2 @@
 export * from './capabilities'
 export * from './entity'
-export * from './entity-traits'

package/src/types.ts

@@ -1,6 +1,5 @@
 import {
     type Int64Type,
-    Name,
     type UInt16,
     type UInt16Type,
     type UInt32,
@@ -12,7 +11,7 @@ import {ServerContract} from './contracts'
 export const PRECISION = 10000
 export const CRAFT_ENERGY_DIVISOR = 150000
 
-export const WAREHOUSE_Z = 500
+export const PLANETARY_STRUCTURE_Z = 0
 
 export const CONTAINER_Z = 300
 
@@ -23,6 +22,9 @@ export const MAX_ORBITAL_ALTITUDE = 3000
 
 export const BASE_ORBITAL_MASS = 100000
 
+export const MIN_TRANSFER_DISTANCE_PLANETARY_STRUCTURE = 100
+export const MIN_TRANSFER_DISTANCE_ORBITAL_VESSEL = 300
+
 export interface ShipLike {
     coordinates: ServerContract.Types.coordinates
     hullmass?: UInt32
@@ -49,8 +51,12 @@ export enum TaskType {
     WARP = 6,
     CRAFT = 7,
     DEPLOY = 8,
-    WRAP = 9,
     UNWRAP = 10,
+    UNDEPLOY = 11,
+    DEMOLISH = 13,
+    CLAIMPLOT = 14,
+    BUILDPLOT = 15,
+    RESERVED = 16,
 }
 
 export enum LocationType {
@@ -58,6 +64,7 @@ export enum LocationType {
     PLANET = 1,
     ASTEROID = 2,
     NEBULA = 3,
+    ICE_FIELD = 4,
 }
 
 export enum TaskCancelable {
@@ -66,14 +73,6 @@ export enum TaskCancelable {
     ALWAYS = 2,
 }
 
-export const EntityType = {
-    SHIP: Name.from('ship'),
-    WAREHOUSE: Name.from('warehouse'),
-    CONTAINER: Name.from('container'),
-} as const
-
-export type EntityTypeName = (typeof EntityType)[keyof typeof EntityType]
-
 export type CoordinatesType =
     | Coordinates
     | ServerContract.Types.coordinates
@@ -122,8 +121,9 @@ export type ModuleType =
     | 'launcher'
     | 'storage'
     | 'hauler'
+    | 'battery'
 
-export const TIER_ADJECTIVES: Record<number, string> = {
+export const RESOURCE_TIER_ADJECTIVES: Record<number, string> = {
     1: 'Crude',
     2: 'Dense',
     3: 'Pure',
@@ -136,6 +136,9 @@ export const TIER_ADJECTIVES: Record<number, string> = {
     10: 'Ascendant',
 }
 
+export const COMPONENT_TIER_PREFIXES: Record<number, string> = {}
+export const MODULE_TIER_PREFIXES: Record<number, string> = {}
+
 export const CATEGORY_LABELS: Record<ResourceCategory, string> = {
     ore: 'Ore',
     crystal: 'Crystal',
@@ -159,3 +162,7 @@ export interface Item {
 export function formatTier(tier: number): string {
     return 'T' + tier
 }
+
+export function tierAdjective(tier: number): string {
+    return RESOURCE_TIER_ADJECTIVES[tier] ?? `T${tier}`
+}

package/src/utils/cargo.ts

@@ -0,0 +1,27 @@
+import type {ServerContract} from '../contracts'
+
+export function cargoRef(src: {
+    item_id: number
+    stats: bigint | number
+    modules?: ServerContract.Types.module_entry[]
+}): ServerContract.ActionParams.Type.cargo_ref {
+    return {
+        item_id: src.item_id,
+        stats: src.stats,
+        modules: src.modules ?? [],
+    }
+}
+
+export function cargoItem(
+    src: {
+        item_id: number
+        stats: bigint | number
+        modules?: ServerContract.Types.module_entry[]
+    },
+    quantity: bigint | number
+): ServerContract.ActionParams.Type.cargo_item {
+    return {
+        ...cargoRef(src),
+        quantity,
+    }
+}

package/src/utils/display-name.ts

@@ -0,0 +1,61 @@
+export interface DisplayNameResult {
+    valid: boolean
+    reason?: string
+    name: string
+}
+
+const MAX_DISPLAY_NAME_BYTES = 32
+const ASCII_SPACE = 0x20
+const ZERO_WIDTH_CODE_POINTS = new Set([0x200b, 0x200c, 0x200d, 0x2060, 0xfeff])
+const textEncoder = new TextEncoder()
+
+function isControlCharacter(codePoint: number): boolean {
+    return codePoint <= 0x1f || codePoint === 0x7f || (codePoint >= 0x80 && codePoint <= 0x9f)
+}
+
+function isLoneSurrogate(codePoint: number): boolean {
+    return codePoint >= 0xd800 && codePoint <= 0xdfff
+}
+
+function isBidiControl(codePoint: number): boolean {
+    return (
+        (codePoint >= 0x202a && codePoint <= 0x202e) || (codePoint >= 0x2066 && codePoint <= 0x2069)
+    )
+}
+
+function isInvalidDisplayNameCodePoint(codePoint: number): boolean {
+    return (
+        isControlCharacter(codePoint) ||
+        isLoneSurrogate(codePoint) ||
+        ZERO_WIDTH_CODE_POINTS.has(codePoint) ||
+        isBidiControl(codePoint)
+    )
+}
+
+export function normalizeDisplayName(input: string): string {
+    let start = 0
+    let end = input.length
+
+    while (start < end && input.charCodeAt(start) === ASCII_SPACE) start++
+    while (end > start && input.charCodeAt(end - 1) === ASCII_SPACE) end--
+
+    return input.slice(start, end)
+}
+
+export function validateDisplayName(input: string): DisplayNameResult {
+    const name = normalizeDisplayName(input)
+
+    if (name.length === 0) return {valid: false, reason: 'empty', name}
+    if (textEncoder.encode(name).length > MAX_DISPLAY_NAME_BYTES) {
+        return {valid: false, reason: 'too_long', name}
+    }
+
+    for (const character of name) {
+        const codePoint = character.codePointAt(0)!
+        if (isInvalidDisplayNameCodePoint(codePoint)) {
+            return {valid: false, reason: 'invalid_char', name}
+        }
+    }
+
+    return {valid: true, name}
+}

package/src/utils/system.ts

@@ -8,7 +8,6 @@ import nebulaAdjectives from '../data/nebula-adjectives.json'
 import nebulaNouns from '../data/nebula-nouns.json'
 
 const LOCATION_EXISTS_THRESHOLD = 0x10
-const LOCATION_ACTIVE_THRESHOLD = 0x80
 
 export function getLocationType(
     gameSeed: Checksum256Type,
@@ -22,12 +21,10 @@ export function getLocationType(
         return LocationType.EMPTY
     }
 
-    if (hashResult.array[1] < 96) {
-        return LocationType.PLANET
-    } else if (hashResult.array[1] < 176) {
-        return LocationType.ASTEROID
-    }
-    return LocationType.NEBULA
+    if (hashResult.array[1] < 96) return LocationType.PLANET
+    if (hashResult.array[1] < 149) return LocationType.ASTEROID
+    if (hashResult.array[1] < 202) return LocationType.NEBULA
+    return LocationType.ICE_FIELD
 }
 
 export function isGatherableLocation(locationType: LocationType): boolean {
@@ -44,6 +41,8 @@ export function getLocationTypeName(type: LocationType): string {
             return 'Asteroid'
         case LocationType.NEBULA:
             return 'Nebula'
+        case LocationType.ICE_FIELD:
+            return 'Ice Field'
     }
 }
 
@@ -76,6 +75,15 @@ function generateNebulaName(hashResult: Checksum512): string {
     return `${nebulaAdjectives[adjIdx]} ${nebulaNouns[nounIdx]}`
 }
 
+function generateIceFieldName(hashResult: Checksum512): string {
+    const A = 65
+    const letter1 = String.fromCharCode(A + (hashResult.array[0] % 26))
+    const letter2 = String.fromCharCode(A + (hashResult.array[1] % 26))
+    const subId = (hashResult.array[2] % 9) + 1
+    const num = (uint16(hashResult, 3) % 9000) + 1000
+    return `${letter1}${letter2}-${subId}/${num}`
+}
+
 export function getSystemName(gameSeed: Checksum256Type, location: CoordinatesType): string {
     const seed = Checksum256.from(gameSeed)
     const locationType = getLocationType(seed, location)
@@ -91,6 +99,8 @@ export function getSystemName(gameSeed: Checksum256Type, location: CoordinatesTy
             return generateAsteroidName(hashResult)
         case LocationType.NEBULA:
             return generateNebulaName(hashResult)
+        case LocationType.ICE_FIELD:
+            return generateIceFieldName(hashResult)
         default:
             return generatePlanetName(hashResult)
     }
@@ -123,10 +133,12 @@ export function deriveLocationStatic(
 
     if (hashResult.array[1] < 96) {
         loc.type = UInt8.from(LocationType.PLANET)
-    } else if (hashResult.array[1] < 176) {
+    } else if (hashResult.array[1] < 149) {
         loc.type = UInt8.from(LocationType.ASTEROID)
-    } else {
+    } else if (hashResult.array[1] < 202) {
         loc.type = UInt8.from(LocationType.NEBULA)
+    } else {
+        loc.type = UInt8.from(LocationType.ICE_FIELD)
     }
 
     loc.subtype = UInt8.from(
@@ -138,31 +150,20 @@ export function deriveLocationStatic(
     return loc
 }
 
-export function deriveLocationEpoch(
-    epochSeed: Checksum256Type,
+export function isLocationBuildable(
+    gameSeed: Checksum256Type,
     coordinates: CoordinatesType
-): ServerContract.Types.location_epoch {
-    const seed = Checksum256.from(epochSeed)
-    const coords = Coordinates.from(coordinates)
-    const str = `system-epoch-${coords.x}-${coords.y}`
-    const hashResult = hash512(seed, str)
-
-    return ServerContract.Types.location_epoch.from({
-        active: hashResult.array[0] < LOCATION_ACTIVE_THRESHOLD,
-        seed0: hashResult.array[1],
-        seed1: hashResult.array[2],
-    })
+): boolean {
+    return getLocationType(gameSeed, coordinates) === LocationType.PLANET
 }
 
 export function deriveLocation(
     gameSeed: Checksum256Type,
-    epochSeed: Checksum256Type,
     coordinates: CoordinatesType
 ): ServerContract.Types.location_derived {
     const staticProps = deriveLocationStatic(gameSeed, coordinates)
     return ServerContract.Types.location_derived.from({
         static_props: staticProps,
-        epoch_props: deriveLocationEpoch(epochSeed, coordinates),
         size: deriveLocationSize(staticProps),
     })
 }

package/src/capabilities/loading.ts

@@ -1,8 +0,0 @@
-import {UInt32, type UInt64} from '@wharfkit/antelope'
-import type {LoaderCapability} from '../types/capabilities'
-
-export function calcLoadDuration(entity: LoaderCapability, cargoMass: UInt64): UInt32 {
-    const totalThrust = entity.loaders.thrust.toNumber() * entity.loaders.quantity.toNumber()
-    if (totalThrust === 0) return UInt32.from(0)
-    return UInt32.from(Math.ceil(Number(cargoMass) / totalThrust))
-}