@shipload/sdk 1.0.0-next.34 → 1.0.0-next.35

package/src/coordinates/permutation.ts

@@ -0,0 +1,77 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {hash512} from '../utils/hash'
+
+// FROZEN INTERFACE — round count, key-derivation strings, and mixing constants must never change; per-game variation comes from the seed.
+const ROUNDS = 4
+
+export interface FeistelConfig {
+    n: number
+    halfBits: number
+    label: string
+}
+
+const keyCache = new Map<string, number[]>()
+
+function deriveRoundKeys(seed: Checksum256Type, label: string): number[] {
+    const cacheKey = `${seed}:${label}`
+    const cached = keyCache.get(cacheKey)
+    if (cached) return cached
+    const h = hash512(seed, `coord-keys-${label}`).array
+    const keys: number[] = []
+    for (let i = 0; i < ROUNDS; i++) {
+        const o = i * 4
+        keys.push(((h[o] << 24) | (h[o + 1] << 16) | (h[o + 2] << 8) | h[o + 3]) >>> 0)
+    }
+    keyCache.set(cacheKey, keys)
+    return keys
+}
+
+function roundFn(r: number, key: number, halfBits: number): number {
+    let x = (r ^ key) >>> 0
+    x = Math.imul(x ^ (x >>> 16), 0x9e3779b1) >>> 0
+    x = Math.imul(x ^ (x >>> 13), 0x7feb352d) >>> 0
+    x = (x ^ (x >>> 16)) >>> 0
+    return x & ((1 << halfBits) - 1)
+}
+
+function encryptBlock(x: number, halfBits: number, keys: number[]): number {
+    const mask = (1 << halfBits) - 1
+    let L = (x >>> halfBits) & mask
+    let R = x & mask
+    for (let i = 0; i < ROUNDS; i++) {
+        const F = roundFn(R, keys[i], halfBits)
+        const nL = R
+        const nR = (L ^ F) & mask
+        L = nL
+        R = nR
+    }
+    return ((L << halfBits) | R) >>> 0
+}
+
+function decryptBlock(y: number, halfBits: number, keys: number[]): number {
+    const mask = (1 << halfBits) - 1
+    let L = (y >>> halfBits) & mask
+    let R = y & mask
+    for (let i = ROUNDS - 1; i >= 0; i--) {
+        const F = roundFn(L, keys[i], halfBits)
+        const nR = L
+        const nL = (R ^ F) & mask
+        L = nL
+        R = nR
+    }
+    return ((L << halfBits) | R) >>> 0
+}
+
+export function permute(seed: Checksum256Type, x: number, cfg: FeistelConfig): number {
+    const keys = deriveRoundKeys(seed, cfg.label)
+    let v = encryptBlock(x, cfg.halfBits, keys)
+    while (v >= cfg.n) v = encryptBlock(v, cfg.halfBits, keys)
+    return v
+}
+
+export function unpermute(seed: Checksum256Type, y: number, cfg: FeistelConfig): number {
+    const keys = deriveRoundKeys(seed, cfg.label)
+    let v = decryptBlock(y, cfg.halfBits, keys)
+    while (v >= cfg.n) v = decryptBlock(v, cfg.halfBits, keys)
+    return v
+}

package/src/coordinates/regions.ts

