@shipload/sdk 2.0.0-rc1 → 2.0.0-rc11

package/src/data/tiers.ts

@@ -0,0 +1,45 @@
+export type CraftedItemCategory = 'component' | 'module' | 'entity' | 'resource'
+
+export const ITEM_TYPE_RESOURCE = 0
+export const ITEM_TYPE_COMPONENT = 1
+export const ITEM_TYPE_MODULE = 2
+export const ITEM_TYPE_ENTITY = 3
+
+export function itemTypeCode(id: number): number {
+    switch (itemCategory(id)) {
+        case 'resource':
+            return ITEM_TYPE_RESOURCE
+        case 'component':
+            return ITEM_TYPE_COMPONENT
+        case 'module':
+            return ITEM_TYPE_MODULE
+        case 'entity':
+            return ITEM_TYPE_ENTITY
+    }
+}
+
+export function itemTier(id: number): number {
+    if (id < 10000) return 0
+    return Math.floor(id / 10000)
+}
+
+export function itemOffset(id: number): number {
+    return id % 10000
+}
+
+export function itemCategory(id: number): CraftedItemCategory {
+    if (id < 10000) return 'resource'
+    const offset = itemOffset(id)
+    if (offset >= 200) return 'entity'
+    if (offset >= 100) return 'module'
+    return 'component'
+}
+
+export function isRelatedItem(a: number, b: number): boolean {
+    if (a < 10000 || b < 10000) return false
+    return itemOffset(a) === itemOffset(b)
+}
+
+export function isCraftedItem(id: number): boolean {
+    return id >= 10000
+}

package/src/derivation/crafting.ts

