@shipload/sdk 0.7.0 → 1.0.0-beta1

package/src/managers/entities.ts

@@ -0,0 +1,103 @@
+import {Name, type NameType, type UInt64Type} from '@wharfkit/antelope'
+import {BaseManager} from './base'
+import {Ship} from '../entities/ship'
+import {Warehouse} from '../entities/warehouse'
+import {Container} from '../entities/container'
+import type {ServerContract} from '../contracts'
+
+export type EntityType = 'ship' | 'warehouse' | 'container' | 'location'
+
+export class EntitiesManager extends BaseManager {
+    async getEntity(type: EntityType, id: UInt64Type): Promise<Ship | Warehouse | Container> {
+        const result = await this.server.readonly('getentity', {
+            entity_type: Name.from(type),
+            entity_id: id,
+        })
+        const entityInfo = result as ServerContract.Types.entity_info
+        return this.wrapEntity(entityInfo)
+    }
+
+    async getEntities(
+        owner: NameType | ServerContract.Types.player_row,
+        type?: EntityType
+    ): Promise<(Ship | Warehouse | Container)[]> {
+        const ownerName = this.resolveOwner(owner)
+        const result = await this.server.readonly('getentities', {
+            owner: ownerName,
+            entity_type: type ? Name.from(type) : null,
+        })
+        const entities = result as ServerContract.Types.entity_info[]
+        return entities.map((entity) => this.wrapEntity(entity))
+    }
+
+    async getSummaries(
+        owner: NameType | ServerContract.Types.player_row,
+        type?: EntityType
+    ): Promise<ServerContract.Types.entity_summary[]> {
+        const ownerName = this.resolveOwner(owner)
+        const result = await this.server.readonly('getsummaries', {
+            owner: ownerName,
+            entity_type: type ? Name.from(type) : null,
+        })
+        return result as ServerContract.Types.entity_summary[]
+    }
+
+    async getShip(id: UInt64Type): Promise<Ship> {
+        return (await this.getEntity('ship', id)) as Ship
+    }
+
+    async getWarehouse(id: UInt64Type): Promise<Warehouse> {
+        return (await this.getEntity('warehouse', id)) as Warehouse
+    }
+
+    async getContainer(id: UInt64Type): Promise<Container> {
+        return (await this.getEntity('container', id)) as Container
+    }
+
+    async getShips(owner: NameType | ServerContract.Types.player_row): Promise<Ship[]> {
+        return (await this.getEntities(owner, 'ship')) as Ship[]
+    }
+
+    async getWarehouses(owner: NameType | ServerContract.Types.player_row): Promise<Warehouse[]> {
+        return (await this.getEntities(owner, 'warehouse')) as Warehouse[]
+    }
+
+    async getContainers(owner: NameType | ServerContract.Types.player_row): Promise<Container[]> {
+        return (await this.getEntities(owner, 'container')) as Container[]
+    }
+
+    async getShipSummaries(
+        owner: NameType | ServerContract.Types.player_row
+    ): Promise<ServerContract.Types.entity_summary[]> {
+        return this.getSummaries(owner, 'ship')
+    }
+
+    async getWarehouseSummaries(
+        owner: NameType | ServerContract.Types.player_row
+    ): Promise<ServerContract.Types.entity_summary[]> {
+        return this.getSummaries(owner, 'warehouse')
+    }
+
+    async getContainerSummaries(
+        owner: NameType | ServerContract.Types.player_row
+    ): Promise<ServerContract.Types.entity_summary[]> {
+        return this.getSummaries(owner, 'container')
+    }
+
+    private wrapEntity(entity: ServerContract.Types.entity_info): Ship | Warehouse | Container {
+        if (entity.type.equals('ship')) {
+            return new Ship(entity)
+        } else if (entity.type.equals('warehouse')) {
+            return new Warehouse(entity)
+        } else {
+            return new Container(entity)
+        }
+    }
+
+    private resolveOwner(owner: NameType | ServerContract.Types.player_row): Name {
+        if (typeof owner === 'object' && owner !== null && 'owner' in owner) {
+            return owner.owner
+        }
+        return Name.from(owner)
+    }
+}

