@jgengine/core 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# 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.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/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/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,

package/dist/game/unlocks.d.ts

@@ -2,6 +2,15 @@ export interface UnlockDef {
     id: string;
     category?: string;
 }
+export type UnlockState = readonly string[];
+export declare function hasUnlock(granted: UnlockState, unlockId: string): boolean;
+export declare function grantUnlock(granted: UnlockState, unlockId: string): string[];
+export declare function unlockTree(defs: readonly UnlockDef[], categoryId: string): UnlockDef[];
+export interface UnlockCatalog {
+    has(unlockId: string): boolean;
+    tree(categoryId: string): UnlockDef[];
+}
+export declare function createUnlockCatalog(defs?: readonly UnlockDef[]): UnlockCatalog;
 export interface Unlocks {
     has(userId: string, unlockId: string): boolean;
     grant(userId: string, unlockId: string): void;

package/dist/game/unlocks.js

@@ -1,3 +1,21 @@
+export function hasUnlock(granted, unlockId) {
+    return granted.includes(unlockId);
+}
+export function grantUnlock(granted, unlockId) {
+    return granted.includes(unlockId) ? granted.slice() : [...granted, unlockId];
+}
+export function unlockTree(defs, categoryId) {
+    return defs.filter((def) => def.category === categoryId);
+}
+export function createUnlockCatalog(defs = []) {
+    const byId = new Map();
+    for (const def of defs)
+        byId.set(def.id, def);
+    return {
+        has: (unlockId) => byId.has(unlockId),
+        tree: (categoryId) => unlockTree(defs, categoryId),
+    };
+}
 export function createUnlocks(defs = []) {
     const definitions = new Map();
     for (const def of defs)
@@ -22,7 +40,7 @@ export function createUnlocks(defs = []) {
             return Array.from(granted.get(userId) ?? []);
         },
         tree(categoryId) {
-            return Array.from(definitions.values()).filter((def) => def.category === categoryId);
+            return unlockTree(Array.from(definitions.values()), categoryId);
         },
         snapshot(userId) {
             return Array.from(granted.get(userId) ?? []);

package/dist/inventory/slotModel.d.ts

@@ -0,0 +1,19 @@
+export type Slot<T> = T | null;
+export type SlotGrid<T> = readonly Slot<T>[];
+export type SlotResult<T> = {
+    status: "ok";
+    grid: Slot<T>[];
+} | {
+    status: "rejected";
+    reason: "invalid-slot" | "slot-occupied" | "empty-slot";
+};
+export declare function createSlots<T>(size: number): Slot<T>[];
+export declare function normalizeSlots<T>(values: SlotGrid<T>, size: number): Slot<T>[];
+export declare function placeAt<T>(grid: SlotGrid<T>, index: number, value: T): SlotResult<T>;
+export declare function removeAt<T>(grid: SlotGrid<T>, index: number): SlotResult<T>;
+export declare function moveSlot<T>(grid: SlotGrid<T>, from: number, to: number): SlotResult<T>;
+export declare function firstEmpty<T>(grid: SlotGrid<T>): number | null;
+export declare function insertFirst<T>(grid: SlotGrid<T>, value: T): SlotResult<T>;
+export declare function compactSlots<T>(grid: SlotGrid<T>): Slot<T>[];
+export declare function countFilled<T>(grid: SlotGrid<T>): number;
+export declare function indexOfSlot<T>(grid: SlotGrid<T>, match: (value: T, index: number) => boolean): number | null;

package/dist/inventory/slotModel.js

@@ -0,0 +1,76 @@
+export function createSlots(size) {
+    return new Array(Math.max(0, size)).fill(null);
+}
+export function normalizeSlots(values, size) {
+    const grid = createSlots(size);
+    for (let index = 0; index < size; index++)
+        grid[index] = values[index] ?? null;
+    return grid;
+}
+function inRange(grid, index) {
+    return Number.isInteger(index) && index >= 0 && index < grid.length;
+}
+export function placeAt(grid, index, value) {
+    if (!inRange(grid, index))
+        return { status: "rejected", reason: "invalid-slot" };
+    if (grid[index] !== null)
+        return { status: "rejected", reason: "slot-occupied" };
+    const next = grid.slice();
+    next[index] = value;
+    return { status: "ok", grid: next };
+}
+export function removeAt(grid, index) {
+    if (!inRange(grid, index))
+        return { status: "rejected", reason: "invalid-slot" };
+    if (grid[index] === null)
+        return { status: "rejected", reason: "empty-slot" };
+    const next = grid.slice();
+    next[index] = null;
+    return { status: "ok", grid: next };
+}
+export function moveSlot(grid, from, to) {
+    if (!inRange(grid, from) || !inRange(grid, to))
+        return { status: "rejected", reason: "invalid-slot" };
+    if (grid[from] === null)
+        return { status: "rejected", reason: "empty-slot" };
+    const next = grid.slice();
+    const moved = next[from];
+    next[from] = next[to];
+    next[to] = moved;
+    return { status: "ok", grid: next };
+}
+export function firstEmpty(grid) {
+    for (let index = 0; index < grid.length; index++) {
+        if (grid[index] === null)
+            return index;
+    }
+    return null;
+}
+export function insertFirst(grid, value) {
+    const index = firstEmpty(grid);
+    if (index === null)
+        return { status: "rejected", reason: "slot-occupied" };
+    return placeAt(grid, index, value);
+}
+export function compactSlots(grid) {
+    const filled = grid.filter((slot) => slot !== null);
+    const next = createSlots(grid.length);
+    for (let index = 0; index < filled.length; index++)
+        next[index] = filled[index];
+    return next;
+}
+export function countFilled(grid) {
+    let count = 0;
+    for (const slot of grid)
+        if (slot !== null)
+            count += 1;
+    return count;
+}
+export function indexOfSlot(grid, match) {
+    for (let index = 0; index < grid.length; index++) {
+        const slot = grid[index];
+        if (slot !== null && match(slot, index))
+            return index;
+    }
+    return null;
+}

package/dist/meta/changelog.d.ts

@@ -0,0 +1,8 @@
+export declare const VERSION = "0.5.0";
+export interface ChangelogEntry {
+    migrate: readonly string[];
+    added: readonly string[];
+    changed: readonly string[];
+    removed: readonly string[];
+}
+export declare const CHANGELOG: Record<string, ChangelogEntry>;

package/dist/meta/changelog.js

@@ -0,0 +1,25 @@
+export const VERSION = "0.5.0";
+export const CHANGELOG = {
+    "0.5.0": {
+        migrate: [
+            "Bump every @jgengine/* dependency to ^0.5.0 (the eight packages version in lockstep).",
+            "0.5.0 is additive — all 0.4.0 APIs are unchanged, so no code change is required to upgrade.",
+            "Optional: replace a game's hand-rolled progression/curves.ts with leveling({ xpForLevel: { kind: 'power', base, exponent, round: 'floor' }, maxLevel }) from @jgengine/core/game/progression; its xpForLevel/resolve/grantXp are drop-ins and ctx.scene.entity.stats satisfies LevelingStatAccess with no adapter.",
+        ],
+        added: [
+            "@jgengine/core/game/progression — declarative scalar curves (curve/evalCurve: const, linear, power, geometric, steps, piecewise with round + min/max) and a leveling() XP->level track built on 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/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.",
+        ],
+        changed: [],
+        removed: [],
+    },
+    "0.4.0": {
+        migrate: [],
+        added: ["Baseline release: core, ws, sql, react, convex, node, shell, assets."],
+        changed: [],
+        removed: [],
+    },
+};

package/dist/world/geometry.d.ts

@@ -0,0 +1,23 @@
+export type Vec2 = readonly [number, number];
+export interface Footprint {
+    w: number;
+    d: number;
+}
+export interface Aabb {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+export interface MoveOptions {
+    bounds?: Aabb;
+    radius?: number;
+}
+export declare function snapToGrid(point: Vec2, size: number): Vec2;
+export declare function footprintAabb(center: Vec2, footprint: Footprint, quarterTurns?: number): Aabb;
+export declare function expandAabb(aabb: Aabb, margin: number): Aabb;
+export declare function aabbOverlap(a: Aabb, b: Aabb): boolean;
+export declare function aabbContains(outer: Aabb, inner: Aabb): boolean;
+export declare function pointInAabb(point: Vec2, aabb: Aabb): boolean;
+export declare function clampToAabb(point: Vec2, aabb: Aabb): Vec2;
+export declare function resolveMove(from: Vec2, delta: Vec2, blockers: readonly Aabb[], options?: MoveOptions): Vec2;

package/dist/world/geometry.js

@@ -0,0 +1,75 @@
+export function snapToGrid(point, size) {
+    if (!(size > 0))
+        return point;
+    return [Math.round(point[0] / size) * size, Math.round(point[1] / size) * size];
+}
+export function footprintAabb(center, footprint, quarterTurns = 0) {
+    const turned = ((quarterTurns % 2) + 2) % 2 === 1;
+    const halfW = (turned ? footprint.d : footprint.w) / 2;
+    const halfD = (turned ? footprint.w : footprint.d) / 2;
+    return {
+        minX: center[0] - halfW,
+        maxX: center[0] + halfW,
+        minZ: center[1] - halfD,
+        maxZ: center[1] + halfD,
+    };
+}
+export function expandAabb(aabb, margin) {
+    return {
+        minX: aabb.minX - margin,
+        maxX: aabb.maxX + margin,
+        minZ: aabb.minZ - margin,
+        maxZ: aabb.maxZ + margin,
+    };
+}
+export function aabbOverlap(a, b) {
+    return a.minX < b.maxX && a.maxX > b.minX && a.minZ < b.maxZ && a.maxZ > b.minZ;
+}
+export function aabbContains(outer, inner) {
+    return (inner.minX >= outer.minX &&
+        inner.maxX <= outer.maxX &&
+        inner.minZ >= outer.minZ &&
+        inner.maxZ <= outer.maxZ);
+}
+export function pointInAabb(point, aabb) {
+    return point[0] >= aabb.minX && point[0] <= aabb.maxX && point[1] >= aabb.minZ && point[1] <= aabb.maxZ;
+}
+export function clampToAabb(point, aabb) {
+    return [
+        Math.min(Math.max(point[0], aabb.minX), aabb.maxX),
+        Math.min(Math.max(point[1], aabb.minZ), aabb.maxZ),
+    ];
+}
+function resolveAxis(main, cross, delta, blockers, axisX) {
+    let next = main + delta;
+    if (delta === 0)
+        return next;
+    for (const blocker of blockers) {
+        const minMain = axisX ? blocker.minX : blocker.minZ;
+        const maxMain = axisX ? blocker.maxX : blocker.maxZ;
+        const minCross = axisX ? blocker.minZ : blocker.minX;
+        const maxCross = axisX ? blocker.maxZ : blocker.maxX;
+        if (cross <= minCross || cross >= maxCross)
+            continue;
+        if (delta > 0) {
+            if (main <= minMain && next > minMain)
+                next = minMain;
+        }
+        else {
+            if (main >= maxMain && next < maxMain)
+                next = maxMain;
+        }
+    }
+    return next;
+}
+export function resolveMove(from, delta, blockers, options = {}) {
+    const radius = options.radius ?? 0;
+    const expanded = radius === 0 ? blockers : blockers.map((blocker) => expandAabb(blocker, radius));
+    let x = resolveAxis(from[0], from[1], delta[0], expanded, true);
+    if (options.bounds)
+        x = Math.min(Math.max(x, options.bounds.minX + radius), options.bounds.maxX - radius);
+    let z = resolveAxis(from[1], x, delta[1], expanded, false);
+    if (options.bounds)
+        z = Math.min(Math.max(z, options.bounds.minZ + radius), options.bounds.maxZ - radius);
+    return [x, z];
+}

package/dist/world/interiors.d.ts

@@ -0,0 +1,35 @@
+import { type Aabb, type Vec2 } from "./geometry.js";
+export type SpaceRef = {
+    kind: "exterior";
+} | {
+    kind: "interior";
+    id: string;
+};
+export interface EntityLocation {
+    space: SpaceRef;
+    position: Vec2;
+}
+export interface Interior {
+    id: string;
+    origin: Vec2;
+    rotation?: number;
+    bounds: Aabb;
+    obstacles?: readonly Aabb[];
+}
+export interface Exterior {
+    bounds?: Aabb;
+    obstacles?: readonly Aabb[];
+}
+export interface InteriorsConfig {
+    exterior?: Exterior;
+    interiors?: readonly Interior[];
+    radius?: number;
+}
+export interface Interiors {
+    move(location: EntityLocation, delta: Vec2): EntityLocation;
+    enter(location: EntityLocation, id: string): EntityLocation | null;
+    leave(location: EntityLocation): EntityLocation | null;
+    toInterior(id: string, exterior: Vec2): Vec2 | null;
+    toExterior(id: string, interior: Vec2): Vec2 | null;
+}
+export declare function createInteriors(config?: InteriorsConfig): Interiors;

package/dist/world/interiors.js

@@ -0,0 +1,66 @@
+import { resolveMove } from "./geometry.js";
+function rotate(point, angle) {
+    if (angle === 0)
+        return point;
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    return [point[0] * cos - point[1] * sin, point[0] * sin + point[1] * cos];
+}
+function toInteriorFrame(interior, exterior) {
+    const local = [exterior[0] - interior.origin[0], exterior[1] - interior.origin[1]];
+    return rotate(local, -(interior.rotation ?? 0));
+}
+function toExteriorFrame(interior, local) {
+    const rotated = rotate(local, interior.rotation ?? 0);
+    return [rotated[0] + interior.origin[0], rotated[1] + interior.origin[1]];
+}
+export function createInteriors(config = {}) {
+    const radius = config.radius ?? 0;
+    const exterior = config.exterior ?? {};
+    const byId = new Map();
+    for (const interior of config.interiors ?? [])
+        byId.set(interior.id, interior);
+    return {
+        move(location, delta) {
+            if (location.space.kind === "exterior") {
+                const position = resolveMove(location.position, delta, exterior.obstacles ?? [], {
+                    bounds: exterior.bounds,
+                    radius,
+                });
+                return { space: { kind: "exterior" }, position };
+            }
+            const interior = byId.get(location.space.id);
+            if (interior === undefined)
+                return location;
+            const position = resolveMove(location.position, delta, interior.obstacles ?? [], {
+                bounds: interior.bounds,
+                radius,
+            });
+            return { space: { kind: "interior", id: interior.id }, position };
+        },
+        enter(location, id) {
+            if (location.space.kind !== "exterior")
+                return null;
+            const interior = byId.get(id);
+            if (interior === undefined)
+                return null;
+            return { space: { kind: "interior", id }, position: toInteriorFrame(interior, location.position) };
+        },
+        leave(location) {
+            if (location.space.kind !== "interior")
+                return null;
+            const interior = byId.get(location.space.id);
+            if (interior === undefined)
+                return null;
+            return { space: { kind: "exterior" }, position: toExteriorFrame(interior, location.position) };
+        },
+        toInterior(id, exterior) {
+            const interior = byId.get(id);
+            return interior === undefined ? null : toInteriorFrame(interior, exterior);
+        },
+        toExterior(id, interior) {
+            const frame = byId.get(id);
+            return frame === undefined ? null : toExteriorFrame(frame, interior);
+        },
+    };
+}

package/dist/world/placement.d.ts

@@ -0,0 +1,30 @@
+import { type Aabb, type Footprint, type Vec2 } from "./geometry.js";
+export interface PlacementObstacle {
+    aabb: Aabb;
+    id?: string;
+}
+export interface PlacementRequest {
+    center: Vec2;
+    footprint: Footprint;
+    quarterTurns?: number;
+}
+export interface PlacementRules {
+    bounds?: Aabb;
+    obstacles?: readonly PlacementObstacle[];
+    snap?: number;
+}
+export type PlacementResult = {
+    status: "ok";
+    center: Vec2;
+    aabb: Aabb;
+} | {
+    status: "rejected";
+    reason: "out-of-bounds";
+} | {
+    status: "rejected";
+    reason: "overlap";
+    obstacle: PlacementObstacle;
+    index: number;
+};
+export declare function validatePlacement(request: PlacementRequest, rules?: PlacementRules): PlacementResult;
+export declare function footprintObstacle(request: PlacementRequest, id?: string): PlacementObstacle;

package/dist/world/placement.js

@@ -0,0 +1,20 @@
+import { aabbContains, aabbOverlap, footprintAabb, snapToGrid, } from "./geometry.js";
+export function validatePlacement(request, rules = {}) {
+    const center = rules.snap === undefined ? request.center : snapToGrid(request.center, rules.snap);
+    const aabb = footprintAabb(center, request.footprint, request.quarterTurns ?? 0);
+    if (rules.bounds !== undefined && !aabbContains(rules.bounds, aabb)) {
+        return { status: "rejected", reason: "out-of-bounds" };
+    }
+    const obstacles = rules.obstacles ?? [];
+    for (let index = 0; index < obstacles.length; index++) {
+        const obstacle = obstacles[index];
+        if (aabbOverlap(aabb, obstacle.aabb)) {
+            return { status: "rejected", reason: "overlap", obstacle, index };
+        }
+    }
+    return { status: "ok", center, aabb };
+}
+export function footprintObstacle(request, id) {
+    const aabb = footprintAabb(request.center, request.footprint, request.quarterTurns ?? 0);
+    return id === undefined ? { aabb } : { aabb, id };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Genre-agnostic TypeScript game engine SDK: game runtime, state store, entity scene, combat, movement, inventory, economy, quests, multiplayer primitives.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -10,7 +10,10 @@
     "url": "git+https://github.com/Noisemaker111/jgengine.git",
     "directory": "packages/core"
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",