@shipload/sdk 2.0.0-rc14 → 2.0.0-rc15

package/src/derivation/stats.ts

@@ -8,7 +8,7 @@ export interface StatDefinition {
     inverted?: boolean
 }
 
-const METAL_STATS: StatDefinition[] = [
+const ORE_STATS: StatDefinition[] = [
     {
         key: 'strength',
         label: 'Strength',
@@ -30,24 +30,24 @@ const METAL_STATS: StatDefinition[] = [
     },
 ]
 
-const PRECIOUS_STATS: StatDefinition[] = [
+const CRYSTAL_STATS: StatDefinition[] = [
     {
         key: 'conductivity',
         label: 'Conductivity',
         abbreviation: 'CON',
-        purpose: 'Efficiency of energy/signal transfer',
+        purpose: 'Efficiency of energy/signal transfer through crystalline lattice',
     },
     {
-        key: 'ductility',
-        label: 'Ductility',
-        abbreviation: 'DUC',
-        purpose: 'Ability to be worked into fine, precise shapes',
+        key: 'resonance',
+        label: 'Resonance',
+        abbreviation: 'RES',
+        purpose: 'Frequency tuning and piezoelectric response — storage and amplification',
     },
     {
         key: 'reflectivity',
         label: 'Reflectivity',
         abbreviation: 'REF',
-        purpose: 'Surface quality for heat management and precision optics',
+        purpose: 'Optical refraction and reflection — lenses, mirrors, focus',
     },
 ]
 
@@ -72,54 +72,54 @@ const GAS_STATS: StatDefinition[] = [
     },
 ]
 
-const MINERAL_STATS: StatDefinition[] = [
+const REGOLITH_STATS: StatDefinition[] = [
     {
-        key: 'resonance',
-        label: 'Resonance',
-        abbreviation: 'RES',
-        purpose: 'Energy field interaction — storage, focusing, projection',
+        key: 'composition',
+        label: 'Composition',
+        abbreviation: 'COM',
+        purpose: 'Mineral/metal mix — drives sensor, chip, and optic crafting quality',
     },
     {
         key: 'hardness',
         label: 'Hardness',
         abbreviation: 'HRD',
-        purpose: 'Resistance to wear — cutting surfaces, penetration',
+        purpose: 'Particle hardness — cutting surfaces, abrasives, wear resistance',
     },
     {
-        key: 'clarity',
-        label: 'Clarity',
-        abbreviation: 'CLR',
-        purpose: 'Crystalline perfection — precision optics',
+        key: 'fineness',
+        label: 'Fineness',
+        abbreviation: 'FIN',
+        purpose: 'Grain size — fine powder for smooth composites and sintering',
     },
 ]
 
-const ORGANIC_STATS: StatDefinition[] = [
+const BIOMASS_STATS: StatDefinition[] = [
     {
         key: 'plasticity',
         label: 'Plasticity',
         abbreviation: 'PLA',
-        purpose: 'Ease of reshaping — speeds processing',
+        purpose: 'Flexibility and deformation under load',
     },
     {
         key: 'insulation',
         label: 'Insulation',
         abbreviation: 'INS',
-        purpose: 'Energy containment — reduces energy loss',
+        purpose: 'Thermal and electrical blocking capacity',
     },
     {
-        key: 'purity',
-        label: 'Purity',
-        abbreviation: 'PUR',
-        purpose: 'Biological cleanliness — better composites and lubricants',
+        key: 'saturation',
+        label: 'Saturation',
+        abbreviation: 'SAT',
+        purpose: 'Concentration of useful organic compounds per unit',
     },
 ]
 
 const STAT_MAP: Record<ResourceCategory, StatDefinition[]> = {
-    metal: METAL_STATS,
-    precious: PRECIOUS_STATS,
+    ore: ORE_STATS,
+    crystal: CRYSTAL_STATS,
     gas: GAS_STATS,
-    mineral: MINERAL_STATS,
-    organic: ORGANIC_STATS,
+    regolith: REGOLITH_STATS,
+    biomass: BIOMASS_STATS,
 }
 
 export function getStatDefinitions(category: ResourceCategory): StatDefinition[] {

package/src/entities/container.ts

@@ -76,12 +76,12 @@ export function computeContainerCapabilities(stats: Record<string, number>): {
 } {
     const density = stats['density'] ?? 500
     const strength = stats['strength'] ?? 500
-    const ductility = stats['ductility'] ?? 500
-    const purity = stats['purity'] ?? 500
+    const fineness = stats['fineness'] ?? 500
+    const saturation = stats['saturation'] ?? 500
 
     const hullmass = 25000 + 75 * density
 
-    const statSum = strength + ductility + purity
+    const statSum = strength + fineness + saturation
     const exponent = statSum / 2997
     const capacity = Math.floor(1000000 * Math.pow(10, exponent))
 
@@ -94,12 +94,12 @@ export function computeContainerT2Capabilities(stats: Record<string, number>): {
 } {
     const strength = stats['strength'] ?? 0
     const density = stats['density'] ?? 0
-    const ductility = stats['ductility'] ?? 0
-    const purity = stats['purity'] ?? 0
+    const fineness = stats['fineness'] ?? 0
+    const saturation = stats['saturation'] ?? 0
 
     const hullmass = 20000 + 50 * density
 
-    const statSum = strength + ductility + purity
+    const statSum = strength + fineness + saturation
     const exponent = statSum / 2500
     const capacity = Math.floor(1500000 * Math.pow(10, exponent))
 

package/src/entities/ship-deploy.ts

@@ -15,11 +15,11 @@ export function computeShipHullCapabilities(stats: Record<string, number>): {
 } {
     const density = stats.density ?? 500
     const strength = stats.strength ?? 500
-    const ductility = stats.ductility ?? 500
-    const purity = stats.purity ?? 500
+    const fineness = stats.fineness ?? 500
+    const saturation = stats.saturation ?? 500
 
     const hullmass = 25000 + 75 * density
-    const statSum = strength + ductility + purity
+    const statSum = strength + fineness + saturation
     const exponent = statSum / 2997.0
     const capacity = Math.floor(1000000 * Math.pow(10, exponent))
 
@@ -44,11 +44,11 @@ export function computeGeneratorCapabilities(stats: Record<string, number>): {
     recharge: number
 } {
     const res = stats.resonance ?? 500
-    const clr = stats.clarity ?? 500
+    const ref = stats.reflectivity ?? 500
 
     return {
         capacity: 300 + Math.floor(res / 6),
-        recharge: 1 + Math.floor((clr * 3) / 1000),
+        recharge: 1 + Math.floor((ref * 3) / 1000),
     }
 }
 
@@ -76,11 +76,11 @@ export function computeLoaderCapabilities(stats: Record<string, number>): {
     thrust: number
     quantity: number
 } {
-    const duc = stats.ductility ?? 500
+    const fin = stats.fineness ?? 500
     const pla = stats.plasticity ?? 500
 
     return {
-        mass: Math.max(200, 2000 - Math.floor(duc * 2)),
+        mass: Math.max(200, 2000 - Math.floor(fin * 2)),
         thrust: 1 + Math.floor(pla / 500),
         quantity: 1,
     }
@@ -91,11 +91,11 @@ export function computeManufacturingCapabilities(stats: Record<string, number>):
     drain: number
 } {
     const rea = stats.reactivity ?? 500
-    const clr = stats.clarity ?? 500
+    const com = stats.composition ?? 500
 
     return {
         speed: 100 + Math.floor((rea * 4) / 5),
-        drain: Math.max(5, 30 - Math.floor(clr / 33)),
+        drain: Math.max(5, 30 - Math.floor(com / 33)),
     }
 }
 
@@ -106,12 +106,12 @@ export function computeHaulerCapabilities(stats: Record<string, number>): {
 } {
     const res = stats.resonance ?? 500
     const con = stats.conductivity ?? 500
-    const clr = stats.clarity ?? 500
+    const ref = stats.reflectivity ?? 500
 
     return {
         capacity: Math.max(1, 1 + Math.floor(res / 400)),
         efficiency: 2000 + con * 6,
-        drain: Math.max(3, 15 - Math.floor(clr / 80)),
+        drain: Math.max(3, 15 - Math.floor(ref / 80)),
     }
 }
 
@@ -122,10 +122,10 @@ export function computeStorageCapabilities(
     capacityBonus: number
 } {
     const strength = stats.strength ?? 500
-    const ductility = stats.ductility ?? 500
-    const purity = stats.purity ?? 500
+    const fineness = stats.fineness ?? 500
+    const saturation = stats.saturation ?? 500
 
-    const statSum = strength + ductility + purity
+    const statSum = strength + fineness + saturation
     const capacityBonus = Math.floor(
         (baseCapacity * (10 + Math.floor((statSum * 10) / 2997))) / 100
     )
@@ -139,11 +139,11 @@ export function computeWarehouseHullCapabilities(stats: Record<string, number>):
 } {
     const density = stats.density ?? 500
     const strength = stats.strength ?? 500
-    const ductility = stats.ductility ?? 500
-    const purity = stats.purity ?? 500
+    const fineness = stats.fineness ?? 500
+    const saturation = stats.saturation ?? 500
 
     const hullmass = 25000 + 75 * density
-    const statSum = strength + ductility + purity
+    const statSum = strength + fineness + saturation
     const exponent = statSum / 2997.0
     const capacity = Math.floor(20000000 * Math.pow(10, exponent))
 

package/src/format.ts

@@ -0,0 +1,12 @@
+export function formatMass(kg: number): string {
+    const t = kg / 1000
+    const fixed = t.toFixed(2)
+    const trimmed = fixed.replace(/\.?0+$/, '')
+    return `${trimmed} t`
+}
+
+export function formatMassDelta(kg: number): string {
+    if (kg === 0) return '0 t'
+    const sign = kg > 0 ? '+' : '-'
+    return `${sign}${formatMass(Math.abs(kg))}`
+}

package/src/index-module.ts

@@ -329,3 +329,8 @@ export {
     ITEM_TYPE_ENTITY,
     itemTypeCode,
 } from './data/tiers'
+
+export {formatMass, formatMassDelta} from './format'
+
+export {displayName, describeItem} from './resolution/display-name'
+export type {DescribeOptions} from './resolution/display-name'

package/src/market/items.ts

@@ -35,7 +35,7 @@ function synthesizeItem(id: number, source: RecipeSource): Item {
         name: source.name,
         description: source.description,
         mass: source.mass,
-        category: 'metal',
+        category: 'ore',
         tier: 't1',
         color: source.color,
     })

package/src/nft/description.ts

@@ -43,27 +43,27 @@ export function computeBaseCapacityWarehouse(stats: bigint): number {
 export const computeEngineThrust = (vol: number): number => 400 + idiv(vol * 3, 4)
 export const computeEngineDrain = (thm: number): number => Math.max(30, 50 - idiv(thm, 70))
 export const computeGeneratorCap = (res: number): number => 300 + idiv(res, 6)
-export const computeGeneratorRech = (clr: number): number => 1 + idiv(clr * 3, 1000)
+export const computeGeneratorRech = (ref: number): number => 1 + idiv(ref * 3, 1000)
 export const computeGathererYield = (str: number): number => 200 + str
 export const computeGathererDrain = (con: number): number =>
     Math.max(250, 1250 - idiv(con * 25, 20))
 export const computeGathererDepth = (tol: number): number => 200 + idiv(tol * 3, 2)
 export const computeGathererSpeed = (ref: number): number => 100 + idiv(ref * 4, 5)
-export const computeLoaderMass = (duc: number): number => Math.max(200, 2000 - duc * 2)
+export const computeLoaderMass = (fin: number): number => Math.max(200, 2000 - fin * 2)
 export const computeLoaderThrust = (pla: number): number => 1 + idiv(pla, 500)
 export const computeCrafterSpeed = (rea: number): number => 100 + idiv(rea * 4, 5)
-export const computeCrafterDrain = (clr: number): number => Math.max(5, 30 - idiv(clr, 33))
+export const computeCrafterDrain = (com: number): number => Math.max(5, 30 - idiv(com, 33))
 
 export function entityDisplayName(itemId: number): string {
     switch (itemId) {
         case ITEM_SHIP_T1_PACKED:
-            return 'Ship T1'
+            return 'Ship'
         case ITEM_WAREHOUSE_T1_PACKED:
-            return 'Warehouse T1'
+            return 'Warehouse'
         case ITEM_CONTAINER_T1_PACKED:
-            return 'Container T1'
+            return 'Container'
         case ITEM_CONTAINER_T2_PACKED:
-            return 'Container T2'
+            return 'Container'
         default:
             return 'Entity'
     }
@@ -72,17 +72,17 @@ export function entityDisplayName(itemId: number): string {
 export function moduleDisplayName(itemId: number): string {
     switch (itemId) {
         case ITEM_ENGINE_T1:
-            return 'Engine T1'
+            return 'Engine'
         case ITEM_GENERATOR_T1:
-            return 'Generator T1'
+            return 'Generator'
         case ITEM_GATHERER_T1:
-            return 'Gatherer T1'
+            return 'Gatherer'
         case ITEM_LOADER_T1:
-            return 'Loader T1'
+            return 'Loader'
         case ITEM_MANUFACTURING_T1:
-            return 'Manufacturing T1'
+            return 'Manufacturing'
         case ITEM_STORAGE_T1:
-            return 'Storage T1'
+            return 'Storage'
         default:
             return 'Module'
     }
@@ -107,8 +107,8 @@ export function formatModuleLine(slot: number, itemId: number, stats: bigint): s
         }
         case MODULE_GENERATOR: {
             const res = decodeStat(stats, 0)
-            const clr = decodeStat(stats, 1)
-            out += `  Capacity ${computeGeneratorCap(res)}  Recharge ${computeGeneratorRech(clr)}`
+            const ref = decodeStat(stats, 1)
+            out += `  Capacity ${computeGeneratorCap(res)}  Recharge ${computeGeneratorRech(ref)}`
             break
         }
         case MODULE_GATHERER: {
@@ -122,22 +122,22 @@ export function formatModuleLine(slot: number, itemId: number, stats: bigint): s
             break
         }
         case MODULE_LOADER: {
-            const duc = decodeStat(stats, 0)
+            const fin = decodeStat(stats, 0)
             const pla = decodeStat(stats, 1)
-            out += `  Mass ${computeLoaderMass(duc)}  Thrust ${computeLoaderThrust(pla)}`
+            out += `  Mass ${computeLoaderMass(fin)}  Thrust ${computeLoaderThrust(pla)}`
             break
         }
         case MODULE_CRAFTER: {
             const rea = decodeStat(stats, 0)
-            const clr = decodeStat(stats, 1)
-            out += `  Speed ${computeCrafterSpeed(rea)}  Drain ${computeCrafterDrain(clr)}`
+            const com = decodeStat(stats, 1)
+            out += `  Speed ${computeCrafterSpeed(rea)}  Drain ${computeCrafterDrain(com)}`
             break
         }
         case MODULE_STORAGE: {
             const str = decodeStat(stats, 0)
-            const duc = decodeStat(stats, 1)
-            const pur = decodeStat(stats, 2)
-            const sum = str + duc + pur
+            const fin = decodeStat(stats, 2)
+            const sat = decodeStat(stats, 3)
+            const sum = str + fin + sat
             const pct = 10 + idiv(sum * 10, 2997)
             out += `  +${pct}% capacity`
             break

package/src/resolution/display-name.ts

@@ -0,0 +1,57 @@
+import type {ResolvedItem} from './resolve-item'
+import type {ResourceCategory} from '../types'
+import {formatMass as defaultFormatMass} from '../format'
+
+const TIER_ADJECTIVES: Record<number, string> = {
+    1: 'Crude',
+    2: 'Dense',
+    3: 'Pure',
+    4: 'Prime',
+    5: 'Pristine',
+    6: 'Radiant',
+    7: 'Exotic',
+    8: 'Mythic',
+    9: 'Cosmic',
+    10: 'Ascendant',
+}
+
+const CATEGORY_LABELS: Record<ResourceCategory, string> = {
+    ore: 'Ore',
+    crystal: 'Crystal',
+    gas: 'Gas',
+    regolith: 'Regolith',
+    biomass: 'Biomass',
+}
+
+function tierNumber(tier: string): number {
+    return Number(String(tier).replace(/^t/i, ''))
+}
+
+export function displayName(resolved: ResolvedItem): string {
+    if (resolved.itemType === 'resource') {
+        const tierNum = tierNumber(resolved.tier)
+        const adj = TIER_ADJECTIVES[tierNum] ?? 'Unknown'
+        const cat = resolved.category ? CATEGORY_LABELS[resolved.category] : 'Resource'
+        return `${adj} ${cat}`
+    }
+    return resolved.name
+}
+
+export interface DescribeOptions {
+    translate?: (key: string) => string
+    formatNumber?: (n: number) => string
+    formatMass?: (kg: number) => string
+}
+
+export function describeItem(resolved: ResolvedItem, opts?: DescribeOptions): string {
+    const massFmt = opts?.formatMass ?? defaultFormatMass
+    const mass = massFmt(resolved.mass)
+    const tier = `T${tierNumber(resolved.tier)}`
+    if (resolved.itemType === 'resource') {
+        const cat = resolved.category ? CATEGORY_LABELS[resolved.category] : 'Resource'
+        const header = `${tier} ${cat}`
+        const stats = resolved.stats?.map((s) => `${s.label} ${s.value}`).join(', ')
+        return [header, stats, mass].filter(Boolean).join(' · ')
+    }
+    return `${tier} ${resolved.name} · ${mass}`
+}

package/src/resolution/resolve-item.ts

@@ -117,14 +117,14 @@ function resolveComponent(id: number, stats?: UInt64Type): ResolvedItem {
     if (stats !== undefined) {
         const decoded = decodeCraftedItemStats(id, toBigStats(stats))
         resolvedStats = Object.entries(decoded).map(([key, value]) => {
-            const allDefs = getStatDefinitions('metal')
-                .concat(getStatDefinitions('precious'))
+            const allDefs = getStatDefinitions('ore')
+                .concat(getStatDefinitions('crystal'))
                 .concat(getStatDefinitions('gas'))
-                .concat(getStatDefinitions('mineral'))
-                .concat(getStatDefinitions('organic'))
+                .concat(getStatDefinitions('regolith'))
+                .concat(getStatDefinitions('biomass'))
             const def = allDefs.find((d) => d.key === key)
             const statDef = comp.stats.find((s) => s.key === key)
-            const cat = (statDef?.source ?? 'metal') as ResourceCategory
+            const cat = (statDef?.source ?? 'ore') as ResourceCategory
             return {
                 key,
                 label: def?.label ?? key,
@@ -219,9 +219,9 @@ function computeCapabilityGroup(
         }
         case MODULE_STORAGE: {
             const str = stats.strength ?? 500
-            const duc = stats.ductility ?? 500
-            const pur = stats.purity ?? 500
-            const statSum = str + duc + pur
+            const fin = stats.fineness ?? 500
+            const sat = stats.saturation ?? 500
+            const statSum = str + fin + sat
             const pct = 10 + Math.floor((statSum * 10) / 2997)
             return {capability: 'Storage', attributes: [{label: 'Capacity Bonus', value: pct}]}
         }

package/src/types.ts

@@ -113,7 +113,7 @@ export interface Distance {
     distance: UInt16
 }
 
-export type ResourceCategory = 'metal' | 'precious' | 'gas' | 'mineral' | 'organic'
+export type ResourceCategory = 'ore' | 'crystal' | 'gas' | 'regolith' | 'biomass'
 export type ResourceTier = 't1' | 't2' | 't3' | 't4' | 't5'
 
 @Struct.type('item')