package/src/managers/epochs.ts

@@ -0,0 +1,47 @@
+import {UInt64, type UInt64Type} from '@wharfkit/antelope'
+import {BaseManager} from './base'
+import {type EpochInfo, getCurrentEpoch, getEpochInfo} from '../scheduling/epoch'
+
+export class EpochsManager extends BaseManager {
+    async getCurrentHeight(): Promise<UInt64> {
+        const game = await this.getGame()
+        return getCurrentEpoch(game)
+    }
+
+    async getCurrent(): Promise<EpochInfo> {
+        const game = await this.getGame()
+        const epoch = await this.getCurrentHeight()
+        return getEpochInfo(game, epoch)
+    }
+
+    async getByHeight(height: UInt64Type): Promise<EpochInfo> {
+        const game = await this.getGame()
+        return getEpochInfo(game, UInt64.from(height))
+    }
+
+    async getTimeRemaining(): Promise<number> {
+        const epochInfo = await this.getCurrent()
+        const now = Date.now()
+        const endTime = epochInfo.end.getTime()
+        return Math.max(0, endTime - now)
+    }
+
+    async getProgress(): Promise<number> {
+        const epochInfo = await this.getCurrent()
+        const now = Date.now()
+        const startTime = epochInfo.start.getTime()
+        const endTime = epochInfo.end.getTime()
+        const duration = endTime - startTime
+        const elapsed = now - startTime
+
+        if (elapsed <= 0) return 0
+        if (elapsed >= duration) return 1
+
+        return elapsed / duration
+    }
+
+    async fitsInCurrentEpoch(durationMs: number): Promise<boolean> {
+        const remaining = await this.getTimeRemaining()
+        return durationMs <= remaining
+    }
+}

package/src/managers/index.ts

@@ -0,0 +1,9 @@
+export {GameContext} from './context'
+export {BaseManager} from './base'
+export {EntitiesManager} from './entities'
+export type {EntityType} from './entities'
+export {PlayersManager} from './players'
+export {LocationsManager} from './locations'
+export type {LocationStratum} from './locations'
+export {EpochsManager} from './epochs'
+export {ActionsManager} from './actions'

package/src/managers/locations.ts

@@ -0,0 +1,68 @@
+import {type UInt16Type, UInt64, type UInt64Type} from '@wharfkit/antelope'
+import {BaseManager} from './base'
+import {type CoordinatesType, coordsToLocationId, type Distance} from '../types'
+import {hasSystem} from '../utils/system'
+import {findNearbyPlanets} from '../travel/travel'
+import type {ServerContract} from '../contracts'
+import {type DerivedStratum, deriveStrata} from '../derivation'
+
+export interface LocationStratum extends DerivedStratum {
+    reserveMax: number
+}
+
+export class LocationsManager extends BaseManager {
+    async hasSystem(location: CoordinatesType): Promise<boolean> {
+        const game = await this.getGame()
+        return hasSystem(game.config.seed, location)
+    }
+
+    async findNearbyPlanets(
+        origin: CoordinatesType,
+        maxDistance: UInt16Type = 20
+    ): Promise<Distance[]> {
+        const game = await this.getGame()
+        return findNearbyPlanets(game.config.seed, origin, maxDistance)
+    }
+
+    async getStrata(coords: CoordinatesType): Promise<LocationStratum[]> {
+        const game = await this.getGame()
+        const state = await this.getState()
+
+        const derived = deriveStrata(coords, game.config.seed, state.epochSeed)
+        if (derived.length === 0) return []
+
+        const overrides = (await this.server.readonly('getreserves', {
+            x: coords.x,
+            y: coords.y,
+        })) as ServerContract.Types.stratum_remaining[]
+
+        const overrideMap = new Map<number, number>()
+        for (const o of overrides) {
+            overrideMap.set(Number(o.stratum), Number(o.remaining))
+        }
+
+        return derived.map((s) => ({
+            ...s,
+            reserveMax: s.reserve,
+            reserve: overrideMap.get(s.index) ?? s.reserve,
+        }))
+    }
+
+    async getLocationEntity(
+        id: UInt64Type
+    ): Promise<ServerContract.Types.location_row | undefined> {
+        const row = await this.server.table('location').get(UInt64.from(id))
+        return row ?? undefined
+    }
+
+    async getLocationEntityAt(
+        coords: CoordinatesType
+    ): Promise<ServerContract.Types.location_row | undefined> {
+        const id = coordsToLocationId(coords)
+        return this.getLocationEntity(id)
+    }
+
+    async getAllLocationEntities(): Promise<ServerContract.Types.location_row[]> {
+        return this.server.table('location').all()
+    }
+}

