@shipload/sdk 1.0.0-next.2 → 1.0.0-next.20

package/src/nft/atomicdata.ts

@@ -0,0 +1,130 @@
+export interface SchemaField {
+    name: string
+    type: string
+}
+
+export type RawData =
+    | Uint8Array
+    | string
+    | number[]
+    | {immutable_serialized_data: Uint8Array | string | number[]}
+
+export function deserializeAtomicData(
+    data: RawData,
+    schema: SchemaField[]
+): Record<string, unknown> {
+    let rawData: Uint8Array | string | number[]
+    if (data && typeof data === 'object' && 'immutable_serialized_data' in (data as object)) {
+        rawData = (data as {immutable_serialized_data: Uint8Array | string | number[]})
+            .immutable_serialized_data
+    } else {
+        rawData = data as Uint8Array | string | number[]
+    }
+
+    let bytes: Uint8Array
+    if (typeof rawData === 'string') {
+        const hex = rawData
+        bytes = new Uint8Array(hex.length / 2)
+        for (let i = 0; i < hex.length; i += 2) {
+            bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16)
+        }
+    } else if (Array.isArray(rawData)) {
+        bytes = new Uint8Array(rawData)
+    } else {
+        bytes = rawData
+    }
+
+    let offset = 0
+
+    function readVarint(): number {
+        let result = 0
+        let multiplier = 1
+        while (bytes[offset] >= 128) {
+            result += (bytes[offset] - 128) * multiplier
+            offset++
+            multiplier *= 128
+        }
+        result += bytes[offset] * multiplier
+        offset++
+        return result
+    }
+
+    function readVarint64(): bigint {
+        let result = 0n
+        let multiplier = 1n
+        while (bytes[offset] >= 128) {
+            result += BigInt(bytes[offset] - 128) * multiplier
+            offset++
+            multiplier *= 128n
+        }
+        result += BigInt(bytes[offset]) * multiplier
+        offset++
+        return result
+    }
+
+    function readZigzagInt64(): bigint {
+        const unsigned = readVarint64()
+        if (unsigned % 2n === 0n) {
+            return unsigned / 2n
+        } else {
+            return -(unsigned / 2n) - 1n
+        }
+    }
+
+    function readString(): string {
+        const length = readVarint()
+        const str = new TextDecoder().decode(bytes.slice(offset, offset + length))
+        offset += length
+        return str
+    }
+
+    const RESERVED = 4
+    const result: Record<string, unknown> = {}
+
+    while (offset < bytes.length) {
+        const fieldIndex = readVarint() - RESERVED
+        const field = schema[fieldIndex]
+        if (!field) break
+
+        switch (field.type) {
+            case 'uint16':
+                result[field.name] = readVarint()
+                break
+            case 'uint32':
+                result[field.name] = readVarint()
+                break
+            case 'uint64':
+                result[field.name] = readVarint64()
+                break
+            case 'int32':
+                result[field.name] = readZigzagInt64()
+                break
+            case 'int64':
+                result[field.name] = readZigzagInt64()
+                break
+            case 'string':
+            case 'image':
+            case 'ipfs':
+                result[field.name] = readString()
+                break
+            case 'uint16[]': {
+                const len = readVarint()
+                const arr: number[] = []
+                for (let i = 0; i < len; i++) arr.push(readVarint())
+                result[field.name] = arr
+                break
+            }
+            case 'uint64[]': {
+                const len = readVarint()
+                const arr: bigint[] = []
+                for (let i = 0; i < len; i++) arr.push(readVarint64())
+                result[field.name] = arr
+                break
+            }
+            default:
+                throw new Error(`Unknown type: ${field.type}`)
+        }
+    }
+
+    return result
+}

package/src/nft/buildImmutableData.ts