@@ -0,0 +1,48 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {REGION_FEISTEL, REGION_PER_AXIS} from './constants'
+import {permute, unpermute} from './permutation'
+
+// FROZEN INTERFACE — phoneme tables; tune aesthetics before launch, then never reorder.
+const ONSETS = ['b', 'd', 'f', 'g', 'k', 'l', 'm', 'n', 'p', 'r', 's', 't'] // 12
+const VOWELS = ['a', 'e', 'i', 'o', 'u'] // 5
+const CODAS = ['n', 'r', 'l', 's', 'k', 'm', 't', 'x'] // 8
+const SYL_BASE = ONSETS.length * VOWELS.length * CODAS.length // 480
+
+function syllable(digit: number): string {
+    const onset = Math.floor(digit / (VOWELS.length * CODAS.length))
+    const rem = digit % (VOWELS.length * CODAS.length)
+    const vowel = Math.floor(rem / CODAS.length)
+    const coda = rem % CODAS.length
+    return ONSETS[onset] + VOWELS[vowel] + CODAS[coda]
+}
+
+function unsyllable(chunk: string): number {
+    const onset = ONSETS.indexOf(chunk[0])
+    const vowel = VOWELS.indexOf(chunk[1])
+    const coda = CODAS.indexOf(chunk[2])
+    if (onset < 0 || vowel < 0 || coda < 0) throw new Error(`invalid region token chunk: ${chunk}`)
+    return onset * (VOWELS.length * CODAS.length) + vowel * CODAS.length + coda
+}
+
+export function encodeRegion(seed: Checksum256Type, rx: number, ry: number): string {
+    const index = rx * REGION_PER_AXIS + ry
+    let n = permute(seed, index, REGION_FEISTEL)
+    const d0 = n % SYL_BASE
+    n = Math.floor(n / SYL_BASE)
+    const d1 = n % SYL_BASE
+    const d2 = Math.floor(n / SYL_BASE)
+    const token = syllable(d2) + syllable(d1) + syllable(d0)
+    return token.charAt(0).toUpperCase() + token.slice(1)
+}
+
+export function decodeRegion(seed: Checksum256Type, token: string): {rx: number; ry: number} {
+    if (token.length !== 9) throw new Error(`invalid region token length: ${token}`)
+    const lower = token.toLowerCase()
+    const d2 = unsyllable(lower.slice(0, 3))
+    const d1 = unsyllable(lower.slice(3, 6))
+    const d0 = unsyllable(lower.slice(6, 9))
+    const scrambled = (d2 * SYL_BASE + d1) * SYL_BASE + d0
+    if (scrambled >= REGION_FEISTEL.n) throw new Error(`invalid region token: ${token}`)
+    const index = unpermute(seed, scrambled, REGION_FEISTEL)
+    return {rx: Math.floor(index / REGION_PER_AXIS), ry: index % REGION_PER_AXIS}
+}

package/src/coordinates/sectors.ts

@@ -0,0 +1,115 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {SECTOR_FEISTEL, SECTORS_PER_AXIS} from './constants'
+import {permute, unpermute} from './permutation'
+
+// FROZEN INTERFACE — curation seed; review before launch, then never reorder.
+export const SECTOR_ADJECTIVES: readonly string[] = [
+    'Amber',
+    'Azure',
+    'Brass',
+    'Cinder',
+    'Cobalt',
+    'Copper',
+    'Coral',
+    'Crimson',
+    'Crystal',
+    'Dusk',
+    'Ember',
+    'Emerald',
+    'Frost',
+    'Glimmer',
+    'Golden',
+    'Hazy',
+    'Indigo',
+    'Iron',
+    'Ivory',
+    'Jade',
+    'Lunar',
+    'Misty',
+    'Neon',
+    'Onyx',
+    'Opal',
+    'Pearl',
+    'Plasma',
+    'Quartz',
+    'Rusty',
+    'Saffron',
+    'Scarlet',
+    'Silver',
+    'Solar',
+    'Static',
+    'Stormy',
+    'Sunny',
+    'Teal',
+    'Umber',
+    'Velvet',
+    'Verdant',
+    'Vermilion',
+    'Violet',
+    'Wispy',
+]
+
+export const SECTOR_NOUNS: readonly string[] = [
+    'Belt',
+    'Bluff',
+    'Cluster',
+    'Coil',
+    'Crest',
+    'Drift',
+    'Expanse',
+    'Fathom',
+    'Flare',
+    'Gulf',
+    'Halo',
+    'Haven',
+    'Hollow',
+    'Maw',
+    'Mesa',
+    'Mire',
+    'Notch',
+    'Nook',
+    'Oasis',
+    'Lagoon',
+    'Peak',
+    'Pocket',
+    'Reach',
+    'Reef',
+    'Ridge',
+    'Rift',
+    'Run',
+    'Shoal',
+    'Shroud',
+    'Span',
+    'Spire',
+    'Spur',
+    'Stretch',
+    'Sprawl',
+    'Tangle',
+    'Trace',
+    'Trench',
+    'Vale',
+    'Vault',
+    'Verge',
+    'Vortex',
+    'Ward',
+    'Wisp',
+]
+
+export function encodeSector(seed: Checksum256Type, sx: number, sy: number): string {
+    const index = sx * SECTORS_PER_AXIS + sy
+    const scrambled = permute(seed, index, SECTOR_FEISTEL)
+    const adj = Math.floor(scrambled / SECTORS_PER_AXIS)
+    const noun = scrambled % SECTORS_PER_AXIS
+    return `${SECTOR_ADJECTIVES[adj]} ${SECTOR_NOUNS[noun]}`
+}
+
+export function decodeSector(seed: Checksum256Type, name: string): {sx: number; sy: number} {
+    const parts = name.trim().split(/\s+/)
+    if (parts.length !== 2) throw new Error(`invalid sector name: ${name}`)
+    const adj = SECTOR_ADJECTIVES.indexOf(parts[0])
+    const noun = SECTOR_NOUNS.indexOf(parts[1])
+    if (adj < 0 || noun < 0) throw new Error(`unknown sector name: ${name}`)
+    const scrambled = adj * SECTORS_PER_AXIS + noun
+    const index = unpermute(seed, scrambled, SECTOR_FEISTEL)
+    return {sx: Math.floor(index / SECTORS_PER_AXIS), sy: index % SECTORS_PER_AXIS}
+}