@@ -0,0 +1,197 @@
+import {UInt64} from '@wharfkit/antelope'
+import type {ResourceCategory} from '../types'
+import {
+    entityRecipes,
+    getComponentById,
+    getEntityRecipe,
+    getModuleRecipe,
+    moduleRecipes,
+} from '../data/recipes'
+import {deriveResourceStats} from './stratum'
+
+export interface StackInput {
+    quantity: number
+    stats: Record<string, number>
+}
+
+export interface CategoryStacks {
+    category: ResourceCategory
+    stacks: StackInput[]
+}
+
+export function encodeStats(values: number[]): bigint {
+    let seed = 0n
+    for (let i = 0; i < values.length && i < 6; i++) {
+        seed |= BigInt(values[i] & 0x3ff) << BigInt(i * 10)
+    }
+    return seed
+}
+
+export function decodeStat(seed: bigint, index: number): number {
+    return Number((seed >> BigInt(index * 10)) & 0x3ffn)
+}
+
+export function decodeStats(seed: bigint, count: number): number[] {
+    const stats: number[] = []
+    for (let i = 0; i < count; i++) {
+        stats.push(decodeStat(seed, i))
+    }
+    return stats
+}
+
+function mapStatsToKeys(seed: bigint, statDefs: {key: string}[]): Record<string, number> {
+    const values = decodeStats(seed, statDefs.length)
+    const result: Record<string, number> = {}
+    for (let i = 0; i < statDefs.length; i++) {
+        result[statDefs[i].key] = values[i]
+    }
+    return result
+}
+
+export function decodeCraftedItemStats(itemId: number, seed: bigint): Record<string, number> {
+    const comp = getComponentById(itemId)
+    if (comp) return mapStatsToKeys(seed, comp.stats)
+
+    const entityRecipe = entityRecipes.find((r) => r.packedItemId === itemId)
+    if (entityRecipe) return mapStatsToKeys(seed, entityRecipe.stats)
+
+    const moduleRecipe = moduleRecipes.find((r) => r.itemId === itemId)
+    if (moduleRecipe) return mapStatsToKeys(seed, moduleRecipe.stats)
+
+    return {}
+}
+
+export function blendStacks(stacks: StackInput[], statKey: string): number {
+    let totalQty = 0
+    let weightedSum = 0
+    for (const stack of stacks) {
+        const val = stack.stats[statKey] ?? 0
+        weightedSum += val * stack.quantity
+        totalQty += stack.quantity
+    }
+    if (totalQty === 0) return 0
+    return Math.floor(weightedSum / totalQty)
+}
+
+export function computeComponentStats(
+    componentId: number,
+    categoryStacks: CategoryStacks[]
+): {key: string; value: number}[] {
+    const comp = getComponentById(componentId)
+    if (!comp) return []
+
+    return comp.stats.map((statDef) => {
+        const matching = categoryStacks.find((cs) => cs.category === statDef.source)
+        const value = matching ? blendStacks(matching.stacks, statDef.key) : 0
+        return {key: statDef.key, value: Math.max(1, Math.min(999, value))}
+    })
+}
+
+export function blendComponentStacks(
+    stacks: {quantity: number; stats: Record<string, number>}[]
+): Record<string, number> {
+    if (stacks.length === 0) return {}
+    const allKeys = new Set<string>()
+    for (const s of stacks) {
+        for (const k of Object.keys(s.stats)) allKeys.add(k)
+    }
+    const result: Record<string, number> = {}
+    for (const key of allKeys) {
+        result[key] = blendStacks(
+            stacks.map((s) => ({quantity: s.quantity, stats: s.stats})),
+            key
+        )
+    }
+    return result
+}
+
+export function computeEntityStats(
+    entityRecipeId: string,
+    componentStacks: Record<number, {quantity: number; stats: Record<string, number>}[]>
+): {key: string; value: number}[] {
+    const recipe = getEntityRecipe(entityRecipeId) ?? getModuleRecipe(entityRecipeId)
+    if (!recipe) return []
+
+    const blendedByComponent: Record<number, Record<string, number>> = {}
+    for (const [compId, stacks] of Object.entries(componentStacks)) {
+        blendedByComponent[Number(compId)] = blendComponentStacks(stacks)
+    }
+
+    return recipe.stats.map((stat) => {
+        const blended = blendedByComponent[stat.sourceComponentId] ?? {}
+        const value = blended[stat.sourceStatKey] ?? 0
+        return {key: stat.key, value: Math.max(1, Math.min(999, value))}
+    })
+}
+
+function decodeStackStats(itemId: number, seed: UInt64): Record<string, number> {
+    if (itemId >= 10000) {
+        return decodeCraftedItemStats(itemId, BigInt(seed.toString()))
+    }
+    const raw = deriveResourceStats(BigInt(seed.toString()))
+    return {stat1: raw.stat1, stat2: raw.stat2, stat3: raw.stat3}
+}
+
+export const categoryItemMass: Record<string, number> = {
+    metal: 30000,
+    precious: 40000,
+    gas: 15000,
+    mineral: 22000,
+    organic: 15000,
+}
+
+export function computeInputMass(
+    itemId: string | number,
+    itemType: 'component' | 'module' | 'entity'
+): number {
+    if (itemType === 'component') {
+        const comp = getComponentById(itemId as number)
+        if (!comp) return 0
+        return comp.recipe.reduce((sum, input) => {
+            const mass = input.category ? categoryItemMass[input.category] ?? 0 : 0
+            return sum + mass * input.quantity
+        }, 0)
+    }
+    if (itemType === 'module') {
+        const mod = getModuleRecipe(itemId as string)
+        if (!mod) return 0
+        return mod.recipe.reduce((sum, input) => {
+            const comp = input.itemId ? getComponentById(input.itemId) : undefined
+            return sum + (comp?.mass ?? 0) * input.quantity
+        }, 0)
+    }
+    if (itemType === 'entity') {
+        const ent = getEntityRecipe(itemId as string)
+        if (!ent) return 0
+        return ent.recipe.reduce((sum, input) => {
+            const comp = input.itemId ? getComponentById(input.itemId) : undefined
+            return sum + (comp?.mass ?? 0) * input.quantity
+        }, 0)
+    }
+    return 0
+}
+
+export function blendCrossGroup(sources: {value: number; weight: number}[]): number {
+    let weightedSum = 0
+    let totalWeight = 0
+    for (const src of sources) {
+        weightedSum += src.value * src.weight
+        totalWeight += src.weight
+    }
+    if (totalWeight === 0) return 1
+    const result = Math.floor(weightedSum / totalWeight)
+    return Math.max(1, Math.min(999, result))
+}
+
+export function blendCargoStacks(
+    itemId: number,
+    stacks: {quantity: number; seed: UInt64}[]
+): UInt64 {
+    const decoded = stacks.map((s) => ({
+        quantity: s.quantity,
+        stats: decodeStackStats(itemId, s.seed),
+    }))
+    const allKeys = Object.keys(decoded[0]?.stats ?? {})
+    const blended = allKeys.map((key) => Math.max(1, Math.min(999, blendStacks(decoded, key))))
+    return UInt64.from(encodeStats(blended))
+}