package/src/managers/players.ts

@@ -0,0 +1,13 @@
+import {Name, type NameType} from '@wharfkit/antelope'
+import {BaseManager} from './base'
+import {Player} from '../entities/player'
+
+export class PlayersManager extends BaseManager {
+    async getPlayer(account: NameType): Promise<Player | undefined> {
+        const playerRow = await this.server.table('player').get(Name.from(account))
+        if (!playerRow) {
+            return undefined
+        }
+        return new Player(playerRow)
+    }
+}

package/src/nft/description.ts

@@ -0,0 +1,176 @@
+import {
+    getModuleCapabilityType,
+    MODULE_CRAFTER,
+    MODULE_ENGINE,
+    MODULE_GATHERER,
+    MODULE_GENERATOR,
+    MODULE_LOADER,
+    MODULE_STORAGE,
+} from '../capabilities/modules'
+import {
+    ITEM_CONTAINER_T1_PACKED,
+    ITEM_CONTAINER_T2_PACKED,
+    ITEM_CRAFTER_T1,
+    ITEM_ENGINE_T1,
+    ITEM_GATHERER_T1,
+    ITEM_GENERATOR_T1,
+    ITEM_LOADER_T1,
+    ITEM_SHIP_T1_PACKED,
+    ITEM_STORAGE_T1,
+    ITEM_WAREHOUSE_T1_PACKED,
+} from '../data/item-ids'
+import {decodeStat} from '../derivation/crafting'
+
+function idiv(a: number, b: number): number {
+    return Math.floor(a / b)
+}
+
+export function computeBaseHullmass(stats: bigint): number {
+    const density = decodeStat(stats, 1)
+    return 25000 + 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))
+}
+
+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))
+}
+
+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 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 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 function entityDisplayName(itemId: number): string {
+    switch (itemId) {
+        case ITEM_SHIP_T1_PACKED:
+            return 'Ship'
+        case ITEM_WAREHOUSE_T1_PACKED:
+            return 'Warehouse'
+        case ITEM_CONTAINER_T1_PACKED:
+            return 'Container'
+        case ITEM_CONTAINER_T2_PACKED:
+            return 'Container'
+        default:
+            return 'Entity'
+    }
+}
+
+export function moduleDisplayName(itemId: number): string {
+    switch (itemId) {
+        case ITEM_ENGINE_T1:
+            return 'Engine'
+        case ITEM_GENERATOR_T1:
+            return 'Generator'
+        case ITEM_GATHERER_T1:
+            return 'Gatherer'
+        case ITEM_LOADER_T1:
+            return 'Loader'
+        case ITEM_CRAFTER_T1:
+            return 'Crafter'
+        case ITEM_STORAGE_T1:
+            return 'Storage'
+        default:
+            return 'Module'
+    }
+}
+
+export function formatModuleLine(slot: number, itemId: number, stats: bigint): string {
+    let out = `Slot ${slot} - `
+    if (itemId === 0) {
+        out += '(empty)'
+        return out
+    }
+
+    out += moduleDisplayName(itemId)
+    const subtype = getModuleCapabilityType(itemId)
+
+    switch (subtype) {
+        case MODULE_ENGINE: {
+            const vol = decodeStat(stats, 0)
+            const thm = decodeStat(stats, 1)
+            out += `  Thrust ${computeEngineThrust(vol)}  Drain ${computeEngineDrain(thm)}`
+            break
+        }
+        case MODULE_GENERATOR: {
+            const res = decodeStat(stats, 0)
+            const ref = decodeStat(stats, 1)
+            out += `  Capacity ${computeGeneratorCap(res)}  Recharge ${computeGeneratorRech(ref)}`
+            break
+        }
+        case MODULE_GATHERER: {
+            const str = decodeStat(stats, 0)
+            const tol = decodeStat(stats, 1)
+            const con = decodeStat(stats, 3)
+            const ref = decodeStat(stats, 4)
+            out += `  Yield ${computeGathererYield(str)}  Depth ${computeGathererDepth(
+                tol
+            )}  Speed ${computeGathererSpeed(ref)}  Drain ${computeGathererDrain(con)}`
+            break
+        }
+        case MODULE_LOADER: {
+            const fin = decodeStat(stats, 0)
+            const pla = decodeStat(stats, 1)
+            out += `  Mass ${computeLoaderMass(fin)}  Thrust ${computeLoaderThrust(pla)}`
+            break
+        }
+        case MODULE_CRAFTER: {
+            const rea = decodeStat(stats, 0)
+            const com = decodeStat(stats, 1)
+            out += `  Speed ${computeCrafterSpeed(rea)}  Drain ${computeCrafterDrain(com)}`
+            break
+        }
+        case MODULE_STORAGE: {
+            const str = decodeStat(stats, 0)
+            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
+        }
+    }
+    return out
+}
+
+export function buildEntityDescription(
+    itemId: number,
+    hullStats: bigint,
+    moduleItems: number[],
+    moduleStats: bigint[]
+): string {
+    const hullMass = computeBaseHullmass(hullStats)
+    let baseCapacity = 0
+    if (itemId === ITEM_SHIP_T1_PACKED) {
+        baseCapacity = computeBaseCapacityShip(hullStats)
+    } else if (itemId === ITEM_WAREHOUSE_T1_PACKED) {
+        baseCapacity = computeBaseCapacityWarehouse(hullStats)
+    }
+
+    let out = entityDisplayName(itemId)
+    out += ` - Hull ${hullMass} mass`
+    if (baseCapacity > 0) {
+        out += ` * ${baseCapacity} capacity`
+    }
+    out += '\n\n'
+
+    for (let i = 0; i < moduleItems.length; i++) {
+        out += formatModuleLine(i, moduleItems[i], moduleStats[i] ?? 0n)
+        out += '\n'
+    }
+
+    return out
+}