@@ -0,0 +1,319 @@
+import {Serializer} from '@wharfkit/antelope'
+import {getItem} from '../data/catalog'
+import {
+    getModuleCapabilityType,
+    MODULE_CRAFTER,
+    MODULE_ENGINE,
+    MODULE_GATHERER,
+    MODULE_GENERATOR,
+    MODULE_HAULER,
+    MODULE_LOADER,
+    MODULE_STORAGE,
+    MODULE_WARP,
+} from '../capabilities/modules'
+import {decodeStat, decodeCraftedItemStats} from '../derivation/crafting'
+import {getStatDefinitions} from '../derivation/stats'
+import type {ResourceCategory} from '../types'
+import {Types as ServerTypes} from '../contracts/server'
+import {
+    buildEntityDescription,
+    computeCrafterDrain,
+    computeCrafterSpeed,
+    computeEngineDrain,
+    computeEngineThrust,
+    computeGathererDepth,
+    computeGathererDrain,
+    computeGathererYield,
+    computeGeneratorCap,
+    computeGeneratorRech,
+    computeHaulerCapacity,
+    computeHaulerDrain,
+    computeHaulerEfficiency,
+    computeLoaderMass,
+    computeLoaderThrust,
+    computeWarpRange,
+} from './description'
+
+export type AtomicAttributeType =
+    | 'string'
+    | 'uint8'
+    | 'uint16'
+    | 'uint32'
+    | 'uint64'
+    | 'int32'
+    | 'image'
+    | 'ipfs'
+    | 'UINT16_VEC'
+    | 'UINT64_VEC'
+
+export interface ImmutableEntry {
+    first: string
+    second: [AtomicAttributeType, unknown]
+}
+
+export interface ImmutableModuleSlot {
+    type?: number | string | bigint
+    installed?: {item_id: number | string | bigint; stats: number | string | bigint}
+}
+
+export function moduleSlotsForImmutable(
+    modules: ServerTypes.module_entry[]
+): ImmutableModuleSlot[] {
+    return modules.map((m) => ({
+        type: Number(m.type.toString()),
+        installed: m.installed
+            ? {
+                  item_id: Number(m.installed.item_id.toString()),
+                  stats: BigInt(m.installed.stats.toString()),
+              }
+            : undefined,
+    }))
+}
+
+const IMAGE_HOST_URL = 'https://item.shiploadgame.com/item'
+
+function bytesToBase64Url(bytes: Uint8Array): string {
+    let binary = ''
+    for (let i = 0; i < bytes.byteLength; i++) binary += String.fromCharCode(bytes[i]!)
+    const b64 = btoa(binary)
+    return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}
+
+export function computeNftImageUrl(
+    item: {item_id: number; stats: bigint; modules: ImmutableModuleSlot[]; quantity: number},
+    originX: number,
+    originY: number
+): string {
+    const payload = ServerTypes.nft_item_payload.from({
+        item: {
+            item_id: item.item_id,
+            stats: String(item.stats),
+            modules: item.modules,
+            quantity: item.quantity,
+        },
+        location: {x: String(originX), y: String(originY)},
+    })
+    const bytes = Serializer.encode({object: payload}).array
+    return `${IMAGE_HOST_URL}/${bytesToBase64Url(bytes)}.png`
+}
+
+function commonBaseImmutable(
+    quantity: number,
+    stats: bigint,
+    originX: number,
+    originY: number,
+    img: string
+): ImmutableEntry[] {
+    return [
+        {first: 'quantity', second: ['uint32', quantity]},
+        {first: 'stats', second: ['uint64', String(stats)]},
+        {first: 'origin_x', second: ['int32', originX]},
+        {first: 'origin_y', second: ['int32', originY]},
+        {first: 'img', second: ['string', img]},
+        {first: 'deposit_amount', second: ['uint64', '0']},
+        {first: 'deposit_token', second: ['uint64', '0']},
+        {first: 'deposit_symbol', second: ['uint64', '0']},
+    ]
+}
+
+export function buildResourceImmutable(
+    itemId: number,
+    quantity: number,
+    stats: bigint,
+    originX: number,
+    originY: number
+): ImmutableEntry[] {
+    const item = getItem(itemId)
+    const cat = item.category
+    if (!cat) throw new Error(`Resource item ${itemId} has no category`)
+    const definitions = getStatDefinitions(cat as ResourceCategory)
+    const img = computeNftImageUrl(
+        {item_id: itemId, stats, modules: [], quantity},
+        originX,
+        originY
+    )
+    const base = commonBaseImmutable(quantity, stats, originX, originY, img)
+    base.push({first: definitions[0].key, second: ['uint16', decodeStat(stats, 0)]})
+    base.push({first: definitions[1].key, second: ['uint16', decodeStat(stats, 1)]})
+    base.push({first: definitions[2].key, second: ['uint16', decodeStat(stats, 2)]})
+    return base
+}
+
+export function buildComponentImmutable(
+    itemId: number,
+    quantity: number,
+    stats: bigint,
+    originX: number,
+    originY: number
+): ImmutableEntry[] {
+    const img = computeNftImageUrl(
+        {item_id: itemId, stats, modules: [], quantity},
+        originX,
+        originY
+    )
+    const base = commonBaseImmutable(quantity, stats, originX, originY, img)
+    const decoded = decodeCraftedItemStats(itemId, stats)
+    for (const [key, value] of Object.entries(decoded)) {
+        base.push({first: key, second: ['uint16', value]})
+    }
+    return base
+}
+
+export function buildModuleImmutable(
+    itemId: number,
+    quantity: number,
+    stats: bigint,
+    originX: number,
+    originY: number
+): ImmutableEntry[] {
+    const img = computeNftImageUrl(
+        {item_id: itemId, stats, modules: [], quantity},
+        originX,
+        originY
+    )
+    const base = commonBaseImmutable(quantity, stats, originX, originY, img)
+    const subtype = getModuleCapabilityType(itemId)
+    const item = getItem(itemId)
+    switch (subtype) {
+        case MODULE_ENGINE: {
+            const vol = decodeStat(stats, 0)
+            const thm = decodeStat(stats, 1)
+            base.push({first: 'volatility', second: ['uint16', vol]})
+            base.push({first: 'thermal', second: ['uint16', thm]})
+            base.push({first: 'thrust', second: ['uint32', computeEngineThrust(vol)]})
+            base.push({first: 'drain', second: ['uint16', computeEngineDrain(thm)]})
+            break
+        }
+        case MODULE_GENERATOR: {
+            const res = decodeStat(stats, 0)
+            const ref = decodeStat(stats, 1)
+            base.push({first: 'resonance', second: ['uint16', res]})
+            base.push({first: 'reflectivity', second: ['uint16', ref]})
+            base.push({first: 'capacity', second: ['uint16', computeGeneratorCap(res)]})
+            base.push({first: 'recharge', second: ['uint16', computeGeneratorRech(ref)]})
+            break
+        }
+        case MODULE_GATHERER: {
+            const str = decodeStat(stats, 0)
+            const tol = decodeStat(stats, 1)
+            const con = decodeStat(stats, 2)
+            const ref = decodeStat(stats, 3)
+            base.push({first: 'strength', second: ['uint16', str]})
+            base.push({first: 'tolerance', second: ['uint16', tol]})
+            base.push({first: 'conductivity', second: ['uint16', con]})
+            base.push({first: 'reflectivity', second: ['uint16', ref]})
+            base.push({first: 'yield', second: ['uint16', computeGathererYield(str)]})
+            base.push({first: 'drain', second: ['uint16', computeGathererDrain(con)]})
+            base.push({first: 'depth', second: ['uint16', computeGathererDepth(tol, item.tier)]})
+            break
+        }
+        case MODULE_LOADER: {
+            const fin = decodeStat(stats, 0)
+            const pla = decodeStat(stats, 1)
+            base.push({first: 'fineness', second: ['uint16', fin]})
+            base.push({first: 'plasticity', second: ['uint16', pla]})
+            base.push({first: 'mass', second: ['uint32', computeLoaderMass(fin)]})
+            base.push({first: 'thrust', second: ['uint16', computeLoaderThrust(pla)]})
+            break
+        }
+        case MODULE_WARP: {
+            const res = decodeStat(stats, 0)
+            base.push({first: 'resonance', second: ['uint16', res]})
+            base.push({first: 'range', second: ['uint32', computeWarpRange(res)]})
+            break
+        }
+        case MODULE_CRAFTER: {
+            const rea = decodeStat(stats, 0)
+            const com = decodeStat(stats, 1)
+            base.push({first: 'reactivity', second: ['uint16', rea]})
+            base.push({first: 'composition', second: ['uint16', com]})
+            base.push({first: 'speed', second: ['uint16', computeCrafterSpeed(rea)]})
+            base.push({first: 'drain', second: ['uint16', computeCrafterDrain(com)]})
+            break
+        }
+        case MODULE_STORAGE: {
+            const str = decodeStat(stats, 0)
+            const fin = decodeStat(stats, 1)
+            const sat = decodeStat(stats, 2)
+            const sum = str + fin + sat
+            base.push({first: 'strength', second: ['uint16', str]})
+            base.push({first: 'fineness', second: ['uint16', fin]})
+            base.push({first: 'saturation', second: ['uint16', sat]})
+            base.push({
+                first: 'capacity_bonus_pct',
+                second: ['uint16', 10 + Math.floor((sum * 10) / 2997)],
+            })
+            break
+        }
+        case MODULE_HAULER: {
+            const res = decodeStat(stats, 0)
+            const con = decodeStat(stats, 1)
+            const ref = decodeStat(stats, 2)
+            base.push({first: 'resonance', second: ['uint16', res]})
+            base.push({first: 'conductivity', second: ['uint16', con]})
+            base.push({first: 'reflectivity', second: ['uint16', ref]})
+            base.push({first: 'capacity', second: ['uint8', computeHaulerCapacity(res)]})
+            base.push({first: 'efficiency', second: ['uint16', computeHaulerEfficiency(con)]})
+            base.push({first: 'drain', second: ['uint16', computeHaulerDrain(ref)]})
+            break
+        }
+    }
+    return base
+}
+
+export function buildEntityImmutable(
+    itemId: number,
+    quantity: number,
+    stats: bigint,
+    originX: number,
+    originY: number,
+    modules: ImmutableModuleSlot[]
+): ImmutableEntry[] {
+    const moduleItems: number[] = []
+    const moduleStats: string[] = []
+    for (const m of modules) {
+        if (m.installed) {
+            moduleItems.push(Number(m.installed.item_id))
+            moduleStats.push(String(m.installed.stats))
+        } else {
+            moduleItems.push(0)
+            moduleStats.push('0')
+        }
+    }
+    const img = computeNftImageUrl({item_id: itemId, stats, modules, quantity}, originX, originY)
+    const base = commonBaseImmutable(quantity, stats, originX, originY, img)
+    base.push({first: 'module_items', second: ['UINT16_VEC', moduleItems]})
+    base.push({first: 'module_stats', second: ['UINT64_VEC', moduleStats]})
+    const description = buildEntityDescription(
+        itemId,
+        stats,
+        moduleItems,
+        moduleStats.map((s) => BigInt(s))
+    )
+    base.push({first: 'description', second: ['string', description]})
+    return base
+}
+
+export function buildImmutableData(
+    itemId: number,
+    quantity: number,
+    stats: bigint,
+    originX: number,
+    originY: number,
+    modules: ImmutableModuleSlot[] = []
+): ImmutableEntry[] {
+    const item = getItem(itemId)
+    if (item.type === 'resource') {
+        return buildResourceImmutable(itemId, quantity, stats, originX, originY)
+    }
+    if (item.type === 'component') {
+        return buildComponentImmutable(itemId, quantity, stats, originX, originY)
+    }
+    if (item.type === 'module') {
+        return buildModuleImmutable(itemId, quantity, stats, originX, originY)
+    }
+    if (item.type === 'entity') {
+        return buildEntityImmutable(itemId, quantity, stats, originX, originY, modules)
+    }
+    throw new Error(`Unsupported item type for wrap: ${item.type}`)
+}

