@shipload/sdk 2.0.0-rc2 → 2.0.0-rc20

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,287 @@
+import {UInt64} from '@wharfkit/antelope'
+import type {ResourceCategory} from '../types'
+import {
+    entityRecipes,
+    getComponentById,
+    getEntityRecipe,
+    getEntityRecipeByItemId,
+    getModuleRecipe,
+    moduleRecipes,
+} from '../data/recipes'
+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 mapStatsToKeys(stats: bigint, statDefs: {key: string}[]): Record<string, number> {
+    const values = decodeStats(stats, 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, stats: bigint): Record<string, number> {
+    const comp = getComponentById(itemId)
+    if (comp) return mapStatsToKeys(stats, comp.stats)
+
+    const entityRecipe = entityRecipes.find((r) => r.packedItemId === itemId)
+    if (entityRecipe) return mapStatsToKeys(stats, entityRecipe.stats)
+
+    const moduleRecipe = moduleRecipes.find((r) => r.itemId === itemId)
+    if (moduleRecipe) return mapStatsToKeys(stats, 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, 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 const categoryItemMass: Record<string, number> = {
+    ore: 30000,
+    crystal: 40000,
+    gas: 15000,
+    regolith: 22000,
+    biomass: 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; 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 component = getComponentById(outputItemId)
+    if (component) {
+        const categoryStacks: CategoryStacks[] = []
+        for (const slot of slotInputs) {
+            if (!slot.category) continue
+            const slotIsComponent = getComponentById(slot.itemId) !== undefined
+            const stacks: StackInput[] = slot.stacks.map((s) => ({
+                quantity: s.quantity,
+                stats: slotIsComponent
+                    ? decodeCraftedItemStats(slot.itemId, s.stats)
+                    : decodeRawStackToCategoryStats(s.stats, slot.category!),
+            }))
+            categoryStacks.push({category: slot.category, stacks})
+        }
+        const stats = computeComponentStats(outputItemId, categoryStacks)
+        const ordered = component.stats.map((statDef) => {
+            const found = stats.find((s) => s.key === statDef.key)
+            return found ? found.value : 0
+        })
+        return UInt64.from(encodeStats(ordered))
+    }
+
+    const entityRecipe = getEntityRecipeByItemId(outputItemId)
+    if (entityRecipe) {
+        const componentStacks: Record<number, {quantity: number; stats: Record<string, number>}[]> =
+            {}
+        for (const slot of slotInputs) {
+            if (slot.category !== undefined) {
+                throw new Error(
+                    `entity recipe ${entityRecipe.id} expects component inputs but slot itemId=${slot.itemId} has category=${slot.category}`
+                )
+            }
+            const list = (componentStacks[slot.itemId] ??= [])
+            for (const s of slot.stacks) {
+                list.push({
+                    quantity: s.quantity,
+                    stats: decodeCraftedItemStats(slot.itemId, s.stats),
+                })
+            }
+        }
+        const stats = computeEntityStats(entityRecipe.id, componentStacks)
+        const ordered = entityRecipe.stats.map((statDef) => {
+            const found = stats.find((s) => s.key === statDef.key)
+            return found ? found.value : 0
+        })
+        return UInt64.from(encodeStats(ordered))
+    }
+
+    throw new Error(`computeCraftedOutputStats: no recipe found for outputItemId=${outputItemId}`)
+}
+
+/**
+ * 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,136 @@
+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.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
+
+interface ResourceEntry {
+    id: number
+    tier: ResourceTier
+}
+
+const RESOURCE_CATALOG: ResourceEntry[] = [
+    {id: 101, tier: 't1'},
+    {id: 102, tier: 't2'},
+    {id: 103, tier: 't3'},
+    {id: 201, tier: 't1'},
+    {id: 202, tier: 't2'},
+    {id: 203, tier: 't3'},
+    {id: 301, tier: 't1'},
+    {id: 302, tier: 't2'},
+    {id: 303, tier: 't3'},
+    {id: 401, tier: 't1'},
+    {id: 402, tier: 't2'},
+    {id: 403, tier: 't3'},
+    {id: 501, tier: 't1'},
+    {id: 502, tier: 't2'},
+    {id: 503, 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 = [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],
+    }
+}