package/src/derivation/index.ts

@@ -0,0 +1,28 @@
+export {deriveStratum, deriveResourceStats} from './stratum'
+export type {StratumInfo, ResourceStats} from './stratum'
+export {deriveLocationSize} from './location-size'
+export {
+    getEligibleResources,
+    getResourceWeight,
+    getLocationCandidates,
+    getDepthThreshold,
+    getResourceTier,
+    depthScaleFactor,
+    DEPTH_THRESHOLD_T1,
+    DEPTH_THRESHOLD_T2,
+    DEPTH_THRESHOLD_T3,
+    DEPTH_THRESHOLD_T4,
+    DEPTH_THRESHOLD_T5,
+    LOCATION_MIN_DEPTH,
+    LOCATION_MAX_DEPTH,
+    YIELD_THRESHOLD,
+    PLANET_SUBTYPE_GAS_GIANT,
+    PLANET_SUBTYPE_ROCKY,
+    PLANET_SUBTYPE_TERRESTRIAL,
+    PLANET_SUBTYPE_ICY,
+    PLANET_SUBTYPE_OCEAN,
+    PLANET_SUBTYPE_INDUSTRIAL,
+} from './resources'
+
+export * from './stats'
+export * from './crafting'

package/src/derivation/location-size.ts

@@ -0,0 +1,15 @@
+import {ServerContract} from '../contracts'
+import {LocationType} from '../types'
+import {LOCATION_MAX_DEPTH, LOCATION_MIN_DEPTH} from './resources'
+
+export function deriveLocationSize(loc: ServerContract.Types.location_static): number {
+    if (loc.type.toNumber() === LocationType.EMPTY) return 0
+
+    const raw = (loc.seed0.toNumber() << 8) | loc.seed1.toNumber()
+    const normalized = raw / 65535
+
+    const curved = Math.pow(normalized, 3.0)
+
+    const range = LOCATION_MAX_DEPTH - LOCATION_MIN_DEPTH
+    return Math.floor(LOCATION_MIN_DEPTH + curved * range)
+}

package/src/derivation/resources.ts

