@jgengine/core 0.29.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.29.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,53 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.29.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`.",
+        ],
+        added: [
+            "`ColorblindFrame` (`@jgengine/react/accessibility`) wraps the 3D canvas and applies the player's colour-vision mode to that box alone, so HUD, menu and caption text keep their own contrast. `colorblindFrameFilter` (`@jgengine/core/ui/accessibility`) resolves a mode to the CSS filter, and `useColorblindMode` reads the mode from the settings store the settings rows write; the 3D shell does both for the mounted game.",
+            "`SettingsSection` (`@jgengine/react/settingsBlocks`) is one `useMenuNav` menu: a d-pad or left stick moves between rows and left/right steps the focused value — slider by its step, toggle flipped, select to the next option, confirm arms a keybind — through the same `onAdjust` path the arrow keys use. `onAdjust` (`@jgengine/react/menuNav`) is the option that makes left/right adjust instead of move.",
+            "`createStanding` (`@jgengine/core/progression/standing`) holds per-faction or per-district standing over authored tracks and moves it from named outcomes, so an outcome that resolves to nothing throws at the call instead of silently moving nothing.",
+            "`createGateSet` (`@jgengine/core/progression/gates`) evaluates authored milestones against standing and money, and refuses to load when a gate's unlock id resolves to nothing.",
+            "`createCareerBank` (`@jgengine/core/progression/careerBank`) keeps persistent career money apart from a run's haul, so a failed run loses the haul and keeps the bank.",
+            "`createUpgradeTree` (`@jgengine/core/progression/upgrades`) prices each rank from the shared curve primitive and gates purchases on prerequisites and standing.",
+        ],
+        changed: [
+            "`AccessibilityProvider` (`@jgengine/react/accessibility`) sets its data attributes and text-scale var without filtering its own subtree. A colour matrix over the HUD and menu root recoloured the text the rest of the UI assumes, so wrap the game canvas in `ColorblindFrame` instead; a custom root can still offset it with its own `ColorblindFilters` and `filter: url(#jg-cb-<mode>)`.",
+            "World health bars and nameplates derive their range from the render camera and the target height when a game sets no `maxDistance`: an overhead camera reaches the units it looks down at, and a bar is kept while the target it annotates still covers 18 px, instead of hiding every target past a fixed 60 units.",
+            "A configured `worldHealthBars.maxDistance` or `nameplates.maxDistance` that hides every target in view now warns once with the nearest measured distance and the prop to raise, instead of rendering nothing.",
+        ],
+        removed: [],
+    },
     "0.29.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.29.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.26.0`; `@jgengine/github` is `0.16.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/dist/progression/careerBank.d.ts

@@ -0,0 +1,63 @@
+import { type CurrencyDefinition } from "../economy/currency.js";
+/**
+ * Everything a career bank stores, as plain JSON. `banked` is the persistent balance; `haul` is
+ * the run in progress and is the part a failed run loses. `deposited`, `lost`, `bestHaul` and
+ * `runs` are lifetime counters a results screen reads.
+ */
+export interface CareerBankState {
+    banked: number;
+    haul: number;
+    deposited: number;
+    lost: number;
+    bestHaul: number;
+    runs: number;
+}
+/** Configuration for {@link createCareerBank}. */
+export interface CareerBankConfig {
+    currency: CurrencyDefinition;
+    /** Persistent money before any run (default `0`). */
+    start?: number;
+    /** Most a single run's haul can carry; omitted means no cap. */
+    haulCap?: number;
+    /** Rehydrate from a prior {@link CareerBank.snapshot}. */
+    state?: CareerBankState;
+}
+/** Persistent career money plus the run in progress, which a failed run loses. */
+export interface CareerBank {
+    currency(): CurrencyDefinition;
+    /** Money kept between runs. */
+    banked(): number;
+    /** Money earned this run and not yet banked or lost. */
+    haul(): number;
+    /** Add to the run's haul (capped by `haulCap`); negative or non-finite is ignored. Returns the haul. */
+    earn(amount: number): number;
+    /** Bank the haul: it becomes persistent and the run's haul resets. */
+    cashOut(): {
+        deposited: number;
+        banked: number;
+    };
+    /** The run failed: the haul is gone, persistent money is untouched. */
+    loseHaul(): {
+        lost: number;
+        banked: number;
+    };
+    /** Pay from persistent money; `false` when it cannot cover the amount. */
+    spend(amount: number): boolean;
+    afford(amount: number): boolean;
+    counters(): {
+        deposited: number;
+        lost: number;
+        bestHaul: number;
+        runs: number;
+    };
+    snapshot(): CareerBankState;
+    restore(next: CareerBankState): void;
+}
+/**
+ * Money that means something between runs: a persistent balance plus a run's haul that is banked on
+ * a cash-out and lost on a failure. Amounts are snapped to the currency's minor units, so a save
+ * round-trip and a display never drift. Pair it with `economy/upgrades` for a career upgrade tree.
+ *
+ * @capability career-bank persistent career money with a run haul that can be banked or lost
+ */
+export declare function createCareerBank(config: CareerBankConfig): CareerBank;