@shipload/sdk 2.0.0-rc2 → 2.0.0-rc21

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,348 @@
+import {UInt64} from '@wharfkit/antelope'
+import type {ResourceCategory} from '../types'
+import {findItemByCategoryAndTier, getRecipe, Recipe} from '../data/recipes-runtime'
+import {getItem} from '../market/items'
+import {getStatDefinitions} from './stats'
+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 stats = 0n
+    for (let i = 0; i < values.length && i < 6; i++) {
+        stats |= BigInt(values[i] & 0x3ff) << BigInt(i * 10)
+    }
+    return stats
+}
+
+export function decodeStat(stats: bigint, index: number): number {
+    return Number((stats >> BigInt(index * 10)) & 0x3ffn)
+}
+
+export function decodeStats(stats: bigint, count: number): number[] {
+    const result: number[] = []
+    for (let i = 0; i < count; i++) {
+        result.push(decodeStat(stats, i))
+    }
+    return result
+}
+
+function getItemStatKeys(itemId: number): string[] {
+    const item = getItem(itemId)
+    if (item.type === 'resource') {
+        if (!item.category) return []
+        return getStatDefinitions(item.category).map((d) => d.key)
+    }
+    const recipe = getRecipe(itemId)
+    if (!recipe) return []
+    return recipe.statSlots.map((slot) => keyForStatSlot(recipe, slot))
+}
+
+function keyForStatSlot(
+    recipe: Recipe,
+    slot: {sources: {inputIndex: number; statIndex: number}[]}
+): string {
+    const src = slot.sources[0]
+    if (!src) return ''
+    return keyForRecipeInputStat(recipe, src.inputIndex, src.statIndex)
+}
+
+function keyForRecipeInputStat(recipe: Recipe, inputIndex: number, statIndex: number): string {
+    const input = recipe.inputs[inputIndex]
+    if (!input) return ''
+    if ('category' in input) {
+        const defs = getStatDefinitions(input.category)
+        return defs[statIndex]?.key ?? ''
+    }
+    // itemId-typed input — its stats follow that item's own statSlots layout.
+    const innerKeys = getItemStatKeys(input.itemId)
+    return innerKeys[statIndex] ?? ''
+}
+
+export function decodeCraftedItemStats(itemId: number, stats: bigint): Record<string, number> {
+    const keys = getItemStatKeys(itemId)
+    const result: Record<string, number> = {}
+    for (let i = 0; i < keys.length; i++) {
+        if (keys[i]) result[keys[i]] = decodeStat(stats, i)
+    }
+    return result
+}
+
+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 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 computeComponentStats(
+    componentId: number,
+    categoryStacks: CategoryStacks[]
+): {key: string; value: number}[] {
+    const recipe = getRecipe(componentId)
+    if (!recipe) return []
+
+    return recipe.statSlots.map((slot) => {
+        const src = slot.sources[0]
+        const key = keyForStatSlot(recipe, slot)
+        const input = src ? recipe.inputs[src.inputIndex] : undefined
+        if (!input || !('category' in input)) {
+            return {key, value: Math.max(1, Math.min(999, 0))}
+        }
+        const matching = categoryStacks.find((cs) => cs.category === input.category)
+        const value = matching ? blendStacks(matching.stacks, key) : 0
+        return {key, value: Math.max(1, Math.min(999, value))}
+    })
+}
+
+export function computeEntityStats(
+    entityItemIdOrLegacyId: number | string,
+    componentStacks: Record<number, {quantity: number; stats: Record<string, number>}[]>
+): {key: string; value: number}[] {
+    const itemId =
+        typeof entityItemIdOrLegacyId === 'number'
+            ? entityItemIdOrLegacyId
+            : legacyEntityIdToItemId(entityItemIdOrLegacyId)
+    const recipe = getRecipe(itemId)
+    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.statSlots.map((slot) => {
+        const src = slot.sources[0]
+        const key = keyForStatSlot(recipe, slot)
+        if (!src) return {key, value: 1}
+        const input = recipe.inputs[src.inputIndex]
+        if (!input || 'category' in input) {
+            return {key, value: 1}
+        }
+        const blended = blendedByComponent[input.itemId] ?? {}
+        const value = blended[key] ?? 0
+        return {key, value: Math.max(1, Math.min(999, value))}
+    })
+}
+
+function legacyEntityIdToItemId(id: string): number {
+    switch (id) {
+        case 'container':
+            return 10200
+        case 'ship-t1':
+            return 10201
+        case 'warehouse-t1':
+            return 10202
+        case 'container-t2':
+            return 20200
+        default:
+            return 0
+    }
+}
+
+function decodeStackStats(itemId: number, stats: UInt64): Record<string, number> {
+    if (itemId >= 10000) {
+        return decodeCraftedItemStats(itemId, BigInt(stats.toString()))
+    }
+    const s = BigInt(stats.toString())
+    return {stat1: decodeStat(s, 0), stat2: decodeStat(s, 1), stat3: decodeStat(s, 2)}
+}
+
+export function computeInputMass(itemId: number): number {
+    const recipe = getRecipe(itemId)
+    if (!recipe) throw new Error(`computeInputMass: no recipe found for itemId=${itemId}`)
+
+    let total = 0
+    for (const input of recipe.inputs) {
+        if ('itemId' in input) {
+            total += getItem(input.itemId).mass * input.quantity
+        } else {
+            const item = findItemByCategoryAndTier(input.category, input.tier)
+            total += item.mass * input.quantity
+        }
+    }
+    return total
+}
+
+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; stats: UInt64}[]
+): UInt64 {
+    const decoded = stacks.map((s) => ({
+        quantity: s.quantity,
+        stats: decodeStackStats(itemId, s.stats),
+    }))
+    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))
+}
+
+export interface RecipeSlotInput {
+    itemId: number
+    category: ResourceCategory | undefined
+    stacks: {quantity: number; stats: bigint}[]
+}
+
+function decodeRawStackToCategoryStats(
+    stats: bigint,
+    category: ResourceCategory
+): Record<string, number> {
+    const defs = getStatDefinitions(category)
+    const result: Record<string, number> = {}
+    if (defs[0]) result[defs[0].key] = decodeStat(stats, 0)
+    if (defs[1]) result[defs[1].key] = decodeStat(stats, 1)
+    if (defs[2]) result[defs[2].key] = decodeStat(stats, 2)
+    return result
+}
+
+export function computeCraftedOutputStats(
+    outputItemId: number,
+    slotInputs: RecipeSlotInput[]
+): UInt64 {
+    const recipe = getRecipe(outputItemId)
+    if (!recipe) {
+        throw new Error(
+            `computeCraftedOutputStats: no recipe found for outputItemId=${outputItemId}`
+        )
+    }
+
+    const outputItem = getItem(outputItemId)
+
+    if (outputItem.type === 'entity') {
+        for (const slot of slotInputs) {
+            if (slot.category !== undefined) {
+                throw new Error(
+                    `entity recipe ${outputItemId} expects component inputs but slot itemId=${slot.itemId} has category=${slot.category}`
+                )
+            }
+        }
+    }
+
+    // Decode each slot's stacks into key→value maps using the slot item's
+    // own stat layout, so blending works regardless of recipe shape.
+    const decodedByItem: Record<number, {quantity: number; stats: Record<string, number>}[]> = {}
+    const decodedByCategory: Partial<Record<ResourceCategory, StackInput[]>> = {}
+
+    for (const slot of slotInputs) {
+        if (slot.category !== undefined) {
+            const list = (decodedByCategory[slot.category] ??= [])
+            for (const s of slot.stacks) {
+                list.push({
+                    quantity: s.quantity,
+                    stats: decodeRawStackToCategoryStats(s.stats, slot.category),
+                })
+            }
+        } else {
+            const list = (decodedByItem[slot.itemId] ??= [])
+            for (const s of slot.stacks) {
+                list.push({
+                    quantity: s.quantity,
+                    stats: decodeCraftedItemStats(slot.itemId, s.stats),
+                })
+            }
+        }
+    }
+
+    // Pre-blend itemId inputs once per item id.
+    const blendedByItem: Record<number, Record<string, number>> = {}
+    for (const [id, stacks] of Object.entries(decodedByItem)) {
+        blendedByItem[Number(id)] = blendComponentStacks(stacks)
+    }
+
+    const out: number[] = []
+    for (const slot of recipe.statSlots) {
+        if (slot.sources.length === 0) {
+            out.push(0)
+            continue
+        }
+        if (slot.sources.length === 1 || recipe.blendWeights.length === 0) {
+            const src = slot.sources[0]
+            const key = keyForRecipeInputStat(recipe, src.inputIndex, src.statIndex)
+            const input = recipe.inputs[src.inputIndex]
+            let value = 0
+            if (input && 'category' in input) {
+                value = blendStacks(decodedByCategory[input.category] ?? [], key)
+            } else if (input) {
+                value = blendedByItem[input.itemId]?.[key] ?? 0
+            }
+            out.push(Math.max(1, Math.min(999, value)))
+        } else {
+            let weightedSum = 0
+            let totalWeight = 0
+            for (const src of slot.sources) {
+                const key = keyForRecipeInputStat(recipe, src.inputIndex, src.statIndex)
+                const input = recipe.inputs[src.inputIndex]
+                const weight = recipe.blendWeights[src.inputIndex] ?? 1
+                let value = 0
+                if (input && 'category' in input) {
+                    value = blendStacks(decodedByCategory[input.category] ?? [], key)
+                } else if (input) {
+                    value = blendedByItem[input.itemId]?.[key] ?? 0
+                }
+                weightedSum += value * weight
+                totalWeight += weight
+            }
+            const blended = totalWeight > 0 ? Math.floor(weightedSum / totalWeight) : 0
+            out.push(Math.max(1, Math.min(999, blended)))
+        }
+    }
+    return UInt64.from(encodeStats(out))
+}
+
+/**
+ * Mirrors the contract's gather-time transform. Takes a deposit's entropy
+ * seed (bigint from deriveStratum), derives stats via weibull hashing, and
+ * returns a UInt64 whose bit-packed form matches what the contract writes
+ * to cargo_item.stats on gather.
+ *
+ * Use this whenever off-chain code simulates a gather (testmap, player
+ * scanners that project cargo outcomes) and needs a value that matches
+ * what on-chain cargo would carry.
+ */
+export function encodeGatheredCargoStats(depositSeed: bigint): UInt64 {
+    const raw = deriveResourceStats(depositSeed)
+    return UInt64.from(encodeStats([raw.stat1, raw.stat2, raw.stat3]))
+}