@@ -0,0 +1,142 @@
+import {ResourceTier} from '../types'
+
+export const DEPTH_THRESHOLD_T1 = 0
+export const DEPTH_THRESHOLD_T2 = 2000
+export const DEPTH_THRESHOLD_T3 = 10000
+export const DEPTH_THRESHOLD_T4 = 30000
+export const DEPTH_THRESHOLD_T5 = 55000
+
+export const LOCATION_MIN_DEPTH = 500
+export const LOCATION_MAX_DEPTH = 65535
+
+export const YIELD_THRESHOLD = Math.floor(0.003 * 0xffffffff)
+
+export const PLANET_SUBTYPE_GAS_GIANT = 0
+export const PLANET_SUBTYPE_ROCKY = 1
+export const PLANET_SUBTYPE_TERRESTRIAL = 2
+export const PLANET_SUBTYPE_ICY = 3
+export const PLANET_SUBTYPE_OCEAN = 4
+export const PLANET_SUBTYPE_INDUSTRIAL = 5
+
+interface ResourceEntry {
+    id: number
+    tier: ResourceTier
+}
+
+const RESOURCE_CATALOG: ResourceEntry[] = [
+    {id: 26, tier: 't1'},
+    {id: 13, tier: 't2'},
+    {id: 24, tier: 't3'},
+    {id: 29, tier: 't1'},
+    {id: 47, tier: 't2'},
+    {id: 79, tier: 't3'},
+    {id: 1, tier: 't1'},
+    {id: 2, tier: 't2'},
+    {id: 18, tier: 't3'},
+    {id: 14, tier: 't1'},
+    {id: 1000, tier: 't2'},
+    {id: 1001, tier: 't3'},
+    {id: 6, tier: 't1'},
+    {id: 1003, tier: 't2'},
+    {id: 1002, tier: 't3'},
+]
+
+export function getDepthThreshold(tier: ResourceTier): number {
+    switch (tier) {
+        case 't1':
+            return DEPTH_THRESHOLD_T1
+        case 't2':
+            return DEPTH_THRESHOLD_T2
+        case 't3':
+            return DEPTH_THRESHOLD_T3
+        case 't4':
+            return DEPTH_THRESHOLD_T4
+        case 't5':
+            return DEPTH_THRESHOLD_T5
+    }
+}
+
+export function getResourceTier(itemId: number): ResourceTier {
+    const entry = RESOURCE_CATALOG.find((r) => r.id === itemId)
+    return entry ? entry.tier : 't5'
+}
+
+export function getResourceWeight(itemId: number, stratum: number): number {
+    const tier = getResourceTier(itemId)
+    const threshold = getDepthThreshold(tier)
+    if (stratum < threshold) return 0
+
+    const depthAbove = stratum - threshold
+
+    switch (tier) {
+        case 't1':
+            if (stratum < 2000) return 100
+            if (stratum < 10000) return 80
+            if (stratum < 30000) return 50
+            return 30
+        case 't2':
+            if (depthAbove < 3000) return 40
+            if (depthAbove < 8000) return 60
+            return 50
+        case 't3':
+            if (depthAbove < 5000) return 20
+            if (depthAbove < 15000) return 35
+            return 40
+        case 't4':
+            if (depthAbove < 10000) return 10
+            if (depthAbove < 25000) return 20
+            return 30
+        case 't5':
+            return 10
+    }
+}
+
+const ASTEROID_RESOURCES = [26, 13, 24, 29, 47]
+const NEBULA_RESOURCES = [47, 79, 1, 2, 18]
+const GAS_GIANT_RESOURCES = [1, 2, 18, 14, 6]
+const ROCKY_RESOURCES = [26, 13, 24, 14, 1000, 1001, 1002]
+const TERRESTRIAL_RESOURCES = [29, 47, 14, 1000, 6, 1003, 1002]
+const ICY_RESOURCES = [26, 1, 2, 14, 1001, 6, 1003]
+const OCEAN_RESOURCES = [29, 79, 1, 18, 6, 1003, 1002]
+const INDUSTRIAL_RESOURCES = [26, 13, 24, 29, 79, 1000, 1001]
+
+export function getLocationCandidates(locationType: number, subtype: number): number[] {
+    if (locationType === 2) return ASTEROID_RESOURCES
+    if (locationType === 3) return NEBULA_RESOURCES
+    if (locationType === 1) {
+        switch (subtype) {
+            case PLANET_SUBTYPE_GAS_GIANT:
+                return GAS_GIANT_RESOURCES
+            case PLANET_SUBTYPE_ROCKY:
+                return ROCKY_RESOURCES
+            case PLANET_SUBTYPE_TERRESTRIAL:
+                return TERRESTRIAL_RESOURCES
+            case PLANET_SUBTYPE_ICY:
+                return ICY_RESOURCES
+            case PLANET_SUBTYPE_OCEAN:
+                return OCEAN_RESOURCES
+            case PLANET_SUBTYPE_INDUSTRIAL:
+                return INDUSTRIAL_RESOURCES
+        }
+    }
+    return []
+}
+
+export function getEligibleResources(
+    locationType: number,
+    subtype: number,
+    stratum: number
+): number[] {
+    const candidates = getLocationCandidates(locationType, subtype)
+    return candidates.filter((itemId) => {
+        const tier = getResourceTier(itemId)
+        const threshold = getDepthThreshold(tier)
+        return stratum >= threshold
+    })
+}
+
+export function depthScaleFactor(stratum: number): number {
+    if (stratum <= 1) return 1.0
+    const logScale = Math.log(stratum) / Math.log(65535)
+    return 1.0 + logScale * 2.0
+}

package/src/derivation/stats.ts