package/src/nft/description.ts

@@ -4,22 +4,29 @@ import {
     MODULE_ENGINE,
     MODULE_GATHERER,
     MODULE_GENERATOR,
+    MODULE_HAULER,
     MODULE_LOADER,
     MODULE_STORAGE,
+    MODULE_WARP,
 } from '../capabilities/modules'
 import {
     ITEM_CONTAINER_T1_PACKED,
     ITEM_CONTAINER_T2_PACKED,
     ITEM_CRAFTER_T1,
     ITEM_ENGINE_T1,
+    ITEM_EXTRACTOR_T1_PACKED,
     ITEM_GATHERER_T1,
     ITEM_GENERATOR_T1,
+    ITEM_HAULER_T1,
     ITEM_LOADER_T1,
     ITEM_SHIP_T1_PACKED,
     ITEM_STORAGE_T1,
     ITEM_WAREHOUSE_T1_PACKED,
+    ITEM_WARP_T1,
 } from '../data/item-ids'
 import {decodeStat} from '../derivation/crafting'
+import {gathererDepthForTier} from '../derivation/capabilities'
+import {getItem} from '../data/catalog'
 
 function idiv(a: number, b: number): number {
     return Math.floor(a / b)
@@ -27,32 +34,36 @@ function idiv(a: number, b: number): number {
 
 export function computeBaseHullmass(stats: bigint): number {
     const density = decodeStat(stats, 1)
-    return 25000 + 75 * density
+    return 100000 - 75 * density
 }
 
 export function computeBaseCapacityShip(stats: bigint): number {
     const s = decodeStat(stats, 0) + decodeStat(stats, 2) + decodeStat(stats, 3)
-    return Math.floor(1_000_000 * 10 ** (s / 2997))
+    return Math.floor(5_000_000 * 6 ** (s / 2997))
 }
 
 export function computeBaseCapacityWarehouse(stats: bigint): number {
     const s = decodeStat(stats, 0) + decodeStat(stats, 2) + decodeStat(stats, 3)
-    return Math.floor(20_000_000 * 10 ** (s / 2997))
+    return Math.floor(100_000_000 * 6 ** (s / 2997))
 }
 
 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 = (ref: number): number => 1 + idiv(ref * 3, 1000)
+export const computeGeneratorCap = (com: number): number => 300 + idiv(com, 6)
+export const computeGeneratorRech = (fin: number): number => 1 + idiv(fin * 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 = (fin: number): number => Math.max(200, 2000 - fin * 2)
+export const computeGathererDepth = (tol: number, tier: number): number =>
+    gathererDepthForTier(tol, tier)
+export const computeLoaderMass = (ins: number): number => Math.max(200, 2000 - ins * 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 = (com: number): number => Math.max(5, 30 - idiv(com, 33))
+export const computeCrafterDrain = (fin: number): number => Math.max(5, 30 - idiv(fin, 33))
+export const computeHaulerCapacity = (fin: number): number => Math.max(1, 1 + idiv(fin, 400))
+export const computeHaulerEfficiency = (con: number): number => 2000 + con * 6
+export const computeHaulerDrain = (com: number): number => Math.max(3, 15 - idiv(com, 80))
+export const computeWarpRange = (stat: number): number => 100 + stat * 3
 
 export function entityDisplayName(itemId: number): string {
     switch (itemId) {
@@ -60,6 +71,8 @@ export function entityDisplayName(itemId: number): string {
             return 'Ship'
         case ITEM_WAREHOUSE_T1_PACKED:
             return 'Warehouse'
+        case ITEM_EXTRACTOR_T1_PACKED:
+            return 'Extractor'
         case ITEM_CONTAINER_T1_PACKED:
             return 'Container'
         case ITEM_CONTAINER_T2_PACKED:
@@ -83,6 +96,10 @@ export function moduleDisplayName(itemId: number): string {
             return 'Crafter'
         case ITEM_STORAGE_T1:
             return 'Storage'
+        case ITEM_HAULER_T1:
+            return 'Hauler'
+        case ITEM_WARP_T1:
+            return 'Warp'
         default:
             return 'Module'
     }
@@ -114,11 +131,12 @@ export function formatModuleLine(slot: number, itemId: number, stats: bigint): s
         case MODULE_GATHERER: {
             const str = decodeStat(stats, 0)
             const tol = decodeStat(stats, 1)
-            const con = decodeStat(stats, 3)
-            const ref = decodeStat(stats, 4)
+            const con = decodeStat(stats, 2)
+            const tier = getItem(itemId).tier
             out += `  Yield ${computeGathererYield(str)}  Depth ${computeGathererDepth(
-                tol
-            )}  Speed ${computeGathererSpeed(ref)}  Drain ${computeGathererDrain(con)}`
+                tol,
+                tier
+            )}  Drain ${computeGathererDrain(con)}`
             break
         }
         case MODULE_LOADER: {
@@ -142,6 +160,18 @@ export function formatModuleLine(slot: number, itemId: number, stats: bigint): s
             out += `  +${pct}% capacity`
             break
         }
+        case MODULE_HAULER: {
+            const res = decodeStat(stats, 0)
+            const con = decodeStat(stats, 1)
+            const ref = decodeStat(stats, 2)
+            out += `  Capacity ${computeHaulerCapacity(res)}  Efficiency ${computeHaulerEfficiency(con)}  Drain ${computeHaulerDrain(ref)}`
+            break
+        }
+        case MODULE_WARP: {
+            const stat = decodeStat(stats, 0)
+            out += `  Range ${computeWarpRange(stat)}`
+            break
+        }
     }
     return out
 }
@@ -158,6 +188,8 @@ export function buildEntityDescription(
         baseCapacity = computeBaseCapacityShip(hullStats)
     } else if (itemId === ITEM_WAREHOUSE_T1_PACKED) {
         baseCapacity = computeBaseCapacityWarehouse(hullStats)
+    } else if (itemId === ITEM_EXTRACTOR_T1_PACKED) {
+        baseCapacity = computeBaseCapacityShip(hullStats)
     }
 
     let out = entityDisplayName(itemId)

package/src/nft/index.ts

@@ -1,2 +1,5 @@
 export * from './deserializers'
 export * from './description'
+export * from './atomicdata'
+export * from './atomicassets'
+export * from './buildImmutableData'

package/src/resolution/describe-module.ts

@@ -53,25 +53,22 @@ const TEMPLATES: Record<string, TemplateSpec> = {
     gatherer: {
         id: 'module.gatherer.description',
         template:
-            'mines resources at {yield} speed to a max depth of {depth} with {speed} gather speed while draining {drain} energy per second',
+            'mines resources at {yield} yield to a max depth of {depth} while draining {drain} energy per second',
         params: [
             ['yield', 'Yield'],
-            ['drain', 'Drain'],
             ['depth', 'Depth'],
-            ['speed', 'Speed'],
+            ['drain', 'Drain'],
         ],
-        highlightKeys: ['yield', 'depth', 'speed', 'drain'],
+        highlightKeys: ['yield', 'depth', 'drain'],
     },
     loader: {
         id: 'module.loader.description',
-        template:
-            '{quantity} loader that generates {thrust} thrust with a weight of {mass} per unit',
+        template: 'generates {thrust} thrust with a weight of {mass} per unit',
         params: [
-            ['quantity', 'Quantity'],
             ['thrust', 'Thrust'],
             ['mass', 'Mass'],
         ],
-        highlightKeys: ['quantity', 'thrust', 'mass'],
+        highlightKeys: ['thrust', 'mass'],
     },
     crafter: {
         id: 'module.crafter.description',

package/src/resolution/display-name.ts

@@ -1,22 +1,50 @@
 import type {ResolvedItem} from './resolve-item'
 import type {ResourceCategory} from '../types'
-import {CATEGORY_LABELS, TIER_ADJECTIVES} from '../types'
+import {
+    CATEGORY_LABELS,
+    RESOURCE_TIER_ADJECTIVES,
+    COMPONENT_TIER_PREFIXES,
+    MODULE_TIER_PREFIXES,
+} from '../types'
 import {formatMass as defaultFormatMass} from '../format'
 
-export interface DisplayNameInput {
-    itemType: 'resource' | 'component' | 'module' | 'entity' | string
+interface DisplayNameInputCommon {
     tier: number
     category?: ResourceCategory
     name: string
 }
 
-export function displayName(resolved: DisplayNameInput): string {
-    if (resolved.itemType === 'resource') {
-        const adj = TIER_ADJECTIVES[resolved.tier] ?? 'Unknown'
-        const cat = resolved.category ? CATEGORY_LABELS[resolved.category] : 'Resource'
-        return `${adj} ${cat}`
-    }
-    return resolved.name
+export type DisplayNameInput =
+    | (DisplayNameInputCommon & {itemType: 'resource' | 'component' | 'module' | 'entity' | string})
+    | (DisplayNameInputCommon & {type: string})
+
+function itemTypeOf(item: DisplayNameInput): string {
+    return 'itemType' in item ? item.itemType : item.type
+}
+
+function tierPrefix(item: DisplayNameInput): string | null {
+    const t = itemTypeOf(item)
+    if (t === 'resource') return RESOURCE_TIER_ADJECTIVES[item.tier] ?? null
+    if (t === 'component') return COMPONENT_TIER_PREFIXES[item.tier] ?? null
+    if (t === 'module') return MODULE_TIER_PREFIXES[item.tier] ?? null
+    return null
+}
+
+function rootName(item: DisplayNameInput): string {
+    if (itemTypeOf(item) !== 'resource') return item.name
+    return item.category ? CATEGORY_LABELS[item.category] : 'Resource'
+}
+
+// Tier-free display name: includes the resource tier adjective / component-module
+// prefix, but no "(T#)" suffix. Use this when the tier is shown separately.
+export function baseName(item: DisplayNameInput): string {
+    const prefix = tierPrefix(item)
+    const root = rootName(item)
+    return prefix ? `${prefix} ${root}` : root
+}
+
+export function displayName(item: DisplayNameInput): string {
+    return `${baseName(item)} (T${item.tier})`
 }
 
 export interface DescribeOptions {