@shipload/sdk 1.0.0-next.34 → 1.0.0-next.36

package/src/coordinates/address.ts

@@ -0,0 +1,88 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {
+    COORD_MAX,
+    COORD_MIN,
+    COORD_OFFSET,
+    LOCAL_HALF,
+    LOCAL_MAX,
+    LOCAL_MIN,
+    REGION_DIV,
+    REGION_PER_AXIS,
+    SECTOR_DIV,
+} from './constants'
+import {decodeRegion, encodeRegion} from './regions'
+import {decodeSector, encodeSector} from './sectors'
+
+export interface CoordinateAddress {
+    sector: string
+    region: string
+    localX: number
+    localY: number
+}
+
+interface AxisSlices {
+    sector: number
+    region: number
+    local: number
+}
+
+function sliceAxis(coord: number): AxisSlices {
+    if (!Number.isInteger(coord) || coord < COORD_MIN || coord > COORD_MAX) {
+        throw new RangeError(`coordinate out of range: ${coord}`)
+    }
+    const u = coord + COORD_OFFSET
+    return {
+        sector: Math.floor(u / SECTOR_DIV),
+        region: Math.floor(u / REGION_DIV) % REGION_PER_AXIS,
+        local: (u % REGION_DIV) - LOCAL_HALF,
+    }
+}
+
+export function encodeAddress(seed: Checksum256Type, x: number, y: number): CoordinateAddress {
+    const ax = sliceAxis(x)
+    const ay = sliceAxis(y)
+    return {
+        sector: encodeSector(seed, ax.sector, ay.sector),
+        region: encodeRegion(seed, ax.region, ay.region),
+        localX: ax.local,
+        localY: ay.local,
+    }
+}
+
+export function decodeAddress(
+    seed: Checksum256Type,
+    addr: CoordinateAddress
+): {x: number; y: number} {
+    if (
+        !Number.isInteger(addr.localX) ||
+        !Number.isInteger(addr.localY) ||
+        addr.localX < LOCAL_MIN ||
+        addr.localX > LOCAL_MAX ||
+        addr.localY < LOCAL_MIN ||
+        addr.localY > LOCAL_MAX
+    ) {
+        throw new RangeError(`local position out of range: ${addr.localX}, ${addr.localY}`)
+    }
+    const sector = decodeSector(seed, addr.sector)
+    const region = decodeRegion(seed, addr.region)
+    const x =
+        sector.sx * SECTOR_DIV + region.rx * REGION_DIV + (addr.localX + LOCAL_HALF) - COORD_OFFSET
+    const y =
+        sector.sy * SECTOR_DIV + region.ry * REGION_DIV + (addr.localY + LOCAL_HALF) - COORD_OFFSET
+    if (x < COORD_MIN || x > COORD_MAX || y < COORD_MIN || y > COORD_MAX) {
+        throw new RangeError(`address decodes outside the coordinate range: ${x}, ${y}`)
+    }
+    return {x, y}
+}
+
+export function addressFromCoordinates(
+    seed: Checksum256Type,
+    coords: {
+        x: number | {toNumber(): number}
+        y: number | {toNumber(): number}
+    }
+): CoordinateAddress {
+    const x = typeof coords.x === 'number' ? coords.x : coords.x.toNumber()
+    const y = typeof coords.y === 'number' ? coords.y : coords.y.toNumber()
+    return encodeAddress(seed, x, y)
+}

package/src/coordinates/constants.test.ts

@@ -0,0 +1,15 @@
+import {describe, expect, test} from 'bun:test'
+import * as sdk from '../index-module'
+
+describe('coordinate constants re-export', () => {
+    test('frozen spatial constants are reachable from the package root', () => {
+        expect(sdk.REGION_DIV).toBe(10_000)
+        expect(sdk.SECTOR_DIV).toBe(100_000_000)
+        expect(sdk.COORD_OFFSET).toBe(2_147_485_000)
+        expect(sdk.SECTORS_PER_AXIS).toBe(43)
+        expect(sdk.REGION_PER_AXIS).toBe(10_000)
+        expect(sdk.LOCAL_HALF).toBe(5_000)
+        expect(sdk.COORD_MIN).toBe(-2_147_483_648)
+        expect(sdk.COORD_MAX).toBe(2_147_483_647)
+    })
+})