@@ -0,0 +1,146 @@
+import type {ResourceCategory} from '../types'
+
+export interface StatDefinition {
+    key: string
+    label: string
+    abbreviation: string
+    purpose: string
+    inverted?: boolean
+}
+
+const METAL_STATS: StatDefinition[] = [
+    {
+        key: 'strength',
+        label: 'Strength',
+        abbreviation: 'STR',
+        purpose: 'Raw structural/mechanical force',
+    },
+    {
+        key: 'tolerance',
+        label: 'Tolerance',
+        abbreviation: 'TOL',
+        purpose: 'Ability to withstand heat, pressure, and stress extremes',
+    },
+    {
+        key: 'density',
+        label: 'Density',
+        abbreviation: 'DEN',
+        purpose: 'Mass per unit',
+        inverted: true,
+    },
+]
+
+const PRECIOUS_STATS: StatDefinition[] = [
+    {
+        key: 'conductivity',
+        label: 'Conductivity',
+        abbreviation: 'CON',
+        purpose: 'Efficiency of energy/signal transfer',
+    },
+    {
+        key: 'ductility',
+        label: 'Ductility',
+        abbreviation: 'DUC',
+        purpose: 'Ability to be worked into fine, precise shapes',
+    },
+    {
+        key: 'reflectivity',
+        label: 'Reflectivity',
+        abbreviation: 'REF',
+        purpose: 'Surface quality for heat management and precision optics',
+    },
+]
+
+const GAS_STATS: StatDefinition[] = [
+    {
+        key: 'volatility',
+        label: 'Volatility',
+        abbreviation: 'VOL',
+        purpose: 'Energy release potential for propulsion and force',
+    },
+    {
+        key: 'reactivity',
+        label: 'Reactivity',
+        abbreviation: 'REA',
+        purpose: 'Chemical interaction speed for processing and penetration',
+    },
+    {
+        key: 'thermal',
+        label: 'Thermal',
+        abbreviation: 'THM',
+        purpose: 'Heat capacity for thermal management',
+    },
+]
+
+const MINERAL_STATS: StatDefinition[] = [
+    {
+        key: 'resonance',
+        label: 'Resonance',
+        abbreviation: 'RES',
+        purpose: 'Energy field interaction — storage, focusing, projection',
+    },
+    {
+        key: 'hardness',
+        label: 'Hardness',
+        abbreviation: 'HRD',
+        purpose: 'Resistance to wear — cutting surfaces, penetration',
+    },
+    {
+        key: 'clarity',
+        label: 'Clarity',
+        abbreviation: 'CLR',
+        purpose: 'Crystalline perfection — precision optics',
+    },
+]
+
+const ORGANIC_STATS: StatDefinition[] = [
+    {
+        key: 'plasticity',
+        label: 'Plasticity',
+        abbreviation: 'PLA',
+        purpose: 'Ease of reshaping — speeds processing',
+    },
+    {
+        key: 'insulation',
+        label: 'Insulation',
+        abbreviation: 'INS',
+        purpose: 'Energy containment — reduces energy loss',
+    },
+    {
+        key: 'purity',
+        label: 'Purity',
+        abbreviation: 'PUR',
+        purpose: 'Biological cleanliness — better composites and lubricants',
+    },
+]
+
+const STAT_MAP: Record<ResourceCategory, StatDefinition[]> = {
+    metal: METAL_STATS,
+    precious: PRECIOUS_STATS,
+    gas: GAS_STATS,
+    mineral: MINERAL_STATS,
+    organic: ORGANIC_STATS,
+}
+
+export function getStatDefinitions(category: ResourceCategory): StatDefinition[] {
+    return STAT_MAP[category]
+}
+
+export function getStatName(category: ResourceCategory, index: 0 | 1 | 2): StatDefinition {
+    return STAT_MAP[category][index]
+}
+
+export interface NamedStats {
+    definitions: StatDefinition[]
+    values: [number, number, number]
+}
+
+export function resolveStats(
+    category: ResourceCategory,
+    stats: {stat1: number; stat2: number; stat3: number}
+): NamedStats {
+    return {
+        definitions: STAT_MAP[category],
+        values: [stats.stat1, stats.stat2, stats.stat3],
+    }
+}

package/src/derivation/stratum.ts