package/src/derivation/wormhole.ts

@@ -0,0 +1,115 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {hash512} from '../utils/hash'
+
+export const WH = {
+    RSIZE: 75,
+    ZONE: 16384,
+    THRESHOLD: 8192,
+    MIN_REACH: 50000,
+    TRANSIT_SPEED: 500,
+} as const
+
+const HALF = Math.round(Math.log2(WH.ZONE))
+const MASK = WH.ZONE - 1
+
+function roll16(seed: Checksum256Type, str: string): number {
+    const h = hash512(seed, str).array
+    return (h[0] << 8) | h[1]
+}
+function feistelF(seed: Checksum256Type, x: number, round: number, key: string): number {
+    return roll16(seed, `feistel-${key}-${round}-${x}`) & MASK
+}
+export function feistel(seed: Checksum256Type, idx: number, key: string): number {
+    let L = (idx >>> HALF) & MASK
+    let R = idx & MASK
+    for (let r = 0; r < 4; r++) {
+        const nR = L ^ feistelF(seed, R, r, key)
+        L = R
+        R = nR
+    }
+    return (L << HALF) | R
+}
+export function feistelInv(seed: Checksum256Type, idx: number, key: string): number {
+    let L = (idx >>> HALF) & MASK
+    let R = idx & MASK
+    for (let r = 3; r >= 0; r--) {
+        const nL = R ^ feistelF(seed, L, r, key)
+        R = L
+        L = nL
+    }
+    return (L << HALF) | R
+}
+
+type Region = {rx: number; ry: number}
+
+export function regionOf(x: number, y: number): Region {
+    return {rx: Math.floor(x / WH.RSIZE), ry: Math.floor(y / WH.RSIZE)}
+}
+export function partnerRegion(seed: Checksum256Type, R: Region): Region {
+    const qx = Math.floor(R.rx / WH.ZONE)
+    const qy = Math.floor(R.ry / WH.ZONE)
+    const zx = qx * WH.ZONE
+    const zy = qy * WH.ZONE
+    const key = `${qx}:${qy}`
+    const idx = (R.ry - zy) * WH.ZONE + (R.rx - zx)
+    const p = feistelInv(seed, feistel(seed, idx, key) ^ 1, key)
+    return {rx: zx + (p % WH.ZONE), ry: zy + Math.floor(p / WH.ZONE)}
+}
+function regKey(R: Region): string {
+    return `${R.rx}:${R.ry}`
+}
+function pairKey(a: Region, b: Region): string {
+    const ka = regKey(a)
+    const kb = regKey(b)
+    return ka < kb ? `${ka}|${kb}` : `${kb}|${ka}`
+}
+function endpointInRegion(seed: Checksum256Type, R: Region, key: string): {x: number; y: number} {
+    const h = hash512(seed, `wh-endpoint-${key}-${regKey(R)}`).array
+    const ox = ((h[0] << 24) | (h[1] << 16) | (h[2] << 8) | h[3]) >>> 0
+    const oy = ((h[4] << 24) | (h[5] << 16) | (h[6] << 8) | h[7]) >>> 0
+    return {x: R.rx * WH.RSIZE + (ox % WH.RSIZE), y: R.ry * WH.RSIZE + (oy % WH.RSIZE)}
+}
+function dist(a: {x: number; y: number}, b: {x: number; y: number}): number {
+    return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2)
+}
+function wormholeOfRegion(
+    seed: Checksum256Type,
+    R: Region
+): {A: {x: number; y: number}; B: {x: number; y: number}} | null {
+    const P = partnerRegion(seed, R)
+    if (P.rx === R.rx && P.ry === R.ry) return null
+    const key = pairKey(R, P)
+    if (roll16(seed, `wh-exists-${key}`) >= WH.THRESHOLD) return null
+    const A = endpointInRegion(seed, R, key)
+    const B = endpointInRegion(seed, P, key)
+    if (dist(A, B) < WH.MIN_REACH) return null
+    return {A, B}
+}
+export function wormholeAtRegionEndpoint(
+    seed: Checksum256Type,
+    rx: number,
+    ry: number
+): {from: {x: number; y: number}; to: {x: number; y: number}} | null {
+    const w = wormholeOfRegion(seed, {rx, ry})
+    if (!w) return null
+    return {from: w.A, to: w.B}
+}
+export function wormholeAt(
+    seed: Checksum256Type,
+    x: number,
+    y: number
+): {x: number; y: number} | null {
+    const w = wormholeOfRegion(seed, regionOf(x, y))
+    if (!w || w.A.x !== x || w.A.y !== y) return null
+    return w.B
+}
+export function isValidWormholePair(
+    seed: Checksum256Type,
+    ax: number,
+    ay: number,
+    bx: number,
+    by: number
+): boolean {
+    const to = wormholeAt(seed, ax, ay)
+    return to !== null && to.x === bx && to.y === by
+}