package/src/coordinates/constants.ts

@@ -0,0 +1,23 @@
+import type {FeistelConfig} from './permutation'
+
+// FROZEN INTERFACE — these values define the on-the-wire address format.
+export const COORD_MIN = -2_147_483_648
+export const COORD_MAX = 2_147_483_647
+// Centers the region grid on the origin: raw (0,0) sits at a region center (local 0,0), not a corner; u stays >= 0 across int32.
+export const COORD_OFFSET = 2_147_485_000
+export const AXIS_SPAN = 4_294_967_296 // 2^32 distinct values per axis
+
+export const SECTOR_DIV = 100_000_000 // 10^8 tiles per sector side
+export const REGION_DIV = 10_000 // 10^4 tiles per region side
+export const SECTORS_PER_AXIS = 43 // floor((2^32 - 1) / 10^8) + 1
+export const REGION_PER_AXIS = 10_000
+export const LOCAL_HALF = 5_000 // half a region; local is signed, measured from the region center
+export const LOCAL_MIN = -5_000
+export const LOCAL_MAX = 4_999
+
+export const SECTOR_COUNT = SECTORS_PER_AXIS * SECTORS_PER_AXIS // 1849
+export const REGION_COUNT = REGION_PER_AXIS * REGION_PER_AXIS // 100,000,000
+
+// 2*halfBits must give a block domain >= the tier's count.
+export const SECTOR_FEISTEL: FeistelConfig = {n: SECTOR_COUNT, halfBits: 6, label: 'sector'} // 2^12 = 4096
+export const REGION_FEISTEL: FeistelConfig = {n: REGION_COUNT, halfBits: 14, label: 'region'} // 2^28 ≈ 2.68e8

package/src/coordinates/index.ts

@@ -0,0 +1,15 @@
+export type {CoordinateAddress} from './address'
+export {addressFromCoordinates, decodeAddress, encodeAddress} from './address'
+export {encodeSector, decodeSector} from './sectors'
+export {encodeRegion, decodeRegion} from './regions'
+export {encodeAddressMemo} from './memo'
+export {
+    COORD_MIN,
+    COORD_MAX,
+    COORD_OFFSET,
+    REGION_DIV,
+    SECTOR_DIV,
+    SECTORS_PER_AXIS,
+    REGION_PER_AXIS,
+    LOCAL_HALF,
+} from './constants'

package/src/coordinates/memo.test.ts

@@ -0,0 +1,47 @@
+import {describe, expect, test} from 'bun:test'
+import {Checksum256} from '@wharfkit/antelope'
+import {encodeAddress, decodeAddress} from './address'
+import {encodeAddressMemo} from './memo'
+
+const SEED = Checksum256.from('73e4385a2708e6d704883c670c50b0aa502ba1098072ed100ae1920eee3597d9')
+
+describe('encodeAddressMemo', () => {
+    test('matches encodeAddress', () => {
+        for (const [x, y] of [
+            [0, 0],
+            [12, -9],
+            [2_147_483_647, -2_147_483_648],
+        ] as const) {
+            expect(encodeAddressMemo(SEED, x, y)).toEqual(encodeAddress(SEED, x, y))
+        }
+    })
+
+    test('returns the same cached object reference for repeat calls', () => {
+        const a = encodeAddressMemo(SEED, 4827, 1190)
+        const b = encodeAddressMemo(SEED, 4827, 1190)
+        expect(a).toBe(b)
+    })
+
+    test('round-trips through decodeAddress', () => {
+        const addr = encodeAddressMemo(SEED, -5, 7)
+        expect(decodeAddress(SEED, addr)).toEqual({x: -5, y: 7})
+    })
+
+    test('origin is centered: raw (0,0) is local (0,0)', () => {
+        const addr = encodeAddressMemo(SEED, 0, 0)
+        expect([addr.localX, addr.localY]).toEqual([0, 0])
+    })
+
+    test('origin neighbors share the origin region', () => {
+        const origin = encodeAddressMemo(SEED, 0, 0)
+        for (const [x, y] of [
+            [-1, -1],
+            [4999, 4999],
+            [-5000, -5000],
+        ] as const) {
+            expect(encodeAddressMemo(SEED, x, y).region).toBe(origin.region)
+        }
+        // first tile outside the origin region on each axis falls into a different region
+        expect(encodeAddressMemo(SEED, 5000, 0).region).not.toBe(origin.region)
+    })
+})