package/src/derivation/index.ts

@@ -0,0 +1,30 @@
+export {deriveStratum, deriveResourceStats} from './stratum'
+export type {StratumInfo, ResourceStats} from './stratum'
+export {deriveLocationSize} from './location-size'
+export {
+    getEligibleResources,
+    getResourceWeight,
+    getLocationCandidates,
+    getDepthThreshold,
+    getResourceTier,
+    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 {RESERVE_TIERS, TIER_ROLL_MAX, rollTier, rollWithinTier} from './tiers'
+export type {ReserveTier, TierRange} from './tiers'
+
+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,112 @@
+import {getItem} from '../market/items'
+
+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.001 * 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
+
+export function getDepthThreshold(tier: number): number {
+    switch (tier) {
+        case 1:
+            return DEPTH_THRESHOLD_T1
+        case 2:
+            return DEPTH_THRESHOLD_T2
+        case 3:
+            return DEPTH_THRESHOLD_T3
+        case 4:
+            return DEPTH_THRESHOLD_T4
+        default:
+            return DEPTH_THRESHOLD_T5
+    }
+}
+
+export function getResourceTier(itemId: number): number {
+    return getItem(itemId).tier
+}
+
+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 1:
+            if (stratum < 2000) return 100
+            if (stratum < 10000) return 80
+            if (stratum < 30000) return 50
+            return 30
+        case 2:
+            if (depthAbove < 3000) return 40
+            if (depthAbove < 8000) return 60
+            return 50
+        case 3:
+            if (depthAbove < 5000) return 20
+            if (depthAbove < 15000) return 35
+            return 40
+        case 4:
+            if (depthAbove < 10000) return 10
+            if (depthAbove < 25000) return 20
+            return 30
+        default:
+            return 10
+    }
+}
+
+const ASTEROID_RESOURCES = [101, 102, 103, 201, 202]
+const NEBULA_RESOURCES = [202, 203, 301, 302, 303]
+const GAS_GIANT_RESOURCES = [301, 302, 303, 401, 501]
+const ROCKY_RESOURCES = [101, 102, 103, 401, 402, 403, 503]
+const TERRESTRIAL_RESOURCES = [201, 202, 401, 402, 501, 502, 503]
+const ICY_RESOURCES = [101, 301, 302, 401, 403, 501, 502]
+const OCEAN_RESOURCES = [201, 203, 301, 303, 501, 502, 503]
+const INDUSTRIAL_RESOURCES = [101, 102, 103, 201, 203, 402, 403]
+
+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
+    })
+}

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 ORE_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 CRYSTAL_STATS: StatDefinition[] = [
+    {
+        key: 'conductivity',
+        label: 'Conductivity',
+        abbreviation: 'CON',
+        purpose: 'Efficiency of energy/signal transfer through crystalline lattice',
+    },
+    {
+        key: 'resonance',
+        label: 'Resonance',
+        abbreviation: 'RES',
+        purpose: 'Frequency tuning and piezoelectric response — storage and amplification',
+    },
+    {
+        key: 'reflectivity',
+        label: 'Reflectivity',
+        abbreviation: 'REF',
+        purpose: 'Optical refraction and reflection — lenses, mirrors, focus',
+    },
+]
+
+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 REGOLITH_STATS: StatDefinition[] = [
+    {
+        key: 'composition',
+        label: 'Composition',
+        abbreviation: 'COM',
+        purpose: 'Mineral/metal mix — drives sensor, chip, and optic crafting quality',
+    },
+    {
+        key: 'hardness',
+        label: 'Hardness',
+        abbreviation: 'HRD',
+        purpose: 'Particle hardness — cutting surfaces, abrasives, wear resistance',
+    },
+    {
+        key: 'fineness',
+        label: 'Fineness',
+        abbreviation: 'FIN',
+        purpose: 'Grain size — fine powder for smooth composites and sintering',
+    },
+]
+
+const BIOMASS_STATS: StatDefinition[] = [
+    {
+        key: 'plasticity',
+        label: 'Plasticity',
+        abbreviation: 'PLA',
+        purpose: 'Flexibility and deformation under load',
+    },
+    {
+        key: 'insulation',
+        label: 'Insulation',
+        abbreviation: 'INS',
+        purpose: 'Thermal and electrical blocking capacity',
+    },
+    {
+        key: 'saturation',
+        label: 'Saturation',
+        abbreviation: 'SAT',
+        purpose: 'Concentration of useful organic compounds per unit',
+    },
+]
+
+const STAT_MAP: Record<ResourceCategory, StatDefinition[]> = {
+    ore: ORE_STATS,
+    crystal: CRYSTAL_STATS,
+    gas: GAS_STATS,
+    regolith: REGOLITH_STATS,
+    biomass: BIOMASS_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],
+    }
+}