package/src/nft/deserializers.ts

@@ -0,0 +1,83 @@
+import {getEntityLayout} from '../data/recipes-runtime'
+import {moduleSlotTypeToCode} from '../capabilities/modules'
+import {
+    ITEM_TYPE_COMPONENT,
+    ITEM_TYPE_ENTITY,
+    ITEM_TYPE_MODULE,
+    ITEM_TYPE_RESOURCE,
+    itemTypeCode,
+} from '../data/tiers'
+
+export interface NFTInstalledModule {
+    item_id: number
+    stats: string
+}
+
+export interface NFTModuleSlot {
+    type: number
+    installed?: NFTInstalledModule
+}
+
+export interface NFTCargoItem {
+    item_id: number
+    quantity: number
+    stats: string
+    modules?: NFTModuleSlot[]
+}
+
+export interface NFTCommonBase {
+    quantity: number
+    stats: string
+    origin_x: string
+    origin_y: string
+}
+
+export function readCommonBase(data: Record<string, any>): NFTCommonBase {
+    return {
+        quantity: Number(data.quantity),
+        stats: String(data.stats),
+        origin_x: String(data.origin_x),
+        origin_y: String(data.origin_y),
+    }
+}
+
+export function deserializeScalar(data: Record<string, any>, itemId: number): NFTCargoItem {
+    const base = readCommonBase(data)
+    return {item_id: itemId, quantity: base.quantity, stats: base.stats}
+}
+
+export const deserializeResource = deserializeScalar
+export const deserializeComponent = deserializeScalar
+export const deserializeModule = deserializeScalar
+
+export function deserializeEntity(data: Record<string, any>, itemId: number): NFTCargoItem {
+    const base = readCommonBase(data)
+    const moduleItems: number[] = (data.module_items ?? []).map((v: any) => Number(v))
+    const moduleStats: string[] = (data.module_stats ?? []).map((v: any) => String(v))
+    const layout = getEntityLayout(itemId)
+    const slots = layout?.slots ?? []
+
+    const modules: NFTModuleSlot[] = slots.map((slot, i) => ({
+        type: moduleSlotTypeToCode(slot.type),
+        installed:
+            moduleItems[i] && moduleItems[i] !== 0
+                ? {item_id: moduleItems[i], stats: moduleStats[i]}
+                : undefined,
+    }))
+
+    return {item_id: itemId, quantity: base.quantity, stats: base.stats, modules}
+}
+
+export function deserializeAsset(data: Record<string, any>, itemId: number): NFTCargoItem {
+    const type = itemTypeCode(itemId)
+    switch (type) {
+        case ITEM_TYPE_RESOURCE:
+        case ITEM_TYPE_COMPONENT:
+        case ITEM_TYPE_MODULE:
+            return deserializeScalar(data, itemId)
+        case ITEM_TYPE_ENTITY:
+            return deserializeEntity(data, itemId)
+        default:
+            throw new Error(`unknown item type ${type} for item ${itemId}`)
+    }
+}