package/src/coordinates/memo.ts

@@ -0,0 +1,20 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {Checksum256} from '@wharfkit/antelope'
+import {type CoordinateAddress, encodeAddress} from './address'
+
+const cache = new Map<string, CoordinateAddress>()
+const CACHE_MAX = 4096
+
+export function encodeAddressMemo(seed: Checksum256Type, x: number, y: number): CoordinateAddress {
+    const key = `${Checksum256.from(seed).toString()}:${x},${y}`
+    let hit = cache.get(key)
+    if (!hit) {
+        hit = encodeAddress(seed, x, y)
+        if (cache.size >= CACHE_MAX) {
+            const oldest = cache.keys().next().value
+            if (oldest !== undefined) cache.delete(oldest)
+        }
+        cache.set(key, hit)
+    }
+    return hit
+}

package/src/coordinates/permutation.ts

@@ -0,0 +1,77 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {hash512} from '../utils/hash'
+
+// FROZEN INTERFACE — round count, key-derivation strings, and mixing constants must never change; per-game variation comes from the seed.
+const ROUNDS = 4
+
+export interface FeistelConfig {
+    n: number
+    halfBits: number
+    label: string
+}
+
+const keyCache = new Map<string, number[]>()
+
+function deriveRoundKeys(seed: Checksum256Type, label: string): number[] {
+    const cacheKey = `${seed}:${label}`
+    const cached = keyCache.get(cacheKey)
+    if (cached) return cached
+    const h = hash512(seed, `coord-keys-${label}`).array
+    const keys: number[] = []
+    for (let i = 0; i < ROUNDS; i++) {
+        const o = i * 4
+        keys.push(((h[o] << 24) | (h[o + 1] << 16) | (h[o + 2] << 8) | h[o + 3]) >>> 0)
+    }
+    keyCache.set(cacheKey, keys)
+    return keys
+}
+
+function roundFn(r: number, key: number, halfBits: number): number {
+    let x = (r ^ key) >>> 0
+    x = Math.imul(x ^ (x >>> 16), 0x9e3779b1) >>> 0
+    x = Math.imul(x ^ (x >>> 13), 0x7feb352d) >>> 0
+    x = (x ^ (x >>> 16)) >>> 0
+    return x & ((1 << halfBits) - 1)
+}
+
+function encryptBlock(x: number, halfBits: number, keys: number[]): number {
+    const mask = (1 << halfBits) - 1
+    let L = (x >>> halfBits) & mask
+    let R = x & mask
+    for (let i = 0; i < ROUNDS; i++) {
+        const F = roundFn(R, keys[i], halfBits)
+        const nL = R
+        const nR = (L ^ F) & mask
+        L = nL
+        R = nR
+    }
+    return ((L << halfBits) | R) >>> 0
+}
+
+function decryptBlock(y: number, halfBits: number, keys: number[]): number {
+    const mask = (1 << halfBits) - 1
+    let L = (y >>> halfBits) & mask
+    let R = y & mask
+    for (let i = ROUNDS - 1; i >= 0; i--) {
+        const F = roundFn(L, keys[i], halfBits)
+        const nR = L
+        const nL = (R ^ F) & mask
+        L = nL
+        R = nR
+    }
+    return ((L << halfBits) | R) >>> 0
+}
+
+export function permute(seed: Checksum256Type, x: number, cfg: FeistelConfig): number {
+    const keys = deriveRoundKeys(seed, cfg.label)
+    let v = encryptBlock(x, cfg.halfBits, keys)
+    while (v >= cfg.n) v = encryptBlock(v, cfg.halfBits, keys)
+    return v
+}
+
+export function unpermute(seed: Checksum256Type, y: number, cfg: FeistelConfig): number {
+    const keys = deriveRoundKeys(seed, cfg.label)
+    let v = decryptBlock(y, cfg.halfBits, keys)
+    while (v >= cfg.n) v = decryptBlock(v, cfg.halfBits, keys)
+    return v
+}