@@ -0,0 +1,124 @@
+import {Bytes, Checksum256, Checksum256Type} from '@wharfkit/antelope'
+import {hash512} from '../utils/hash'
+import {Coordinates, CoordinatesType} from '../types'
+import {
+    depthScaleFactor,
+    getEligibleResources,
+    getResourceWeight,
+    YIELD_THRESHOLD,
+} from './resources'
+
+export interface StratumInfo {
+    itemId: number
+    seed: bigint
+    richness: number
+    reserve: number
+}
+
+export interface ResourceStats {
+    stat1: number
+    stat2: number
+    stat3: number
+}
+
+export function deriveStratum(
+    epochSeed: Checksum256Type,
+    coords: CoordinatesType,
+    stratum: number,
+    locationType: number,
+    subtype: number,
+    _maxDepth: number
+): StratumInfo {
+    const seed = Checksum256.from(epochSeed)
+    const c = Coordinates.from(coords)
+    const input = `stratum-${c.x}-${c.y}-${stratum}`
+    const hashResult = hash512(seed, input)
+    const bytes = hashResult.array
+
+    const rawReserve = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0
+
+    let reserve = 0
+    if (rawReserve <= YIELD_THRESHOLD) {
+        const baseReserve = (rawReserve % 333) + 1
+        const scale = depthScaleFactor(stratum)
+        reserve = Math.floor(baseReserve * scale)
+    }
+
+    if (reserve === 0) return {itemId: 0, seed: 0n, richness: 0, reserve: 0}
+
+    const eligible = getEligibleResources(locationType, subtype, stratum)
+    if (eligible.length === 0) return {itemId: 0, seed: 0n, richness: 0, reserve: 0}
+
+    const resourceRoll = ((bytes[4] << 24) | (bytes[5] << 16) | (bytes[6] << 8) | bytes[7]) >>> 0
+
+    let totalWeight = 0
+    for (const id of eligible) {
+        totalWeight += getResourceWeight(id, stratum)
+    }
+
+    let selectedItemId = eligible[0]
+    if (totalWeight > 0) {
+        const roll = resourceRoll % totalWeight
+        let cumulative = 0
+        for (const id of eligible) {
+            cumulative += getResourceWeight(id, stratum)
+            if (roll < cumulative) {
+                selectedItemId = id
+                break
+            }
+        }
+    }
+
+    const seedBigInt =
+        (BigInt(bytes[8]) << 56n) |
+        (BigInt(bytes[9]) << 48n) |
+        (BigInt(bytes[10]) << 40n) |
+        (BigInt(bytes[11]) << 32n) |
+        (BigInt(bytes[12]) << 24n) |
+        (BigInt(bytes[13]) << 16n) |
+        (BigInt(bytes[14]) << 8n) |
+        BigInt(bytes[15])
+
+    const rawRichness = (bytes[16] << 8) | bytes[17]
+    const normalized = rawRichness / 65535
+    const baseRichness = Math.floor(normalized * normalized * 999) + 1
+
+    let depthBonus = 0
+    if (stratum > 1) {
+        depthBonus = (50 * Math.log(stratum)) / Math.log(65535)
+    }
+    const richness = Math.min(Math.floor(baseRichness + depthBonus), 1000)
+
+    return {itemId: selectedItemId, seed: seedBigInt, richness, reserve}
+}
+
+export function deriveResourceStats(seed: bigint): ResourceStats {
+    const seedBytes = new Uint8Array(8)
+    for (let i = 0; i < 8; i++) {
+        seedBytes[i] = Number(seed & 0xffn)
+        seed >>= 8n
+    }
+    const hashResult = Checksum256.hash(Bytes.from(seedBytes))
+    const hashBytes = hashResult.array
+
+    const extractU32 = (offset: number): number =>
+        (hashBytes[offset] * 0x1000000 +
+            (hashBytes[offset + 1] << 16) +
+            (hashBytes[offset + 2] << 8) +
+            hashBytes[offset + 3]) >>> 0
+
+    const weibull = (raw: number): number => {
+        const u = raw / 4294967296
+        let x = 0.27 * Math.sqrt(-Math.log(1 - u))
+        if (x > 1) x = 1
+        let val = Math.floor(x * 999) + 1
+        if (val > 999) val = 999
+        return val
+    }
+
+    return {
+        stat1: weibull(extractU32(0)),
+        stat2: weibull(extractU32(4)),
+        stat3: weibull(extractU32(8)),
+    }
+}