@jgengine/core 0.30.0 → 0.31.0

package/dist/loot/lootGen.js

@@ -18,6 +18,10 @@ export function assertLootCatalog(catalog) {
         baseIds.add(base.id);
         if (base.weight !== undefined)
             check(base.weight > 0, `Loot base "${base.id}" weight must be positive`);
+        if (base.minLevel !== undefined)
+            check(Number.isInteger(base.minLevel) && base.minLevel >= 1, `Loot base "${base.id}" minLevel must be an integer >= 1`);
+        if (base.mass !== undefined)
+            check(Number.isFinite(base.mass) && base.mass > 0, `Loot base "${base.id}" mass must be positive`);
     }
     const poolIds = new Set();
     const affixIds = new Set();
@@ -29,6 +33,8 @@ export function assertLootCatalog(catalog) {
             check(!affixIds.has(affix.id), `Loot affix "${affix.id}" is declared twice`);
             affixIds.add(affix.id);
             check(affix.weight > 0, `Loot affix "${affix.id}" weight must be positive`);
+            if (affix.minLevel !== undefined)
+                check(Number.isInteger(affix.minLevel) && affix.minLevel >= 1, `Loot affix "${affix.id}" minLevel must be an integer >= 1`);
             if (typeof affix.roll === "number") {
                 check(Number.isFinite(affix.roll), `Loot affix "${affix.id}" roll must be finite`);
                 if (affix.op === "mul")
@@ -148,7 +154,7 @@ function weighted(rng, items, weightOf, field) {
         throw new Error(`Loot catalog has no eligible ${field}`);
     return picked;
 }
-function candidateAffixes(catalog, base, rarity) {
+function candidateAffixes(catalog, base, rarity, level) {
     const out = [];
     for (const poolId of base.pools) {
         if (rarity.pools !== undefined && !rarity.pools.includes(poolId))
@@ -156,8 +162,11 @@ function candidateAffixes(catalog, base, rarity) {
         const pool = catalog.pools.find((entry) => entry.id === poolId);
         if (pool === undefined)
             continue;
-        for (const affix of pool.affixes)
+        for (const affix of pool.affixes) {
+            if (affix.minLevel !== undefined && affix.minLevel > level)
+                continue;
             out.push({ affix, poolId });
+        }
     }
     return out;
 }
@@ -192,11 +201,13 @@ export function rollLoot(catalog, rng, options = {}) {
     const manufacturer = options.manufacturer === undefined
         ? weighted(rng, catalog.manufacturers.filter((maker) => options.baseId === undefined || maker.bases === undefined || maker.bases.includes(options.baseId)), (maker) => maker.weight ?? 1, "manufacturer")
         : findOrThrow(catalog.manufacturers, options.manufacturer, "manufacturer");
-    const basePool = catalog.bases.filter((base) => manufacturer.bases === undefined || manufacturer.bases.includes(base.id));
+    const basePool = catalog.bases.filter((base) => (base.minLevel === undefined || base.minLevel <= level)
+        && (manufacturer.bases === undefined || manufacturer.bases.includes(base.id)));
     const base = options.baseId === undefined
         ? weighted(rng, basePool, (entry) => entry.weight ?? 1, "base")
         : findOrThrow(catalog.bases, options.baseId, "base");
     check(manufacturer.bases === undefined || manufacturer.bases.includes(base.id), `Loot manufacturer "${manufacturer.id}" does not produce base "${base.id}"`);
+    check(base.minLevel === undefined || base.minLevel <= level, `Loot base "${base.id}" needs item level ${base.minLevel}, got ${level}`);
     const rarity = options.rarity === undefined
         ? weighted(rng, catalog.rarities, (tier) => tier.weight, "rarity")
         : findOrThrow(catalog.rarities, options.rarity, "rarity");
@@ -206,7 +217,7 @@ export function rollLoot(catalog, rng, options = {}) {
         const part = weighted(rng, eligible, (entry) => entry.weight ?? 1, `part for slot "${slot.id}"`);
         parts.push({ slotId: slot.id, partId: part.id, category: part.category });
     }
-    const candidates = candidateAffixes(catalog, base, rarity);
+    const candidates = candidateAffixes(catalog, base, rarity, level);
     const favors = manufacturer.favoredPools ?? [];
     const favorWeight = manufacturer.favoredWeight ?? 3;
     const remaining = candidates.slice();
@@ -254,6 +265,7 @@ export function rollLoot(catalog, rng, options = {}) {
     }
     for (const stat of Object.keys(stats))
         stats[stat] = Math.round(stats[stat] * 1000) / 1000;
+    const mass = Math.round((base.mass ?? 1) * (1 + 0.1 * (level - 1)) * 100) / 100;
     return {
         baseId: base.id,
         manufacturer: manufacturer.id,
@@ -263,6 +275,7 @@ export function rollLoot(catalog, rng, options = {}) {
         parts,
         affixes,
         stats,
+        mass,
     };
 }
 /**
@@ -280,6 +293,9 @@ export function validateLootItem(item, catalog) {
     if (base === undefined) {
         issues.push({ code: "unknown-base", detail: `base "${item.baseId}" is not in the catalog` });
     }
+    else if (base.minLevel !== undefined && base.minLevel > item.level) {
+        issues.push({ code: "level-gated-base", detail: `base "${base.id}" needs item level ${base.minLevel}, got ${item.level}` });
+    }
     const manufacturer = catalog.manufacturers.find((entry) => entry.id === item.manufacturer);
     if (manufacturer === undefined) {
         issues.push({ code: "unknown-manufacturer", detail: `manufacturer "${item.manufacturer}" is not in the catalog` });
@@ -316,7 +332,7 @@ export function validateLootItem(item, catalog) {
         if (!seenSlots.has(slot.id))
             issues.push({ code: "missing-slot-part", detail: `slot "${slot.id}" has no part` });
     }
-    const allowed = base === undefined || rarity === undefined ? null : candidateAffixes(catalog, base, rarity);
+    const allowed = base === undefined || rarity === undefined ? null : candidateAffixes(catalog, base, rarity, item.level);
     const seenAffixes = new Set();
     for (const affix of item.affixes) {
         if (seenAffixes.has(affix.id)) {
@@ -335,6 +351,9 @@ export function validateLootItem(item, catalog) {
         if (!Number.isFinite(value))
             issues.push({ code: "non-finite-stat", detail: `stat "${stat}" is ${String(value)}` });
     }
+    if (item.mass !== undefined && (!Number.isFinite(item.mass) || item.mass <= 0)) {
+        issues.push({ code: "invalid-mass", detail: `mass ${String(item.mass)} is not a positive number` });
+    }
     if (item.name.trim() === "")
         issues.push({ code: "empty-name", detail: "item has no name" });
     return issues;

package/dist/loot/salvage.d.ts

@@ -0,0 +1,74 @@
+/** Where an item instance stands: still usable, broken down, or sold. */
+export type ItemLifecycle = "owned" | "salvaged" | "sold";
+/** Items that have left play, keyed by instance id; anything absent is still `owned`. */
+export type ItemLedgerState = Readonly<Record<string, Exclude<ItemLifecycle, "owned">>>;
+/**
+ * One record of what happened to rolled item instances. Every path that removes an item - salvage,
+ * sale, granting a duplicate - claims it here first, so a second claim returns false and the item
+ * cannot be equipped, sold or broken down twice.
+ */
+export interface ItemLedger {
+    status(id: string): ItemLifecycle;
+    /** True only while the instance is `owned`; a salvaged or sold item is no longer usable. */
+    canUse(id: string): boolean;
+    /** Claim `id` for `salvaged` or `sold`; false when it already left play. */
+    spend(id: string, how: Exclude<ItemLifecycle, "owned">): boolean;
+    snapshot(): ItemLedgerState;
+    /** Replace the ledger; false without mutation when an entry names an unknown outcome. */
+    restore(next: ItemLedgerState): boolean;
+    reset(): void;
+}
+/**
+ * Build an item ledger. Ids are consumed once: the first successful {@link ItemLedger.spend} wins,
+ * every later call fails, which is what makes salvage and sale mutually exclusive.
+ *
+ * @capability item-ledger track which rolled item instances are still owned, salvaged or sold
+ */
+export declare function createItemLedger(initial?: ItemLedgerState): ItemLedger;
+/** The currency and amount one salvage yields. `currency` is the game's key, never interpreted. */
+export interface SalvageYield {
+    currency: string;
+    amount: number;
+}
+/** What a broken-down item is worth: a game-authored currency, rate and per-rarity multiplier. */
+export interface SalvageTable {
+    /** Wallet currency key the yield is granted in, e.g. `"cores"`. */
+    currency: string;
+    /** Units paid per item level at multiplier `1`. */
+    perLevel: number;
+    /** Multiplier per rarity id; omitted rarities use `1`. */
+    rarityMultiplier?: Readonly<Record<string, number>>;
+    /** Floor for the yield (default `1`). */
+    minimum?: number;
+}
+/**
+ * The yield an item of this level and rarity breaks down into. The formula is
+ * `round(perLevel x level x rarityMultiplier)`, floored by `minimum`, so the same item always yields
+ * the same amount and a higher level never yields less.
+ *
+ * @capability item-salvage-value compute the currency an item of a level and rarity breaks down into
+ */
+export declare function salvageValue(item: Pick<ItemDropLike, "level" | "rarity">, table: SalvageTable): SalvageYield;
+/** The fields salvage reads; an `ItemDrop` from `./drop` satisfies it. */
+export interface ItemDropLike {
+    id: string;
+    level: number;
+    rarity: string;
+}
+/** Salvage outcome: the yield, or the reason the instance could not be broken down. */
+export type SalvageResult = {
+    ok: true;
+    id: string;
+    yield: SalvageYield;
+} | {
+    ok: false;
+    reason: "already-spent" | "invalid-item";
+};
+/**
+ * Break one item down through its ledger. The ledger is claimed before the yield is computed, so a
+ * salvaged item cannot be salvaged, equipped or sold again; pass the game's own wallet update from
+ * `yield`.
+ *
+ * @capability item-salvage break an item down for the currency its level and rarity say, once
+ */
+export declare function salvageItem(item: ItemDropLike, table: SalvageTable, ledger: ItemLedger): SalvageResult;

package/dist/loot/salvage.js

@@ -0,0 +1,68 @@
+/**
+ * Build an item ledger. Ids are consumed once: the first successful {@link ItemLedger.spend} wins,
+ * every later call fails, which is what makes salvage and sale mutually exclusive.
+ *
+ * @capability item-ledger track which rolled item instances are still owned, salvaged or sold
+ */
+export function createItemLedger(initial = {}) {
+    const spent = new Map();
+    for (const [id, how] of Object.entries(initial)) {
+        if (how === "salvaged" || how === "sold")
+            spent.set(id, how);
+    }
+    return {
+        status: (id) => spent.get(id) ?? "owned",
+        canUse: (id) => !spent.has(id),
+        spend(id, how) {
+            if (spent.has(id))
+                return false;
+            spent.set(id, how);
+            return true;
+        },
+        snapshot: () => Object.fromEntries(spent),
+        restore(next) {
+            if (next === null || typeof next !== "object")
+                return false;
+            const staged = new Map();
+            for (const [id, how] of Object.entries(next)) {
+                if (how !== "salvaged" && how !== "sold")
+                    return false;
+                if (id.trim() === "")
+                    return false;
+                staged.set(id, how);
+            }
+            spent.clear();
+            for (const [id, how] of staged)
+                spent.set(id, how);
+            return true;
+        },
+        reset: () => spent.clear(),
+    };
+}
+/**
+ * The yield an item of this level and rarity breaks down into. The formula is
+ * `round(perLevel x level x rarityMultiplier)`, floored by `minimum`, so the same item always yields
+ * the same amount and a higher level never yields less.
+ *
+ * @capability item-salvage-value compute the currency an item of a level and rarity breaks down into
+ */
+export function salvageValue(item, table) {
+    const multiplier = table.rarityMultiplier?.[item.rarity] ?? 1;
+    const amount = Math.max(table.minimum ?? 1, Math.round(table.perLevel * Math.max(1, item.level) * multiplier));
+    return { currency: table.currency, amount };
+}
+/**
+ * Break one item down through its ledger. The ledger is claimed before the yield is computed, so a
+ * salvaged item cannot be salvaged, equipped or sold again; pass the game's own wallet update from
+ * `yield`.
+ *
+ * @capability item-salvage break an item down for the currency its level and rarity say, once
+ */
+export function salvageItem(item, table, ledger) {
+    if (!Number.isFinite(item.level) || item.level < 1 || item.id.trim() === "") {
+        return { ok: false, reason: "invalid-item" };
+    }
+    if (!ledger.spend(item.id, "salvaged"))
+        return { ok: false, reason: "already-spent" };
+    return { ok: true, id: item.id, yield: salvageValue(item, table) };
+}

package/dist/loot/vendor.d.ts

@@ -0,0 +1,76 @@
+import type { ShopStock, ShopStockEntry } from "../economy/shopStock.js";
+import { type LootCatalog, type LootItem } from "./lootGen.js";
+import type { ItemDrop } from "./drop.js";
+/** How a vendor price is derived from an item: a base, a per-level rate and a rarity multiplier. */
+export interface VendorPriceRule {
+    /** Wallet currency key the stock is priced in, e.g. `"credits"`. */
+    currency: string;
+    /** Price floor at level 1 before the rarity multiplier. */
+    base: number;
+    /** Added per item level. */
+    perLevel: number;
+    /** Multiplier per rarity id; omitted rarities use `1`. */
+    rarityMultiplier?: Readonly<Record<string, number>>;
+    /** Buy-back fraction of the buy price; omitted means the vendor does not buy this stock back. */
+    sellFactor?: number;
+}
+/** One stocked item and the shop entry that prices it. */
+export interface VendorOffer {
+    item: ItemDrop;
+    entry: ShopStockEntry;
+}
+/** What stocking a vendor reads: the roll catalog, a seeded rng and the pricing policy. */
+export interface StockVendorOptions {
+    catalog: LootCatalog;
+    /** Injected random source; pass a seeded generator so the shelf is reproducible. */
+    rng: () => number;
+    /** Item level rolled onto the shelf. */
+    level: number;
+    /** How many items to roll. */
+    count: number;
+    price: VendorPriceRule;
+    /** Stable id prefix for this vendor, e.g. `"harbor.guns"`. */
+    idPrefix: string;
+    /** Whole units on hand; `null` means unlimited (default `1`). */
+    qty?: number | null;
+}
+/**
+ * The price of one item under a `VendorPriceRule`: `round(base + perLevel x level)` times the
+ * rarity multiplier, never below 1. Sell-back is `floor(price x sellFactor)` when the rule sets one.
+ *
+ * @capability item-vendor-price price an item from its level and rarity through the economy's currency
+ */
+export declare function itemPrice(item: Pick<LootItem, "level" | "rarity">, rule: VendorPriceRule): {
+    buy: number;
+    sell: number | null;
+};
+/**
+ * Roll a vendor's shelf and add it to an existing {@link ShopStock}. Entries added by a previous
+ * call with the same `idPrefix` are removed first, so a refresh replaces the shelf instead of
+ * throwing on duplicate ids. Buying, selling and wallet charging stay in the economy owner.
+ *
+ * @capability item-vendor stock a vendor with rolled items priced through the shared economy
+ */
+export declare function stockVendor(shop: ShopStock, options: StockVendorOptions): VendorOffer[];
+/** Where a vendor shelf stands: the run number it was last stocked on. */
+export interface VendorRotationState {
+    refreshedAt: number;
+}
+/** A run-count refresh rule; the game owns how many runs between restocks. */
+export interface VendorRotation {
+    /** True when `run` is at least `everyRuns` past the last refresh. */
+    due(run: number): boolean;
+    /** Record that the shelf was stocked on `run`. */
+    mark(run: number): void;
+    state(): VendorRotationState;
+    restore(next: VendorRotationState): boolean;
+    reset(run?: number): void;
+}
+/**
+ * A restock rule the game authors as "every N runs". It only answers when a refresh is due; the
+ * game calls {@link stockVendor} and then `mark`. No timer, so a paused or reloaded save keeps the
+ * same shelf until the run count moves.
+ *
+ * @capability item-vendor-rotation decide when a vendor's shelf is due for a restock
+ */
+export declare function createVendorRotation(everyRuns: number, start?: number): VendorRotation;

package/dist/loot/vendor.js

@@ -0,0 +1,72 @@
+import { rollLoot } from "./lootGen.js";
+/**
+ * The price of one item under a `VendorPriceRule`: `round(base + perLevel x level)` times the
+ * rarity multiplier, never below 1. Sell-back is `floor(price x sellFactor)` when the rule sets one.
+ *
+ * @capability item-vendor-price price an item from its level and rarity through the economy's currency
+ */
+export function itemPrice(item, rule) {
+    const multiplier = rule.rarityMultiplier?.[item.rarity] ?? 1;
+    const buy = Math.max(1, Math.round((rule.base + rule.perLevel * Math.max(1, item.level)) * multiplier));
+    const sell = rule.sellFactor === undefined ? null : Math.max(0, Math.floor(buy * rule.sellFactor));
+    return { buy, sell };
+}
+/**
+ * Roll a vendor's shelf and add it to an existing {@link ShopStock}. Entries added by a previous
+ * call with the same `idPrefix` are removed first, so a refresh replaces the shelf instead of
+ * throwing on duplicate ids. Buying, selling and wallet charging stay in the economy owner.
+ *
+ * @capability item-vendor stock a vendor with rolled items priced through the shared economy
+ */
+export function stockVendor(shop, options) {
+    for (const entry of shop.list()) {
+        if (entry.id.startsWith(`${options.idPrefix}:`))
+            shop.remove(entry.id);
+    }
+    const offers = [];
+    for (let i = 0; i < Math.max(0, Math.floor(options.count)); i += 1) {
+        const item = {
+            ...rollLoot(options.catalog, options.rng, { level: options.level }),
+            id: `${options.idPrefix}:${i}`,
+        };
+        const price = itemPrice(item, options.price);
+        const entry = {
+            id: item.id,
+            kind: item.baseId,
+            price: { currency: options.price.currency, amount: price.buy },
+            qty: options.qty === undefined ? 1 : options.qty,
+            ...(price.sell === null ? {} : { sellPrice: { currency: options.price.currency, amount: price.sell } }),
+        };
+        shop.add(entry);
+        offers.push({ item, entry });
+    }
+    return offers;
+}
+/**
+ * A restock rule the game authors as "every N runs". It only answers when a refresh is due; the
+ * game calls {@link stockVendor} and then `mark`. No timer, so a paused or reloaded save keeps the
+ * same shelf until the run count moves.
+ *
+ * @capability item-vendor-rotation decide when a vendor's shelf is due for a restock
+ */
+export function createVendorRotation(everyRuns, start = 0) {
+    if (!Number.isFinite(everyRuns) || everyRuns < 1)
+        throw new RangeError("everyRuns must be >= 1");
+    let refreshedAt = start;
+    return {
+        due: (run) => run - refreshedAt >= everyRuns,
+        mark: (run) => {
+            refreshedAt = run;
+        },
+        state: () => ({ refreshedAt }),
+        restore(next) {
+            if (next === null || typeof next !== "object" || !Number.isFinite(next.refreshedAt))
+                return false;
+            refreshedAt = next.refreshedAt;
+            return true;
+        },
+        reset(run = 0) {
+            refreshedAt = run;
+        },
+    };
+}

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.30.0";
+export declare const VERSION = "0.31.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,34 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.30.0";
+export const VERSION = "0.31.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.31.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.31.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.28.0`; `@jgengine/github` is `0.18.0`.",
+        ],
+        added: [
+            "`createAgent` (`@jgengine/core/agents/agent`) runs one resident's whole loop on the world clock: needs decay through `sim/needs`, a utility brain picks among the targets the game offers, an authored day plan says where the agent belongs, and the agent falls back to a declared target when its pick disappears. Mood, action and the far flag snapshot and restore with the needs.",
+            "`createMoodReader` / `readMood` (`@jgengine/core/agents/mood`) derive a 0-100 mood and a caller-labelled tier from weighted need satisfaction, plus named sources a queue, a litter patch or a cold snap raises and clears.",
+            "`createAgentSchedule` (`@jgengine/core/agents/schedule`) resolves an authored day plan through `sim/routine` and adds a work beat: a stop names the places it patrols, so a janitor is an agent with a route rather than a special case. Off-hours behaviour is a stop without a beat.",
+            "`createRelationshipBook` (`@jgengine/core/agents/relationships`) keeps undirected familiarity and opinion per pair. A social action moves both and reports the milestones crossed, friends prefer each other's company, and a bonded pair refuses to split. Pair keys come from `relation/keyedValues` and crossings from `relation/thresholds`.",
+            "`GameSave.deleteSlot(slot)` and `SaveStore.deleteSlot(slot)` remove one slot's payload and drop it from the slot index; they resolve `true` when a document was removed and `false` for an unknown slot. Deleting the active slot resets the live state to the initial document. `load()` no longer lists a slot that holds nothing, so a deleted slot cannot return.",
+            "`HudPanel` takes `lane` (`@jgengine/react`): blocks naming the same anchor and lane stack without overlap, lanes in one anchor sit side by side, and `resolveHudLanes` resolves the rectangles. A moved panel leaves its lane and keeps its authored placement.",
+            "`hudBlockOverlaps` and `formatHudOverlapReport` (`@jgengine/react`) name every pair of rendered HUD blocks whose rectangles intersect, with both ids and the viewport; `HudCanvas` warns with that report in a dev build.",
+            "`rollDrop` (`@jgengine/core/loot/drop`) rolls one deterministic item from a seed and `compareToEquipped` turns it into per-stat deltas against worn gear with a weighted verdict a HUD can render.",
+            "`createRunHaul` (`@jgengine/core/loot/haul`) gates carried loot by weight through the shared encumbrance rules, banks what the persistent stash fits, and discards the run's haul when the game calls `fail`.",
+            "`salvageItem` and `createItemLedger` (`@jgengine/core/loot/salvage`) break an item down for the currency its level and rarity say and claim the instance, so a salvaged item cannot be salvaged, equipped or sold again.",
+            "`stockVendor` and `createVendorRotation` (`@jgengine/core/loot/vendor`) fill a `ShopStock` with rolled items priced through the economy wallet, with a run-count restock rule the game authors.",
+            "`markerProximity` on `createMissionRuntime` picks the plane a marker proximity test compares in: `\"horizontal\"` (default) measures ground distance and allows the actor a `tolerance` (default 8 m) above or below the marker, `\"spatial\"` is the straight 3D check for worlds with stacked platforms. `MissionMarkerPlane`, `MissionMarkerProximity` and `DEFAULT_MARKER_TOLERANCE` are exported with it.",
+        ],
+        changed: [
+            "`evaluatePressure` (`@jgengine/core/ai/director/pressure`) reads pressure as player control: a healthy player further into a run is leaned on harder, a hurt player is eased off, and every effect stays inside the rule's `maxTier`.",
+            "Loot bases and affixes take `minLevel`, so `rollLoot` only draws from entries at or below the item level. Loot bases take `mass`; rolled items carry it for carry checks.",
+            "`HudCanvas` resolved its host with `canvas.parentElement`, which is `HudThemeRoot`'s `display: contents` element and measures 0x0 — the boundary overlay, the HUD-fit measurement and the new overlap report never ran under the standard HUD root. It now uses the nearest ancestor with a real box.",
+            "The HUD boundary check returned early whenever nothing overflowed, so a later report in the same pass could never run.",
+            "`reach`, `interact` and the `left-area` fail condition compared a marker in 3D, so a marker authored at `y=0` under rising ground was unreachable. They now read the same plane.",
+        ],
+        removed: [],
+    },
     "0.30.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.30.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.27.0`; `@jgengine/github` is `0.17.0`.",

package/dist/mission/mission.d.ts

@@ -341,6 +341,8 @@ export interface MissionRuntimeConfig {
     readonly missions: readonly MissionDef[];
     /** Marker positions resolved from the authored scene, by marker id. See `missionMarkers`. */
     readonly markers?: Readonly<Record<string, ScenePoint3>>;
+    /** How marker proximity is measured for `reach`, `interact` and `left-area`. Default horizontal. */
+    readonly markerProximity?: MissionMarkerProximity;
     /** Actor id used for a `pursue` objective that names no `pursuer`. */
     readonly defaultPursuer?: string;
     /** `[0,1)` source for a mission's `rollout`; pass `ctx.rng`. Only read when a mission declares one. */
@@ -378,8 +380,26 @@ export interface MissionRuntime {
     /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
     dispose(): void;
 }
+/** Which plane a marker proximity test compares in. */
+export type MissionMarkerPlane = "horizontal" | "spatial";
+/**
+ * How a positional objective compares an actor to its authored marker.
+ *
+ * Authored markers sit on a flat plan (`y = 0`) while the terrain around them rises, so a straight
+ * 3D test can leave a marker unreachable from the ground below it. `"horizontal"` compares the
+ * ground distance and allows the actor up to `tolerance` metres off the marker's height;
+ * `"spatial"` is the plain 3D check, for a world whose stacked platforms must stay distinct.
+ */
+export interface MissionMarkerProximity {
+    /** `"horizontal"` (default) or `"spatial"`. */
+    plane?: MissionMarkerPlane;
+    /** Horizontal plane only: how far (m) the actor may sit above or below the marker. Default {@link DEFAULT_MARKER_TOLERANCE}. */
+    tolerance?: number;
+}
 /** Default proximity radius (m) for a `reach` / `interact` objective. */
 export declare const DEFAULT_REACH_RADIUS = 2.5;
+/** Default vertical allowance (m) for a horizontal marker proximity test. */
+export declare const DEFAULT_MARKER_TOLERANCE = 8;
 /** Default keep-close distance (m) for a `pursue` objective. */
 export declare const DEFAULT_PURSUE_DISTANCE = 3;
 /** A pursuit escapes at this multiple of its keep-close distance when none is declared. */
@@ -404,6 +424,10 @@ export declare function applyMissionRewards(rewards: MissionRewards, appliers: M
  *
  * Cost per tick is bounded by the active objective's own fail list plus one goal test.
  *
+ * Marker proximity runs on the plane `markerProximity` picks: horizontal by default, so a marker
+ * authored on a flat `y = 0` plan still triggers from ground that rises under it; `spatial` for a
+ * world whose stacked platforms must stay apart.
+ *
  * @capability mission-runtime missions as a data-driven objective state machine with fail states, timers, branches and rewards
  */
 export declare function createMissionRuntime(config: MissionRuntimeConfig): MissionRuntime;

package/dist/mission/mission.js

@@ -23,6 +23,8 @@ export function isCounterObjective(kind) {
 }
 /** Default proximity radius (m) for a `reach` / `interact` objective. */
 export const DEFAULT_REACH_RADIUS = 2.5;
+/** Default vertical allowance (m) for a horizontal marker proximity test. */
+export const DEFAULT_MARKER_TOLERANCE = 8;
 /** Default keep-close distance (m) for a `pursue` objective. */
 export const DEFAULT_PURSUE_DISTANCE = 3;
 /** A pursuit escapes at this multiple of its keep-close distance when none is declared. */
@@ -30,6 +32,21 @@ export const DEFAULT_ESCAPE_MULTIPLE = 3;
 function distance(a, b) {
     return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
 }
+/** Whether `from` is inside the marker's reach radius under the configured plane — no allocation, no sqrt. */
+function markerWithin(from, to, radius, plane, tolerance) {
+    const dy = from.y - to.y;
+    const limit = radius * radius;
+    if (plane === "spatial") {
+        const dx = from.x - to.x;
+        const dz = from.z - to.z;
+        return dx * dx + dy * dy + dz * dz <= limit;
+    }
+    if (Math.abs(dy) > tolerance)
+        return false;
+    const dx = from.x - to.x;
+    const dz = from.z - to.z;
+    return dx * dx + dz * dz <= limit;
+}
 function cloneState(state) {
     return {
         ...state,
@@ -110,6 +127,10 @@ export function applyMissionRewards(rewards, appliers) {
  *
  * Cost per tick is bounded by the active objective's own fail list plus one goal test.
  *
+ * Marker proximity runs on the plane `markerProximity` picks: horizontal by default, so a marker
+ * authored on a flat `y = 0` plan still triggers from ground that rises under it; `spatial` for a
+ * world whose stacked platforms must stay apart.
+ *
  * @capability mission-runtime missions as a data-driven objective state machine with fail states, timers, branches and rewards
  */
 export function createMissionRuntime(config) {
@@ -117,6 +138,8 @@ export function createMissionRuntime(config) {
     for (const def of config.missions)
         defs.set(def.id, def);
     const markers = config.markers ?? {};
+    const markerPlane = config.markerProximity?.plane ?? "horizontal";
+    const markerTolerance = Math.max(0, config.markerProximity?.tolerance ?? DEFAULT_MARKER_TOLERANCE);
     let rng = config.rng;
     let state = null;
     let ticks = 0;
@@ -222,7 +245,7 @@ export function createMissionRuntime(config) {
                 const to = objective.marker === undefined ? undefined : markers[objective.marker];
                 if (from === undefined || to === undefined)
                     return false;
-                return distance(from, to) <= (objective.radius ?? DEFAULT_REACH_RADIUS);
+                return markerWithin(from, to, objective.radius ?? DEFAULT_REACH_RADIUS, markerPlane, markerTolerance);
             }
             case "interact": {
                 if (objective.actor === undefined || !(input.interact ?? []).includes(objective.actor))
@@ -231,7 +254,8 @@ export function createMissionRuntime(config) {
                 if (to === undefined)
                     return true;
                 const from = positionOf(objective.actor, input);
-                return from !== undefined && distance(from, to) <= (objective.radius ?? DEFAULT_REACH_RADIUS);
+                return from !== undefined
+                    && markerWithin(from, to, objective.radius ?? DEFAULT_REACH_RADIUS, markerPlane, markerTolerance);
             }
             case "survive":
                 return state.objectiveElapsed >= (objective.duration ?? 0);
@@ -306,7 +330,8 @@ export function createMissionRuntime(config) {
                 const actor = condition.actor ?? objective.actor;
                 const from = positionOf(actor, input);
                 const to = condition.marker === undefined ? undefined : markers[condition.marker];
-                if (from !== undefined && to !== undefined && distance(from, to) > (condition.radius ?? DEFAULT_REACH_RADIUS)) {
+                const radius = condition.radius ?? DEFAULT_REACH_RADIUS;
+                if (from !== undefined && to !== undefined && !markerWithin(from, to, radius, markerPlane, markerTolerance)) {
                     return { state: condition.to ?? "failed", reason: condition.message ?? `${actor ?? "actor"} left the area` };
                 }
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.31.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.31.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -728,7 +728,7 @@
 - `GameLoop` (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
 - `Hotbar` (function): function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon, style, className, }: { inventoryId: string; activeSlot?: number; keys?: readonly string[]; slotSize?: number; /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */ itemIcon?: … — A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
 - `HudCanvas` (function): function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: { layout: HudLayoutStore; editChord?: HudEditChord | false; /** Zoom applied to the whole HUD on compact displays. Default 0.85. */ compactScale?: number; /** Opt-in play-phase gate: render the HUD only … — Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine anchor regions and stack automatically with a gap — no per-panel pixel offsets, no manual clearance for sibling panels, the touch-control dock (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the whole surface scales down and each panel applies its `compact` behavior.
-- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** Stack … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
+- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", lane, order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
 - `PlayableGame` (type): type PlayableGame = EnginePlayableGame< ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps> > & { /** HUD theme the shell applies at the `GameUI` root. Unset uses `defaultHudTheme`; `false` opts out of the default theme and the en… — The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle.
 - `StatBar` (function): function StatBar({ statId = "health", entityId, tone = "health", label, showValue = true, width = 200, icon, style, className, }: { statId?: string; entityId?: string; tone?: StatTone; label?: string; showValue?: boolean; width?: number; icon?: ReactNode; style?: CSSProperties; className?: string; }… — A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player). Renders nothing until the stat exists.
 - `StoreHandle` (interface): interface StoreHandle<T> — A typed, cast-free handle onto one slot of the reactive game store (`ctx.game.store`). The single type parameter is fixed at definition; `read`/`write`/`update` never widen to `unknown`, so no call site repeats `store.get(key) as T`. Writes flow through the engine store, so they bump `ctx.version()`, serialize into a {@link WorldSnapshot}, and replay under host authority — the same guarantees a hand-rolled `store.get`/`store.set` pair gives up the moment it forks run state into a module-level singleton.

package/skills/jgengine-gameplay/SKILL.md

@@ -44,7 +44,16 @@ tiers, manufacturer stat personalities and a level curve, all caller data.
 `validateLootItem` names each defect, `compareLootItems` returns per-stat deltas
 and a weighted score, and `lootWeaponDefinition` (`loot/lootWeapon`) projects a
 rolled item onto a `WeaponDefinition` for `createWeaponSystem`. `createLootRoller`
-counts drops per rarity for a debug probe and snapshots its counters. Sample
+counts drops per rarity for a debug probe and snapshots its counters.
+
+Roll a campaign drop with `rollDrop` (`loot/drop`) and show `compareToEquipped`
+against worn gear; carry and bank it with `createRunHaul` (`loot/haul`), which
+weighs the hold through the encumbrance rules and drops the hold on `fail`. Break
+an item down once with `salvageItem` and `createItemLedger` (`loot/salvage`), and
+price a vendor shelf through the wallet with `stockVendor` (`loot/vendor`).
+Bases and affixes take `minLevel`; bases take `mass`, which a roll carries forward.
+
+Sample
 catalog, distribution check and generated-weapon proof are in
 [reference-systems.md](reference-systems.md#procedural-gear).