package/src/coordinates/regions.ts

@@ -0,0 +1,48 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {REGION_FEISTEL, REGION_PER_AXIS} from './constants'
+import {permute, unpermute} from './permutation'
+
+// FROZEN INTERFACE — phoneme tables; tune aesthetics before launch, then never reorder.
+const ONSETS = ['b', 'd', 'f', 'g', 'k', 'l', 'm', 'n', 'p', 'r', 's', 't'] // 12
+const VOWELS = ['a', 'e', 'i', 'o', 'u'] // 5
+const CODAS = ['n', 'r', 'l', 's', 'k', 'm', 't', 'x'] // 8
+const SYL_BASE = ONSETS.length * VOWELS.length * CODAS.length // 480
+
+function syllable(digit: number): string {
+    const onset = Math.floor(digit / (VOWELS.length * CODAS.length))
+    const rem = digit % (VOWELS.length * CODAS.length)
+    const vowel = Math.floor(rem / CODAS.length)
+    const coda = rem % CODAS.length
+    return ONSETS[onset] + VOWELS[vowel] + CODAS[coda]
+}
+
+function unsyllable(chunk: string): number {
+    const onset = ONSETS.indexOf(chunk[0])
+    const vowel = VOWELS.indexOf(chunk[1])
+    const coda = CODAS.indexOf(chunk[2])
+    if (onset < 0 || vowel < 0 || coda < 0) throw new Error(`invalid region token chunk: ${chunk}`)
+    return onset * (VOWELS.length * CODAS.length) + vowel * CODAS.length + coda
+}
+
+export function encodeRegion(seed: Checksum256Type, rx: number, ry: number): string {
+    const index = rx * REGION_PER_AXIS + ry
+    let n = permute(seed, index, REGION_FEISTEL)
+    const d0 = n % SYL_BASE
+    n = Math.floor(n / SYL_BASE)
+    const d1 = n % SYL_BASE
+    const d2 = Math.floor(n / SYL_BASE)
+    const token = syllable(d2) + syllable(d1) + syllable(d0)
+    return token.charAt(0).toUpperCase() + token.slice(1)
+}
+
+export function decodeRegion(seed: Checksum256Type, token: string): {rx: number; ry: number} {
+    if (token.length !== 9) throw new Error(`invalid region token length: ${token}`)
+    const lower = token.toLowerCase()
+    const d2 = unsyllable(lower.slice(0, 3))
+    const d1 = unsyllable(lower.slice(3, 6))
+    const d0 = unsyllable(lower.slice(6, 9))
+    const scrambled = (d2 * SYL_BASE + d1) * SYL_BASE + d0
+    if (scrambled >= REGION_FEISTEL.n) throw new Error(`invalid region token: ${token}`)
+    const index = unpermute(seed, scrambled, REGION_FEISTEL)
+    return {rx: Math.floor(index / REGION_PER_AXIS), ry: index % REGION_PER_AXIS}
+}

package/src/coordinates/sectors.ts

