@jgengine/core 0.10.0 → 0.11.0

package/dist/devtools/tunableSchema.js

@@ -6,12 +6,15 @@ export const MAX_SCAN_TARGETS = 512;
 const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 const DEFAULT_AXIS = ["x", "y", "z", "w"];
+/** @internal */
 export function isFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
+/** @internal */
 export function escapePathSegment(segment) {
     return segment.replace(/\\/g, "\\\\").replace(/\./g, "\\.");
 }
+/** @internal */
 export function unescapePathSegment(segment) {
     let out = "";
     for (let i = 0; i < segment.length; i += 1) {
@@ -25,10 +28,12 @@ export function unescapePathSegment(segment) {
     }
     return out;
 }
+/** @internal */
 export function joinTunablePath(parent, segment) {
     const escaped = escapePathSegment(segment);
     return parent === "" ? escaped : `${parent}.${escaped}`;
 }
+/** @internal */
 export function splitTunablePath(path) {
     const parts = [];
     let current = "";
@@ -49,6 +54,7 @@ export function splitTunablePath(path) {
     parts.push(unescapePathSegment(current));
     return parts;
 }
+/** @internal */
 export function parseColor(input) {
     if (typeof input !== "string" || !COLOR_PATTERN.test(input))
         return null;
@@ -81,6 +87,7 @@ export function parseColor(input) {
     const hex = `${rgb}${a.toLowerCase()}`;
     return { hex, rgb, alpha, hasAlpha: true };
 }
+/** @internal */
 export function formatColor(rgb, alpha, withAlpha) {
     const parsed = parseColor(rgb);
     const rgbHex = parsed?.rgb ?? (/^#[0-9a-fA-F]{6}$/.test(rgb) ? rgb.toLowerCase() : null);
@@ -94,6 +101,7 @@ export function formatColor(rgb, alpha, withAlpha) {
         .padStart(2, "0");
     return `${rgbHex}${a}`;
 }
+/** @internal */
 export function normalizeColorValue(input, forceAlpha) {
     const parsed = parseColor(input);
     if (parsed === null)
@@ -103,9 +111,11 @@ export function normalizeColorValue(input, forceAlpha) {
     }
     return parsed.rgb;
 }
+/** @internal */
 export function isColorString(value) {
     return typeof value === "string" && COLOR_PATTERN.test(value);
 }
+/** @internal */
 export function vecLength(kind) {
     if (kind === "vec2")
         return 2;
@@ -113,11 +123,13 @@ export function vecLength(kind) {
         return 3;
     return 4;
 }
+/** @internal */
 export function isNumericTuple(value, length) {
     if (!Array.isArray(value) || value.length !== length)
         return false;
     return value.every(isFiniteNumber);
 }
+/** @internal */
 export function isIntervalShape(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -127,6 +139,7 @@ export function isIntervalShape(value) {
         return false;
     return isFiniteNumber(record.min) && isFiniteNumber(record.max);
 }
+/** @internal */
 export function expandAxisMeta(length, labels, min, max, step, sample) {
     const resolvedLabels = Array.from({ length }, (_, i) => labels?.[i] ?? DEFAULT_AXIS[i] ?? `a${i}`);
     const resolvedMin = Array.from({ length }, (_, i) => {
@@ -154,15 +167,18 @@ export function expandAxisMeta(length, labels, min, max, step, sample) {
     });
     return { labels: resolvedLabels, min: resolvedMin, max: resolvedMax, step: resolvedStep };
 }
+/** @internal */
 export function clampAxisValue(value, min, max) {
     return Math.min(max, Math.max(min, value));
 }
+/** @internal */
 export function parseVec(kind, raw, bounds) {
     const length = vecLength(kind);
     if (!isNumericTuple(raw, length))
         return null;
     return raw.map((value, i) => clampAxisValue(value, bounds.min[i], bounds.max[i]));
 }
+/** @internal */
 export function parseInterval(raw, options) {
     if (!isIntervalShape(raw))
         return null;
@@ -200,6 +216,7 @@ export function parseInterval(raw, options) {
     }
     return { min: lo, max: hi };
 }
+/** @internal */
 export function convertAngle(value, from, to) {
     if (from === to)
         return value;
@@ -207,6 +224,7 @@ export function convertAngle(value, from, to) {
         return (value * Math.PI) / 180;
     return (value * 180) / Math.PI;
 }
+/** @internal */
 export function normalizeAngle(value, unit, options) {
     let next = value;
     if (options.wrap === true) {
@@ -225,6 +243,7 @@ export function normalizeAngle(value, unit, options) {
     }
     return next;
 }
+/** @internal */
 export function resolveChoices(options, choices) {
     if (choices !== undefined)
         return choices;
@@ -232,22 +251,26 @@ export function resolveChoices(options, choices) {
         return options.map((value) => ({ value }));
     return undefined;
 }
+/** @internal */
 export function choiceValues(choices) {
     if (choices === undefined)
         return undefined;
     return choices.map((choice) => choice.value);
 }
+/** @internal */
 export function findChoice(choices, raw) {
     if (choices === undefined)
         return undefined;
     return choices.find((choice) => Object.is(choice.value, raw));
 }
+/** @internal */
 export function parseEnumValue(raw, choices) {
     if (choices === undefined)
         return null;
     const match = findChoice(choices, raw);
     return match === undefined ? null : match.value;
 }
+/** @internal */
 export function coerceSelectWrite(raw, choices, options) {
     if (choices !== undefined) {
         const byValue = findChoice(choices, raw);
@@ -275,6 +298,7 @@ export function coerceSelectWrite(raw, choices, options) {
     }
     return raw;
 }
+/** @internal */
 export function inferKind(initial, options) {
     if (options?.kind !== undefined)
         return options.kind;
@@ -289,6 +313,7 @@ export function inferKind(initial, options) {
         return "color";
     return "text";
 }
+/** @internal */
 export function discoverableKind(value, meta) {
     if (meta?.kind !== undefined) {
         if (meta.kind === "vec2" || meta.kind === "vec3" || meta.kind === "vec4") {
@@ -320,6 +345,7 @@ export function discoverableKind(value, meta) {
         return "color";
     return null;
 }
+/** @internal */
 export function isScannableContainer(value) {
     if (value === null || typeof value !== "object")
         return false;
@@ -328,6 +354,7 @@ export function isScannableContainer(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/** @internal */
 export function ownWritableDataKeys(target) {
     return Object.keys(target).filter((key) => {
         if (UNSAFE_KEYS.has(key))
@@ -342,12 +369,14 @@ export function ownWritableDataKeys(target) {
         return true;
     });
 }
+/** @internal */
 export function sliderBounds(initial, options) {
     const min = options?.min ?? (initial < 0 ? initial * 2 : 0);
     const max = options?.max ?? (initial > 0 ? initial * 2 : initial < 0 ? 0 : 1);
     const step = options?.step ?? (max - min) / 100;
     return { min, max, step };
 }
+/** @internal */
 export function validateControlValue(kind, raw, context) {
     switch (kind) {
         case "slider": {
@@ -420,6 +449,7 @@ export function validateControlValue(kind, raw, context) {
             return { ok: false, reason: "unknown kind" };
     }
 }
+/** @internal */
 export function parseOverridesPayload(raw) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
         return { overrides: null, diagnostics: ["overrides payload is not an object"] };
@@ -467,6 +497,7 @@ export function parseOverridesPayload(raw) {
         diagnostics: version === 0 ? ["migrated unversioned overrides to v1"] : [],
     };
 }
+/** @internal */
 export function cloneValue(value) {
     if (Array.isArray(value))
         return value.slice();

package/dist/economy/currency.d.ts

@@ -15,11 +15,22 @@ export type CurrencyAdjustment = {
     success: false;
     reason: string;
 };
+/** @internal */
 export declare function sanitizeCurrencyAmount(amount: number): number;
+/**
+ * Format a currency amount with its symbol and grouping for HUD display.
+ *
+ * @capability currency-format format a currency amount with its symbol for display
+  * @internal
+  */
 export declare function formatCurrencyAmount(currency: CurrencyDefinition, amount: number): string;
+/** @internal */
 export declare function insufficientCurrencyReason(currency: CurrencyDefinition, needed: number, current: number): string;
+/** @internal */
 export declare function applyCurrencyOperation(currency: CurrencyDefinition, current: number, operation: CurrencyOperation, amount: number): CurrencyAdjustment;
-/** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full. */
+/** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full.
+ * @internal
+ */
 export declare function resolveCurrencyDelta(current: number, delta: number): {
     operation: CurrencyOperation;
     amount: number;

package/dist/economy/currency.js

@@ -1,14 +1,23 @@
+/** @internal */
 export function sanitizeCurrencyAmount(amount) {
     return Math.max(0, Math.floor(amount));
 }
+/**
+ * Format a currency amount with its symbol and grouping for HUD display.
+ *
+ * @capability currency-format format a currency amount with its symbol for display
+  * @internal
+  */
 export function formatCurrencyAmount(currency, amount) {
     const prefix = currency.symbol ?? "";
     const suffix = currency.unit ? ` ${currency.unit}` : "";
     return `${prefix}${amount}${suffix}`;
 }
+/** @internal */
 export function insufficientCurrencyReason(currency, needed, current) {
     return `Insufficient ${currency.id}: need ${formatCurrencyAmount(currency, needed)}, have ${formatCurrencyAmount(currency, current)}`;
 }
+/** @internal */
 export function applyCurrencyOperation(currency, current, operation, amount) {
     const safeAmount = sanitizeCurrencyAmount(amount);
     if (safeAmount === 0)
@@ -19,7 +28,9 @@ export function applyCurrencyOperation(currency, current, operation, amount) {
     const appliedDelta = operation === "add" ? safeAmount : -safeAmount;
     return { success: true, newBalance: current + appliedDelta, appliedDelta };
 }
-/** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full. */
+/** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full.
+ * @internal
+ */
 export function resolveCurrencyDelta(current, delta) {
     const safeDelta = Math.floor(delta);
     if (safeDelta > 0)

package/dist/economy/listingBook.d.ts

@@ -0,0 +1,91 @@
+import type { ItemStack } from "../inventory/storageTier.js";
+/** One active post in a {@link ListingBook}: an item stack a seller offered at a fixed price until it expires. */
+export interface Listing {
+    readonly id: string;
+    readonly sellerId: string;
+    readonly itemId: string;
+    readonly count: number;
+    readonly price: number;
+    readonly currency: string;
+    readonly listedAt: number;
+    readonly expiresAt: number;
+}
+/** Tunables for {@link createListingBook} — per-seller listing cap, expiry window, house cut, and optional price bounds. */
+export interface ListingBookConfig {
+    maxListingsPerSeller: number;
+    expirySeconds: number;
+    cutRate: number;
+    minPrice?: number;
+    maxPrice?: number;
+}
+/** Input to {@link ListingBook.post} — the goods, asking price, and current game-time to stamp the listing with. */
+export interface PostListingInput {
+    id?: string;
+    sellerId: string;
+    itemId: string;
+    count: number;
+    price: number;
+    currency: string;
+    now: number;
+}
+/** Why {@link ListingBook.post} refused a listing. */
+export type PostListingReason = "invalid-count" | "invalid-price" | "price-too-low" | "price-too-high" | "listing-cap-reached";
+/** Result of {@link ListingBook.post}. */
+export type PostListingResult = {
+    status: "ok";
+    listing: Listing;
+} | {
+    status: "rejected";
+    reason: PostListingReason;
+};
+/** Result of {@link ListingBook.cancel}. */
+export type CancelListingResult = {
+    status: "ok";
+    listing: Listing;
+} | {
+    status: "rejected";
+    reason: "not-found" | "not-owner";
+};
+/** The financial split of a completed sale: total price, the house's cut, and what the seller's collection box was credited. */
+export interface BuyListingOutcome {
+    listing: Listing;
+    houseCut: number;
+    sellerProceeds: number;
+}
+/** Result of {@link ListingBook.buy}. */
+export type BuyListingResult = {
+    status: "ok";
+    outcome: BuyListingOutcome;
+} | {
+    status: "rejected";
+    reason: "not-found" | "expired" | "own-listing";
+};
+/** A read-only view of a seller's collection box — currency and item stacks waiting to be claimed. */
+export interface CollectionBoxSnapshot {
+    currency: Readonly<Record<string, number>>;
+    items: readonly ItemStack[];
+}
+/** A player-driven marketplace of {@link Listing}s plus the per-seller collection boxes behind it. See {@link createListingBook}. */
+export interface ListingBook {
+    post(input: PostListingInput): PostListingResult;
+    cancel(listingId: string, sellerId: string): CancelListingResult;
+    buy(listingId: string, buyerId: string, now: number): BuyListingResult;
+    sweepExpired(now: number): readonly Listing[];
+    get(listingId: string): Listing | null;
+    active(): readonly Listing[];
+    listingsOf(sellerId: string): readonly Listing[];
+    countOf(sellerId: string): number;
+    collectionOf(sellerId: string): CollectionBoxSnapshot;
+    claimCurrency(sellerId: string): Readonly<Record<string, number>>;
+    claimItem(sellerId: string, itemId: string, count: number): boolean;
+}
+/**
+ * A player-driven listing marketplace: post/cancel/buy against a shared book with a house cut on
+ * every sale, an expiry sweep that pulls unsold goods out of circulation, and a per-seller
+ * collection box holding sale proceeds and returned items until claimed. Buyer/seller wallet and
+ * inventory movement is the caller's job (mirrors `game/trade`'s split) — this primitive owns only
+ * the listing lifecycle and the escrowed collection-box bookkeeping behind it.
+ *
+ * @capability listing-book player-driven marketplace listings with a house cut, expiry sweep, and seller collection box
+ */
+export declare function createListingBook(config: ListingBookConfig): ListingBook;

package/dist/economy/listingBook.js

@@ -0,0 +1,144 @@
+/**
+ * A player-driven listing marketplace: post/cancel/buy against a shared book with a house cut on
+ * every sale, an expiry sweep that pulls unsold goods out of circulation, and a per-seller
+ * collection box holding sale proceeds and returned items until claimed. Buyer/seller wallet and
+ * inventory movement is the caller's job (mirrors `game/trade`'s split) — this primitive owns only
+ * the listing lifecycle and the escrowed collection-box bookkeeping behind it.
+ *
+ * @capability listing-book player-driven marketplace listings with a house cut, expiry sweep, and seller collection box
+ */
+export function createListingBook(config) {
+    const listings = new Map();
+    const boxes = new Map();
+    let counter = 0;
+    function boxOf(sellerId) {
+        let box = boxes.get(sellerId);
+        if (box === undefined) {
+            box = { currency: {}, items: [] };
+            boxes.set(sellerId, box);
+        }
+        return box;
+    }
+    function creditCurrency(sellerId, currency, amount) {
+        const box = boxOf(sellerId);
+        box.currency[currency] = (box.currency[currency] ?? 0) + amount;
+    }
+    function creditItem(sellerId, itemId, count) {
+        const box = boxOf(sellerId);
+        const existing = box.items.find((stack) => stack.itemId === itemId);
+        if (existing !== undefined)
+            existing.count += count;
+        else
+            box.items.push({ itemId, count });
+    }
+    function countOf(sellerId) {
+        let total = 0;
+        for (const listing of listings.values())
+            if (listing.sellerId === sellerId)
+                total += 1;
+        return total;
+    }
+    return {
+        post(input) {
+            if (!Number.isInteger(input.count) || input.count < 1) {
+                return { status: "rejected", reason: "invalid-count" };
+            }
+            if (!Number.isFinite(input.price) || input.price <= 0) {
+                return { status: "rejected", reason: "invalid-price" };
+            }
+            if (config.minPrice !== undefined && input.price < config.minPrice) {
+                return { status: "rejected", reason: "price-too-low" };
+            }
+            if (config.maxPrice !== undefined && input.price > config.maxPrice) {
+                return { status: "rejected", reason: "price-too-high" };
+            }
+            if (countOf(input.sellerId) >= config.maxListingsPerSeller) {
+                return { status: "rejected", reason: "listing-cap-reached" };
+            }
+            const id = input.id ?? `listing_${(counter += 1)}`;
+            const listing = {
+                id,
+                sellerId: input.sellerId,
+                itemId: input.itemId,
+                count: input.count,
+                price: input.price,
+                currency: input.currency,
+                listedAt: input.now,
+                expiresAt: input.now + config.expirySeconds,
+            };
+            listings.set(id, listing);
+            return { status: "ok", listing };
+        },
+        cancel(listingId, sellerId) {
+            const listing = listings.get(listingId);
+            if (listing === undefined)
+                return { status: "rejected", reason: "not-found" };
+            if (listing.sellerId !== sellerId)
+                return { status: "rejected", reason: "not-owner" };
+            listings.delete(listingId);
+            return { status: "ok", listing };
+        },
+        buy(listingId, buyerId, now) {
+            const listing = listings.get(listingId);
+            if (listing === undefined)
+                return { status: "rejected", reason: "not-found" };
+            if (listing.sellerId === buyerId)
+                return { status: "rejected", reason: "own-listing" };
+            if (listing.expiresAt <= now)
+                return { status: "rejected", reason: "expired" };
+            listings.delete(listingId);
+            const houseCut = Math.floor(listing.price * config.cutRate);
+            const sellerProceeds = listing.price - houseCut;
+            creditCurrency(listing.sellerId, listing.currency, sellerProceeds);
+            return { status: "ok", outcome: { listing, houseCut, sellerProceeds } };
+        },
+        sweepExpired(now) {
+            const expired = [];
+            for (const listing of listings.values()) {
+                if (listing.expiresAt <= now)
+                    expired.push(listing);
+            }
+            for (const listing of expired) {
+                listings.delete(listing.id);
+                creditItem(listing.sellerId, listing.itemId, listing.count);
+            }
+            return expired;
+        },
+        get(listingId) {
+            return listings.get(listingId) ?? null;
+        },
+        active() {
+            return [...listings.values()];
+        },
+        listingsOf(sellerId) {
+            return [...listings.values()].filter((listing) => listing.sellerId === sellerId);
+        },
+        countOf,
+        collectionOf(sellerId) {
+            const box = boxes.get(sellerId);
+            if (box === undefined)
+                return { currency: {}, items: [] };
+            return { currency: { ...box.currency }, items: box.items.map((stack) => ({ ...stack })) };
+        },
+        claimCurrency(sellerId) {
+            const box = boxOf(sellerId);
+            const claimed = box.currency;
+            box.currency = {};
+            return claimed;
+        },
+        claimItem(sellerId, itemId, count) {
+            const box = boxOf(sellerId);
+            const index = box.items.findIndex((stack) => stack.itemId === itemId);
+            if (index === -1)
+                return false;
+            const stack = box.items[index];
+            if (stack.count < count)
+                return false;
+            if (stack.count === count)
+                box.items.splice(index, 1);
+            else
+                box.items[index] = { ...stack, count: stack.count - count };
+            return true;
+        },
+    };
+}