@jgengine/core 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All eight `@jgengine/*` packages are versioned in lockstep, so this one file
+covers every release. Format follows [Keep a Changelog](https://keepachangelog.com);
+each release **leads with a Migrate block** — the concrete steps to move a game
+from the previous version onto the new APIs — because the point of a bump is to
+let consumers pick up the better stuff, not just to list what moved.
+
+Agents building on the published SDK can also read this programmatically:
+`import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` gives the
+same data as typed values, so an updater can diff its installed version against
+the latest and surface the migration steps.
+
+## Unreleased
+
+_Nothing yet._
+
+## 0.6.0
+
+An additive release: **every 0.5.0 API is unchanged**, so upgrading is only a
+version bump. The headline is a whole outdoor-world layer — composable
+`environment(...)` descriptors, renderer-free query primitives so gameplay reads
+the same world the shell renders, a standalone rigid-body physics sim, and the
+`@jgengine/shell` renderers that draw it all.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.6.0` (the eight packages version in lockstep).
+- No code change is required — 0.6.0 adds surface, it doesn't move or remove any.
+- Optional: describe an outdoor scene once with `environment({ terrain, weather, vegetation, water, structures })` from `@jgengine/core/world/features`. `@jgengine/shell`'s `EnvironmentScene` renders it (terrain, rain/snow, grass, ocean, buildings), and gameplay reads the same world through the renderer-free primitives — `resolveTerrainField(...)` for ground-snap/collision, `windField(...)` for sway/sailing, `waterSurface(...)` for buoyancy, `scatter(...)` for prop/spawn placement, `buildingIndex(...)` for placement avoidance — no three.js needed.
+
+### Added
+
+- `@jgengine/core/world` query primitives — pure, renderer-free world sampling so gameplay and rendering read one source of truth. `world/terrain` (`TerrainField`, `noiseField`, `resolveTerrainField`, `resolveGroundStep` for slope-limited movement), `world/wind` (`windField` — one wind source for weather sway, grass, sailing, fire spread), `world/water` (`waterSurface` / `waterSurfaceFromDescriptor` — CPU Gerstner matching the ocean shader, for buoyancy and shorelines), `world/scatter` (`scatter` — seeded, overlap-aware point distribution for vegetation/props/spawns), `world/buildings` (`generateBuilding`, `generateBuildingDistrict`) and `world/buildingIndex` (`buildingIndex` — `at`/`within`/`nearest`/`isInside`/`blockers` over a district).
+- `@jgengine/core/world/features` composable outdoor descriptors — `environment(...)` plus `terrain()`, `rain()`, `snow()`, `grass()`, `ocean()`, `building()`.
+- `@jgengine/core/world/regions` (`createRegionField` — blend content-agnostic biomes by nearest selector, adding `tint`/`water`/`fog`/`speedMultiplier`/opaque `data`; extends `TerrainField` so it ground-snaps too) and `@jgengine/core/world/scatterItems` (`scatterItems` — region-driven content scatter: density per region, grounded, above-water/slope-aware, with `pickWeighted` for weighted rolls).
+- `@jgengine/core/physics/physicsWorld` — standalone fixed-capacity rigid-body sim (SoA buffers, spatial-hash broadphase, sleeping) for many colliding dynamic bodies (piles, debris, stress scenes). Distinct from the `defineGame` `physics: { gravity }` character-controller config.
+- `ctx.time` simulation clock (`@jgengine/core/time/simClock`) — `onTick`'s `dt` is now **game time**, so `rate * dt` decay/regen/AI obeys pause and fast-forward for free without per-system wiring. Configure with `defineGame({ time: { scale?, speeds?, dayLength?, start?, startPaused? } })` (all optional; default is real-time 1:1). `ctx.time` exposes `pause`/`play`/`toggle`/`setSpeed`/`cycleSpeed` + `snapshot()`/`calendar()`; `useGameClock()` binds it in React.
+- `@jgengine/shell` environment/terrain/water/weather/structures renderers — `EnvironmentScene` mounts an `environment()` descriptor as R3F renderers; `GrassField`, `ProceduralGround`, `Ocean`, `RainField`, `SnowField`, `LightningStrike`, `GeneratedBuilding`, and `world/InstancedBodies` (renders `PhysicsWorld` bodies).
+- `@jgengine/react/liveBind` — `useFrameBind` drives a DOM/SVG element from a per-frame value without re-rendering React (HUDs bound to live engine state never re-render or lag).
+
+## 0.5.0
+
+An additive release: **every 0.4.0 API is unchanged**, so upgrading is only a
+version bump. New pure primitives across progression, inventory slots, world
+geometry, and React store bindings.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.5.0` (the eight packages version in lockstep).
+- No code change is required — 0.5.0 adds surface, it doesn't move or remove any.
+- Optional: replace a game's hand-rolled `progression/curves.ts` with the new `leveling(...)` track. `leveling({ xpForLevel: { kind: "power", base, exponent, round: "floor" }, maxLevel })` returns `xpForLevel`, `resolve`, and `grantXp(ctx.scene.entity.stats, userId, amount, onLevelUp?)` — a drop-in for the old `xpRequiredForLevel` / `resolveLevelProgress` / `grantXp` exports. `ctx.scene.entity.stats` satisfies the primitive's `LevelingStatAccess` structurally, so no adapter is needed.
+
+### Added
+
+- `@jgengine/core/game/progression` — genre-agnostic progression primitive. `curve(spec)` / `evalCurve(spec, x)` evaluate declarative scalar curves (`const`, `linear`, `power`, `geometric`, `steps`, `piecewise`, each with optional `round`/`min`/`max`) for speed-by-level, difficulty-by-wave, loot drop-rate ramps, and similar scaling. `leveling(config)` builds the stateful XP→level track (threshold accumulation, multi-level grants, cap handling, `stat.levelUp` emit) on top of an `xpForLevel` curve.
+- `@jgengine/core/inventory/slotModel` — pure slot-grid primitives (`createSlots`, `placeAt`, `removeAt`, `moveSlot`).
+- `@jgengine/core/world/geometry`, `/world/interiors`, `/world/placement` — pure world primitives: grid snapping, footprint AABBs and overlap, interior/exterior spaces, and placement validation.
+- `@jgengine/react/engineStore` — raw-store React bindings (`useEngineState`, `useEngineStore`, `useEngineEvent`).
+- Pure/functional tiers for the `trade`, `unlocks`, `quest`, and `feed` verbs in `@jgengine/core/game`.
+
+## 0.4.0
+
+Baseline release: the eight `@jgengine/*` packages (core, ws, sql, react,
+convex, node, shell, assets) as the first tracked version. No migration —
+this is the floor changelog entries are measured against.

package/dist/game/defineGame.d.ts

@@ -3,6 +3,7 @@ import type { ItemTraits } from "../inventory/inventoryModel.js";
 import type { SaveConfig } from "../runtime/save.js";
 import type { AssetCatalog, ModelAssetRef } from "../scene/assetCatalog.js";
 import { type EntityStore } from "../scene/entityStore.js";
+import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
 export interface PhysicsConfig {
     gravity?: number;
@@ -30,6 +31,8 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     scene: EntityStore;
     world?: WorldFeature;
     physics?: PhysicsConfig;
+    /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */
+    time?: TimeConfig;
     inventories?: Record<string, InventoryDeclaration>;
     input?: ActionCodesMap;
     server?: GameServerConfig;

package/dist/game/feed.d.ts

@@ -6,6 +6,8 @@ export interface FeedEntry<T = unknown> {
 export interface GameFeedOptions {
     limit?: number;
 }
+export declare function appendFeedEntry<T>(buffer: readonly FeedEntry<T>[], entry: FeedEntry<T>, limit: number): FeedEntry<T>[];
+export declare function recentFeedEntries<T>(buffer: readonly FeedEntry<T>[], limit?: number): FeedEntry<T>[];
 export interface GameFeed {
     bind<TName extends keyof GameEventMap>(action: TName, events: GameEvents): () => void;
     push(action: string, entry: unknown): void;

package/dist/game/feed.js

@@ -1,13 +1,17 @@
+export function appendFeedEntry(buffer, entry, limit) {
+    const next = [...buffer, entry];
+    return next.length > limit ? next.slice(next.length - limit) : next;
+}
+export function recentFeedEntries(buffer, limit) {
+    const count = limit ?? buffer.length;
+    return buffer.slice(Math.max(0, buffer.length - count));
+}
 export function createGameFeed(options) {
     const limit = options?.limit ?? 20;
     const buffers = new Map();
     const listeners = new Map();
     function append(action, entry) {
-        const buffer = buffers.get(action) ?? [];
-        buffer.push(entry);
-        if (buffer.length > limit)
-            buffer.splice(0, buffer.length - limit);
-        buffers.set(action, buffer);
+        buffers.set(action, appendFeedEntry(buffers.get(action) ?? [], entry, limit));
         for (const listener of listeners.get(action) ?? [])
             listener(entry);
     }
@@ -19,9 +23,7 @@ export function createGameFeed(options) {
             append(action, { at: Date.now(), data });
         },
         recent(action, opts) {
-            const buffer = buffers.get(action) ?? [];
-            const count = opts?.limit ?? buffer.length;
-            return buffer.slice(Math.max(0, buffer.length - count));
+            return recentFeedEntries(buffers.get(action) ?? [], opts?.limit);
         },
         subscribe(action, listener) {
             let set = listeners.get(action);

package/dist/game/playableGame.d.ts

@@ -1,5 +1,6 @@
 import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
 import type { GameContext, GameContextContent } from "../runtime/gameContext.js";
+import type { ModelDims } from "../scene/assetCatalog.js";
 import type { GameDefinition, GameLoop } from "./defineGame.js";
 export interface CameraFollowState {
     entityId: string;
@@ -71,14 +72,22 @@ export interface ModelConfig {
     url: string;
     scale?: number;
     y?: number;
+    /** How the model registers on its placement point. `"center"` (default) horizontally centers the measured footprint on the point and ground-snaps its lowest vertex to the point's Y — the correct behavior for corner-pivot modular kits. `"origin"` renders at the raw GLB origin (legacy). */
+    anchor?: "center" | "origin";
+    /** Measured footprint/center/minY; supplied automatically when the model resolves through an `@jgengine/assets` catalog. Required for `anchor: "center"` to take effect. */
+    dims?: ModelDims;
 }
-export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown> {
+export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never> {
     game: GameDefinition;
     content: GameContextContent;
     loop: Required<GameLoop<GameContext>>;
     GameUI: TUi;
     /** Optional canvas-layer VFX component (e.g. traveling projectiles). */
     WorldOverlay?: TWorldOverlay;
+    /** Replaces the default demo backdrop (ground + grid + rocks) with the game's own scene — ground, sky, structures. Camera, input, HUD, entity rendering, and the loop stay shell-provided; supply your world without forking the shell. */
+    environment?: TWorldOverlay;
+    /** Per-entity visual override: return your own mesh for an entity and the shell still positions it and drives selection/targeting. Return null/undefined to fall back to model → sprite → primitive. */
+    renderEntity?: TRenderEntity;
     /** Billboard sprites keyed by entity kind name; unmatched entities get primitive markers. */
     entitySprites?: Record<string, EntitySpriteConfig>;
     /** GLB models keyed by entity kind name; a string resolves as an asset-catalog key via game.assets, a ModelConfig renders directly. Takes priority over sprites, then primitives. */

package/dist/game/progression.d.ts

@@ -0,0 +1,61 @@
+export type CurveDef = {
+    kind: "const";
+    value: number;
+} | {
+    kind: "linear";
+    base: number;
+    per: number;
+} | {
+    kind: "power";
+    base: number;
+    exponent: number;
+} | {
+    kind: "geometric";
+    base: number;
+    ratio: number;
+} | {
+    kind: "steps";
+    values: number[];
+} | {
+    kind: "piecewise";
+    points: [number, number][];
+};
+export interface CurveShape {
+    round?: "floor" | "ceil" | "round";
+    min?: number;
+    max?: number;
+}
+export type Curve = CurveDef & CurveShape;
+export declare function evalCurve(spec: Curve, x: number): number;
+export declare function curve(spec: Curve): (x: number) => number;
+export interface LevelProgress {
+    level: number;
+    xp: number;
+    xpMax: number;
+    levelsGained: number;
+}
+export interface LevelingConfig {
+    xpForLevel: Curve;
+    maxLevel: number;
+    startLevel?: number;
+    xpStat?: string;
+    levelStat?: string;
+}
+export interface LevelingStatAccess {
+    get(userId: string, statId: string): {
+        current: number;
+        max: number;
+    } | null;
+    set(userId: string, statId: string, patch: {
+        current?: number;
+        max?: number;
+    }): unknown;
+}
+export interface LevelingTrack {
+    readonly maxLevel: number;
+    readonly startLevel: number;
+    xpForLevel(level: number): number;
+    resolve(level: number, xp: number): LevelProgress;
+    grantXp(access: LevelingStatAccess, userId: string, amount: number, onLevelUp?: (level: number) => void): number;
+}
+export declare function leveling(config: LevelingConfig): LevelingTrack;

package/dist/game/progression.js

@@ -0,0 +1,96 @@
+function rawCurve(def, x) {
+    switch (def.kind) {
+        case "const":
+            return def.value;
+        case "linear":
+            return def.base + def.per * x;
+        case "power":
+            return def.base * x ** def.exponent;
+        case "geometric":
+            return def.base * def.ratio ** x;
+        case "steps": {
+            const i = Math.max(0, Math.min(def.values.length - 1, Math.floor(x)));
+            return def.values[i];
+        }
+        case "piecewise":
+            return interpolate(def.points, x);
+    }
+}
+function interpolate(points, x) {
+    if (points.length === 0)
+        return 0;
+    if (x <= points[0][0])
+        return points[0][1];
+    const last = points[points.length - 1];
+    if (x >= last[0])
+        return last[1];
+    for (let i = 1; i < points.length; i += 1) {
+        const [x1, y1] = points[i];
+        if (x <= x1) {
+            const [x0, y0] = points[i - 1];
+            const span = x1 - x0;
+            const t = span === 0 ? 0 : (x - x0) / span;
+            return y0 + t * (y1 - y0);
+        }
+    }
+    return last[1];
+}
+export function evalCurve(spec, x) {
+    let y = rawCurve(spec, x);
+    if (spec.min !== undefined)
+        y = Math.max(spec.min, y);
+    if (spec.max !== undefined)
+        y = Math.min(spec.max, y);
+    switch (spec.round) {
+        case "floor":
+            return Math.floor(y);
+        case "ceil":
+            return Math.ceil(y);
+        case "round":
+            return Math.round(y);
+        default:
+            return y;
+    }
+}
+export function curve(spec) {
+    return (x) => evalCurve(spec, x);
+}
+export function leveling(config) {
+    const maxLevel = config.maxLevel;
+    const startLevel = config.startLevel ?? 1;
+    const xpStat = config.xpStat ?? "xp";
+    const levelStat = config.levelStat ?? "level";
+    const xpForLevel = (level) => evalCurve(config.xpForLevel, level);
+    const resolve = (level, xp) => {
+        let currentLevel = level;
+        let currentXp = xp;
+        let levelsGained = 0;
+        while (currentLevel < maxLevel && currentXp >= xpForLevel(currentLevel)) {
+            currentXp -= xpForLevel(currentLevel);
+            currentLevel += 1;
+            levelsGained += 1;
+        }
+        if (currentLevel >= maxLevel)
+            currentXp = 0;
+        return {
+            level: currentLevel,
+            xp: currentXp,
+            xpMax: xpForLevel(Math.min(currentLevel, maxLevel)),
+            levelsGained,
+        };
+    };
+    const grantXp = (access, userId, amount, onLevelUp) => {
+        const xp = access.get(userId, xpStat);
+        const level = access.get(userId, levelStat);
+        if (xp === null || level === null)
+            return 0;
+        const progress = resolve(level.current, xp.current + amount);
+        access.set(userId, xpStat, { current: progress.xp, max: progress.xpMax });
+        if (progress.levelsGained > 0) {
+            access.set(userId, levelStat, { current: progress.level });
+            onLevelUp?.(progress.level);
+        }
+        return progress.levelsGained;
+    };
+    return { maxLevel, startLevel, xpForLevel, resolve, grantXp };
+}

package/dist/game/quest.d.ts

@@ -91,3 +91,42 @@ export interface QuestJournal {
     hydrate(userId: string, data: QuestSnapshotEntry[]): void;
 }
 export declare function createQuestJournal(deps: QuestJournalDeps): QuestJournal;
+export interface QuestAcceptOptions {
+    hasUnlock?(id: string): boolean;
+}
+export interface QuestTurnIn {
+    state: QuestSnapshotEntry[];
+    rewards: QuestRewards | null;
+}
+export interface QuestEvaluator {
+    has(questId: string): boolean;
+    get(questId: string): QuestDef | null;
+    canAccept(state: readonly QuestSnapshotEntry[], questId: string, options?: QuestAcceptOptions): {
+        reason: string;
+    } | null;
+    accept(state: readonly QuestSnapshotEntry[], questId: string, options?: QuestAcceptOptions): QuestSnapshotEntry[] | {
+        reason: string;
+    };
+    abandon(state: readonly QuestSnapshotEntry[], questId: string): QuestSnapshotEntry[];
+    progress(state: readonly QuestSnapshotEntry[], questId: string, objectiveId: string, delta: number): QuestSnapshotEntry[];
+    canTurnIn(state: readonly QuestSnapshotEntry[], questId: string): {
+        reason: string;
+    } | null;
+    turnIn(state: readonly QuestSnapshotEntry[], questId: string): QuestTurnIn | {
+        reason: string;
+    };
+    grant(state: readonly QuestSnapshotEntry[], questId: string, options?: {
+        completed?: boolean;
+    }): QuestSnapshotEntry[];
+    revoke(state: readonly QuestSnapshotEntry[], questId: string): QuestSnapshotEntry[];
+    creditKill(state: readonly QuestSnapshotEntry[], targetCatalogId: string): QuestSnapshotEntry[];
+    creditCollect(state: readonly QuestSnapshotEntry[], itemId: string, count: number): QuestSnapshotEntry[];
+    list(state: readonly QuestSnapshotEntry[]): QuestInstance[];
+}
+export declare function applyQuestRewards(rewards: QuestRewards, appliers: {
+    grantXp?(amount: number): void;
+    grantEconomy?(currencyId: string, amount: number): void;
+    grantItem?(inventoryId: string, itemId: string, count: number): void;
+    grantUnlock?(unlockId: string): void;
+}): void;
+export declare function createQuestEvaluator(defs: QuestDef[] | Record<string, QuestDef>): QuestEvaluator;

package/dist/game/quest.js

@@ -226,3 +226,198 @@ export function createQuestJournal(deps) {
         },
     };
 }
+export function applyQuestRewards(rewards, appliers) {
+    if (rewards.xp)
+        appliers.grantXp?.(rewards.xp.amount);
+    for (const [currencyId, amount] of Object.entries(rewards.economy ?? {})) {
+        appliers.grantEconomy?.(currencyId, amount);
+    }
+    for (const entry of rewards.items ?? []) {
+        appliers.grantItem?.(entry.inventory, entry.item, entry.count);
+    }
+    for (const unlockId of rewards.unlocks ?? []) {
+        appliers.grantUnlock?.(unlockId);
+    }
+}
+function toWorking(state) {
+    const working = new Map();
+    for (const entry of state) {
+        working.set(entry.questId, {
+            status: entry.status,
+            progress: new Map(Object.entries(entry.progress)),
+        });
+    }
+    return working;
+}
+function toSnapshot(working) {
+    return Array.from(working, ([questId, state]) => ({
+        questId,
+        status: state.status,
+        progress: Object.fromEntries(state.progress),
+    }));
+}
+export function createQuestEvaluator(defs) {
+    const catalog = new Map();
+    for (const def of Array.isArray(defs) ? defs : Object.values(defs))
+        catalog.set(def.id, def);
+    function canAcceptWorking(working, questId, options) {
+        const def = catalog.get(questId);
+        if (def === undefined)
+            return { reason: `unknown quest "${questId}"` };
+        const state = working.get(questId);
+        if (state?.status === "active")
+            return { reason: `quest "${questId}" already active` };
+        if (state?.status === "completed")
+            return { reason: `quest "${questId}" already completed` };
+        for (const requirementId of def.requires ?? []) {
+            const met = working.get(requirementId)?.status === "completed" ||
+                (options?.hasUnlock?.(requirementId) ?? false);
+            if (!met)
+                return { reason: `quest "${questId}" requires "${requirementId}"` };
+        }
+        return null;
+    }
+    function progressWorking(working, questId, objectiveId, delta) {
+        const def = catalog.get(questId);
+        const state = working.get(questId);
+        if (def === undefined || state === undefined || state.status !== "active")
+            return;
+        const objective = def.objectives.find((candidate) => candidate.id === objectiveId);
+        if (objective === undefined)
+            return;
+        const previous = state.progress.get(objectiveId) ?? 0;
+        const next = clamp(previous + delta, 0, objective.count);
+        if (next !== previous)
+            state.progress.set(objectiveId, next);
+    }
+    function creditWorking(working, predicate, delta) {
+        for (const [questId, state] of working) {
+            if (state.status !== "active")
+                continue;
+            const def = catalog.get(questId);
+            if (def === undefined)
+                continue;
+            for (const objective of def.objectives) {
+                if (predicate(objective))
+                    progressWorking(working, questId, objective.id, delta);
+            }
+        }
+    }
+    function canTurnInWorking(working, questId) {
+        const def = catalog.get(questId);
+        if (def === undefined)
+            return { reason: `unknown quest "${questId}"` };
+        const state = working.get(questId);
+        if (state === undefined || state.status !== "active") {
+            return { reason: `quest "${questId}" is not active` };
+        }
+        for (const objective of def.objectives) {
+            if ((state.progress.get(objective.id) ?? 0) < objective.count) {
+                return { reason: `objective "${objective.id}" incomplete` };
+            }
+        }
+        return null;
+    }
+    return {
+        has(questId) {
+            return catalog.has(questId);
+        },
+        get(questId) {
+            return catalog.get(questId) ?? null;
+        },
+        canAccept(state, questId, options) {
+            return canAcceptWorking(toWorking(state), questId, options);
+        },
+        accept(state, questId, options) {
+            const working = toWorking(state);
+            const denied = canAcceptWorking(working, questId, options);
+            if (denied !== null)
+                return denied;
+            working.set(questId, { status: "active", progress: new Map() });
+            return toSnapshot(working);
+        },
+        abandon(state, questId) {
+            const working = toWorking(state);
+            if (working.get(questId)?.status === "active")
+                working.delete(questId);
+            return toSnapshot(working);
+        },
+        progress(state, questId, objectiveId, delta) {
+            const working = toWorking(state);
+            progressWorking(working, questId, objectiveId, delta);
+            return toSnapshot(working);
+        },
+        canTurnIn(state, questId) {
+            return canTurnInWorking(toWorking(state), questId);
+        },
+        turnIn(state, questId) {
+            const working = toWorking(state);
+            const denied = canTurnInWorking(working, questId);
+            if (denied !== null)
+                return denied;
+            const def = catalog.get(questId);
+            working.get(questId).status = "completed";
+            for (const nextQuestId of def.rewards?.quests ?? []) {
+                if (canAcceptWorking(working, nextQuestId) === null) {
+                    working.set(nextQuestId, { status: "active", progress: new Map() });
+                }
+            }
+            return { state: toSnapshot(working), rewards: def.rewards ?? null };
+        },
+        grant(state, questId, options) {
+            const def = catalog.get(questId);
+            if (def === undefined)
+                return state.slice();
+            const working = toWorking(state);
+            const completed = options?.completed ?? false;
+            const progressMap = new Map();
+            if (completed) {
+                for (const objective of def.objectives)
+                    progressMap.set(objective.id, objective.count);
+            }
+            working.set(questId, {
+                status: completed ? "completed" : "active",
+                progress: progressMap,
+            });
+            return toSnapshot(working);
+        },
+        revoke(state, questId) {
+            const working = toWorking(state);
+            working.delete(questId);
+            return toSnapshot(working);
+        },
+        creditKill(state, targetCatalogId) {
+            const working = toWorking(state);
+            creditWorking(working, (objective) => objective.kind === "kill" && objective.target === targetCatalogId, 1);
+            return toSnapshot(working);
+        },
+        creditCollect(state, itemId, count) {
+            const working = toWorking(state);
+            creditWorking(working, (objective) => objective.kind === "collect" && objective.item === itemId, count);
+            return toSnapshot(working);
+        },
+        list(state) {
+            const instances = [];
+            for (const entry of state) {
+                const def = catalog.get(entry.questId);
+                if (def === undefined)
+                    continue;
+                instances.push({
+                    questId: entry.questId,
+                    status: entry.status,
+                    objectives: def.objectives.map((objective) => {
+                        const current = entry.progress[objective.id] ?? 0;
+                        return {
+                            id: objective.id,
+                            kind: objective.kind,
+                            count: objective.count,
+                            progress: current,
+                            complete: current >= objective.count,
+                        };
+                    }),
+                });
+            }
+            return instances;
+        },
+    };
+}

package/dist/game/trade.d.ts

@@ -32,4 +32,27 @@ export interface TradeSystem {
     sell(itemId: string, count: number | undefined, party: TradeParty): TradeRejection | null;
     tradableAt(shopId: string, allItemIds: string[]): string[];
 }
+export declare function canAffordCosts(balances: Record<string, number>, costs: Record<string, number>): string | null;
+export interface TradeOutcome {
+    itemId: string;
+    count: number;
+    currency: Record<string, number>;
+}
+export type TradeResolution = {
+    status: "ok";
+    outcome: TradeOutcome;
+} | {
+    status: "rejected";
+    reason: string;
+};
+export declare function resolveBuy(itemId: string, trade: TradeField | null | undefined, shopId: string, count: number, balances: Record<string, number>): TradeResolution;
+export declare function resolveSell(itemId: string, trade: TradeField | null | undefined, count: number): TradeResolution;
+export declare function applyTradeOutcome(outcome: TradeOutcome, appliers: {
+    adjustItem(itemId: string, count: number): {
+        reason: string;
+    } | null;
+    adjustCurrency(delta: Record<string, number>): void;
+}): {
+    reason: string;
+} | null;
 export declare function createTradeSystem(deps: TradeSystemDeps): TradeSystem;

package/dist/game/trade.js

@@ -4,21 +4,63 @@ function scale(amounts, count) {
         scaled[currency] = amount * count;
     return scaled;
 }
+function negate(amounts) {
+    const out = {};
+    for (const [currency, amount] of Object.entries(amounts))
+        out[currency] = -amount;
+    return out;
+}
+export function canAffordCosts(balances, costs) {
+    for (const [currency, amount] of Object.entries(costs)) {
+        if ((balances[currency] ?? 0) < amount)
+            return "insufficient-funds";
+    }
+    return null;
+}
+function buyEligibility(trade, shopId) {
+    if (!trade?.buy)
+        return "not-purchasable";
+    if (!trade.shops?.includes(shopId))
+        return "not-stocked";
+    return null;
+}
+function sellEligibility(trade) {
+    return trade?.sell ? null : "not-sellable";
+}
+export function resolveBuy(itemId, trade, shopId, count, balances) {
+    const ineligible = buyEligibility(trade, shopId);
+    if (ineligible)
+        return { status: "rejected", reason: ineligible };
+    const costs = scale(trade.buy, count);
+    const unaffordable = canAffordCosts(balances, costs);
+    if (unaffordable)
+        return { status: "rejected", reason: unaffordable };
+    return { status: "ok", outcome: { itemId, count, currency: negate(costs) } };
+}
+export function resolveSell(itemId, trade, count) {
+    const ineligible = sellEligibility(trade);
+    if (ineligible)
+        return { status: "rejected", reason: ineligible };
+    return { status: "ok", outcome: { itemId, count: -count, currency: scale(trade.sell, count) } };
+}
+export function applyTradeOutcome(outcome, appliers) {
+    const itemResult = appliers.adjustItem(outcome.itemId, outcome.count);
+    if (itemResult)
+        return itemResult;
+    appliers.adjustCurrency(outcome.currency);
+    return null;
+}
 export function createTradeSystem(deps) {
     const { resolveTrade, wallet, inventory } = deps;
     function canBuy(itemId, shopId, count = 1) {
         const trade = resolveTrade(itemId);
-        if (!trade?.buy)
-            return "not-purchasable";
-        if (!trade.shops?.includes(shopId))
-            return "not-stocked";
+        const ineligible = buyEligibility(trade, shopId);
+        if (ineligible)
+            return ineligible;
         return wallet.canAfford(scale(trade.buy, count));
     }
     function canSell(itemId, _count = 1) {
-        const trade = resolveTrade(itemId);
-        if (!trade?.sell)
-            return "not-sellable";
-        return null;
+        return sellEligibility(resolveTrade(itemId));
     }
     return {
         canBuy,