package/src/errors.ts

@@ -56,6 +56,8 @@ export const GROUP_HAUL_CAPACITY_EXCEEDED =
     'Group travel requires sufficient hauler capacity for all non-self-propelled entities.'
 export const CANCEL_CONTAINS_GROUPED_TASK =
     'Cannot cancel range containing grouped task - cancel non-grouped tasks first.'
+export const WOULD_STRAND = 'Cancelling this would leave a later task without the cargo it needs.'
+export const WOULD_OVERFILL = 'Cancelling this would overfill the other entity with returned cargo.'
 export const WARP_NO_CAPABILITY = 'Entity does not have warp capability.'
 export const WARP_HAS_SCHEDULE = 'Entity must be idle to warp.'
 export const WARP_HAS_CARGO = 'Entity must have no cargo to warp.'

package/src/index-module.ts

@@ -87,6 +87,7 @@ export type {EpochInfo} from './scheduling/epoch'
 export {
     getSystemName,
     hasSystem,
+    getLocationKind,
     getLocationType,
     getLocationTypeName,
     isGatherableLocation,
@@ -164,6 +165,7 @@ export {
     calc_ship_mass,
     calc_ship_rechargetime,
     calc_transfer_duration,
+    calc_transit_duration,
     calculateFlightTime,
     calculateLoadTimeBreakdown,
     calculateRefuelingTime,
@@ -232,6 +234,15 @@ export type {TaskCargoChange, TaskCargoDirection} from './scheduling/task-cargo'
 export {composeIdleResolve} from './scheduling/idle-resolve'
 export type {CounterpartLookup, IdleResolveTarget} from './scheduling/idle-resolve'
 
+export {cancelEligibility, CancelBlockReason} from './scheduling/cancel'
+export type {
+    CancelPlan,
+    CancelEffects,
+    CancelRefund,
+    CancelReleasedHold,
+    CancelEligibilityInput,
+} from './scheduling/cancel'
+
 export {
     projectedCargoAvailableAt,
     availableForItem,
@@ -356,6 +367,17 @@ export {
 } from './derivation/capabilities'
 export type {GathererDepthParams, ComputedCapabilities} from './derivation/capabilities'
 
+export {
+    WH,
+    feistel,
+    feistelInv,
+    regionOf,
+    partnerRegion,
+    wormholeAt,
+    wormholeAtRegionEndpoint,
+    isValidWormholePair,
+} from './derivation/wormhole'
+
 export {resolveItem} from './resolution/resolve-item'
 export type {
     ResolvedItem,
@@ -460,6 +482,7 @@ export {
 } from './data/tiers'
 
 export {formatMass, formatMassDelta, formatMassScaled, formatLocation} from './format'
+export * from './coordinates'
 
 export {displayName, baseName, describeItem} from './resolution/display-name'
 export type {DescribeOptions} from './resolution/display-name'

package/src/managers/actions.ts

@@ -3,6 +3,7 @@ import {
     Checksum256,
     type Checksum256Type,
     Int64,
+    type Int64Type,
     Name,
     type NameType,
     UInt8,
@@ -37,13 +38,17 @@ export class ActionsManager extends BaseManager {
         })
     }
 
-    grouptravel(entities: EntityRefInput[], destination: CoordinatesType, recharge = true): Action {
-        const entityRefs = entities.map((e) =>
+    private entityRefs(entities: EntityRefInput[]) {
+        return entities.map((e) =>
             ServerContract.Types.entity_ref.from({
                 entity_type: e.entityType,
                 entity_id: UInt64.from(e.entityId),
             })
         )
+    }
+
+    grouptravel(entities: EntityRefInput[], destination: CoordinatesType, recharge = true): Action {
+        const entityRefs = this.entityRefs(entities)
         const x = Int64.from(destination.x)
         const y = Int64.from(destination.y)
 
@@ -55,6 +60,44 @@ export class ActionsManager extends BaseManager {
         })
     }
 
+    transit(shipId: UInt64Type, entrance: CoordinatesType, exit: CoordinatesType): Action {
+        return this.server.action('transit', {
+            id: UInt64.from(shipId),
+            ax: Int64.from(entrance.x),
+            ay: Int64.from(entrance.y),
+            bx: Int64.from(exit.x),
+            by: Int64.from(exit.y),
+        })
+    }
+
+    grouptransit(
+        entities: EntityRefInput[],
+        entrance: CoordinatesType,
+        exit: CoordinatesType
+    ): Action {
+        const entityRefs = this.entityRefs(entities)
+        return this.server.action('grouptransit', {
+            entities: entityRefs,
+            ax: Int64.from(entrance.x),
+            ay: Int64.from(entrance.y),
+            bx: Int64.from(exit.x),
+            by: Int64.from(exit.y),
+        })
+    }
+
+    getwormhole(x: Int64Type, y: Int64Type): Action {
+        return this.server.action('getwormhole', {x: Int64.from(x), y: Int64.from(y)})
+    }
+
+    getdistance(origin: CoordinatesType, destination: CoordinatesType): Action {
+        return this.server.action('getdistance', {
+            ax: Int64.from(origin.x),
+            ay: Int64.from(origin.y),
+            bx: Int64.from(destination.x),
+            by: Int64.from(destination.y),
+        })
+    }
+
     resolve(entityId: UInt64Type, count?: UInt64Type): Action {
         const params: ServerContract.ActionParams.resolve = {
             id: UInt64.from(entityId),

package/src/scheduling/availability.ts

@@ -36,7 +36,7 @@ export function taskCargoEffect(task: Task): CargoEffect {
     }
 }
 
-function cargoKey(item: CargoItem): string {
+export function cargoKey(item: CargoItem): string {
     const base = `${item.item_id.toNumber()}:${item.stats.toString()}`
     const modules = item.modules ?? []
     const entityId = item.entity_id?.toString()