package/src/nft/index.ts

@@ -0,0 +1,2 @@
+export * from './deserializers'
+export * from './description'

package/src/resolution/describe-module.ts

@@ -0,0 +1,166 @@
+import type {ResolvedItem, ResolvedModuleSlot} from './resolve-item'
+
+export interface TextSpan {
+    text: string
+    highlight?: boolean
+}
+
+export interface CapabilityInput {
+    capability: string
+    attributes: {label: string; value: number}[]
+}
+
+export interface ModuleDescription {
+    id: string
+    template: string
+    params: Readonly<Record<string, number | string>>
+    highlightKeys: readonly string[]
+}
+
+export interface RenderDescriptionOptions {
+    translate?: (id: string, fallback: string) => string
+    formatNumber?: (n: number) => string
+}
+
+interface TemplateSpec {
+    id: string
+    template: string
+    params: readonly [string, string][]
+    highlightKeys: readonly string[]
+}
+
+const TEMPLATES: Record<string, TemplateSpec> = {
+    engine: {
+        id: 'module.engine.description',
+        template:
+            'generates {thrust} thrust for travel while draining {drain} energy per distance travelled',
+        params: [
+            ['thrust', 'Thrust'],
+            ['drain', 'Drain'],
+        ],
+        highlightKeys: ['thrust', 'drain'],
+    },
+    generator: {
+        id: 'module.generator.description',
+        template:
+            'holds {capacity} maximum energy and restores {recharge} per second while recharging',
+        params: [
+            ['capacity', 'Capacity'],
+            ['recharge', 'Recharge'],
+        ],
+        highlightKeys: ['capacity', 'recharge'],
+    },
+    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',
+        params: [
+            ['yield', 'Yield'],
+            ['drain', 'Drain'],
+            ['depth', 'Depth'],
+            ['speed', 'Speed'],
+        ],
+        highlightKeys: ['yield', 'depth', 'speed', 'drain'],
+    },
+    loader: {
+        id: 'module.loader.description',
+        template:
+            '{quantity} loader that generates {thrust} thrust with a weight of {mass} per unit',
+        params: [
+            ['quantity', 'Quantity'],
+            ['thrust', 'Thrust'],
+            ['mass', 'Mass'],
+        ],
+        highlightKeys: ['quantity', 'thrust', 'mass'],
+    },
+    crafter: {
+        id: 'module.crafter.description',
+        template: 'manufactures items at {speed} speed while draining {drain} energy per second',
+        params: [
+            ['speed', 'Speed'],
+            ['drain', 'Drain'],
+        ],
+        highlightKeys: ['speed', 'drain'],
+    },
+    storage: {
+        id: 'module.storage.description',
+        template: 'boosts cargo capacity by {bonus}%',
+        params: [['bonus', 'Capacity Bonus']],
+        highlightKeys: ['bonus'],
+    },
+    hauler: {
+        id: 'module.hauler.description',
+        template:
+            'locks onto up to {capacity} targets at {efficiency} efficiency while draining {drain} energy per distance travelled per target',
+        params: [
+            ['capacity', 'Capacity'],
+            ['efficiency', 'Efficiency'],
+            ['drain', 'Drain'],
+        ],
+        highlightKeys: ['capacity', 'efficiency', 'drain'],
+    },
+}
+
+export function describeModule(input: CapabilityInput): ModuleDescription | null {
+    if (!input.attributes || input.attributes.length === 0) return null
+    const key = input.capability.toLowerCase()
+    const spec = TEMPLATES[key]
+    if (!spec) return null
+    const params: Record<string, number | string> = {}
+    for (const [paramName, attrLabel] of spec.params) {
+        const attr = input.attributes.find((a) => a.label === attrLabel)
+        if (attr) params[paramName] = attr.value
+    }
+    return {
+        id: spec.id,
+        template: spec.template,
+        params,
+        highlightKeys: spec.highlightKeys,
+    }
+}
+
+export function describeModuleForItem(resolved: ResolvedItem): ModuleDescription | null {
+    if (resolved.itemType !== 'module') return null
+    const group = resolved.attributes?.[0]
+    if (!group) return null
+    return describeModule({capability: group.capability, attributes: group.attributes})
+}
+
+export function describeModuleForSlot(slot: ResolvedModuleSlot): ModuleDescription | null {
+    if (!slot.installed || !slot.name || !slot.attributes) return null
+    return describeModule({capability: slot.name, attributes: slot.attributes})
+}
+
+export function renderDescription(
+    desc: ModuleDescription,
+    options?: RenderDescriptionOptions
+): TextSpan[] {
+    const translate = options?.translate ?? ((_id: string, fallback: string) => fallback)
+    const formatNumber = options?.formatNumber ?? ((n: number) => n.toLocaleString('en-US'))
+    const tpl = translate(desc.id, desc.template)
+
+    const spans: TextSpan[] = []
+    const regex = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g
+    let lastIndex = 0
+    while (true) {
+        const m = regex.exec(tpl)
+        if (m === null) break
+        if (m.index > lastIndex) {
+            spans.push({text: tpl.slice(lastIndex, m.index)})
+        }
+        const paramName = m[1] ?? ''
+        const raw = desc.params[paramName]
+        if (raw === undefined) {
+            spans.push({text: `{${paramName}}`})
+        } else {
+            const formatted = typeof raw === 'number' ? formatNumber(raw) : raw
+            const highlight = (desc.highlightKeys as readonly string[]).includes(paramName)
+            spans.push(highlight ? {text: formatted, highlight: true} : {text: formatted})
+        }
+        lastIndex = m.index + m[0].length
+    }
+    if (lastIndex < tpl.length) {
+        spans.push({text: tpl.slice(lastIndex)})
+    }
+    return spans
+}