@@ -0,0 +1,115 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {SECTOR_FEISTEL, SECTORS_PER_AXIS} from './constants'
+import {permute, unpermute} from './permutation'
+
+// FROZEN INTERFACE — curation seed; review before launch, then never reorder.
+export const SECTOR_ADJECTIVES: readonly string[] = [
+    'Amber',
+    'Azure',
+    'Brass',
+    'Cinder',
+    'Cobalt',
+    'Copper',
+    'Coral',
+    'Crimson',
+    'Crystal',
+    'Dusk',
+    'Ember',
+    'Emerald',
+    'Frost',
+    'Glimmer',
+    'Golden',
+    'Hazy',
+    'Indigo',
+    'Iron',
+    'Ivory',
+    'Jade',
+    'Lunar',
+    'Misty',
+    'Neon',
+    'Onyx',
+    'Opal',
+    'Pearl',
+    'Plasma',
+    'Quartz',
+    'Rusty',
+    'Saffron',
+    'Scarlet',
+    'Silver',
+    'Solar',
+    'Static',
+    'Stormy',
+    'Sunny',
+    'Teal',
+    'Umber',
+    'Velvet',
+    'Verdant',
+    'Vermilion',
+    'Violet',
+    'Wispy',
+]
+
+export const SECTOR_NOUNS: readonly string[] = [
+    'Belt',
+    'Bluff',
+    'Cluster',
+    'Coil',
+    'Crest',
+    'Drift',
+    'Expanse',
+    'Fathom',
+    'Flare',
+    'Gulf',
+    'Halo',
+    'Haven',
+    'Hollow',
+    'Maw',
+    'Mesa',
+    'Mire',
+    'Notch',
+    'Nook',
+    'Oasis',
+    'Lagoon',
+    'Peak',
+    'Pocket',
+    'Reach',
+    'Reef',
+    'Ridge',
+    'Rift',
+    'Run',
+    'Shoal',
+    'Shroud',
+    'Span',
+    'Spire',
+    'Spur',
+    'Stretch',
+    'Sprawl',
+    'Tangle',
+    'Trace',
+    'Trench',
+    'Vale',
+    'Vault',
+    'Verge',
+    'Vortex',
+    'Ward',
+    'Wisp',
+]
+
+export function encodeSector(seed: Checksum256Type, sx: number, sy: number): string {
+    const index = sx * SECTORS_PER_AXIS + sy
+    const scrambled = permute(seed, index, SECTOR_FEISTEL)
+    const adj = Math.floor(scrambled / SECTORS_PER_AXIS)
+    const noun = scrambled % SECTORS_PER_AXIS
+    return `${SECTOR_ADJECTIVES[adj]} ${SECTOR_NOUNS[noun]}`
+}
+
+export function decodeSector(seed: Checksum256Type, name: string): {sx: number; sy: number} {
+    const parts = name.trim().split(/\s+/)
+    if (parts.length !== 2) throw new Error(`invalid sector name: ${name}`)
+    const adj = SECTOR_ADJECTIVES.indexOf(parts[0])
+    const noun = SECTOR_NOUNS.indexOf(parts[1])
+    if (adj < 0 || noun < 0) throw new Error(`unknown sector name: ${name}`)
+    const scrambled = adj * SECTORS_PER_AXIS + noun
+    const index = unpermute(seed, scrambled, SECTOR_FEISTEL)
+    return {sx: Math.floor(index / SECTORS_PER_AXIS), sy: index % SECTORS_PER_AXIS}
+}

package/src/data/capability-formulas.ts

@@ -23,7 +23,6 @@ const ENTITY_HULL_SLOTS: Record<number, SlotConsumer> = {
     0: {capability: 'Storage', attribute: 'capacity'},
     1: {capability: 'Hull', attribute: 'mass'},
     2: {capability: 'Storage', attribute: 'capacity'},
-    3: {capability: 'Storage', attribute: 'capacity'},
 }
 
 export const SLOT_FORMULAS: Record<SlotConsumerKind, Record<number, SlotConsumer>> = {

package/src/data/entities.json

@@ -58,11 +58,11 @@
     "slots": [
       {
         "type": "generator",
-        "outputPct": 100
+        "outputPct": 200
       },
       {
         "type": "gatherer",
-        "outputPct": 100
+        "outputPct": 200
       }
     ]
   },
@@ -71,11 +71,11 @@
     "slots": [
       {
         "type": "generator",
-        "outputPct": 100
+        "outputPct": 200
       },
       {
         "type": "crafter",
-        "outputPct": 100
+        "outputPct": 200
       }
     ]
   },

package/src/data/items.json

@@ -474,31 +474,31 @@
   },
   {
     "id": 10200,
-    "mass": 1300000,
+    "mass": 1900000,
     "type": "entity",
     "tier": 1
   },
   {
     "id": 10201,
-    "mass": 1900000,
+    "mass": 2400000,
     "type": "entity",
     "tier": 1
   },
   {
     "id": 10202,
-    "mass": 4800000,
+    "mass": 3200000,
     "type": "entity",
     "tier": 1
   },
   {
     "id": 10203,
-    "mass": 3700000,
+    "mass": 1900000,
     "type": "entity",
     "tier": 1
   },
   {
     "id": 10204,
-    "mass": 4600000,
+    "mass": 1900000,
     "type": "entity",
     "tier": 1
   },