@jgengine/core 0.4.0 → 0.6.0

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.6.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,43 @@
+export const VERSION = "0.6.0";
+export const CHANGELOG = {
+    "0.6.0": {
+        migrate: [
+            "Bump every @jgengine/* dependency to ^0.6.0 (the eight packages version in lockstep).",
+            "0.6.0 is additive — every 0.5.0 API is unchanged, so no code change is required to upgrade.",
+            "Optional: mount an outdoor scene by handing environment({ terrain, weather, vegetation, water, structures }) from @jgengine/core/world/features to the shell — @jgengine/shell EnvironmentScene renders terrain, rain/snow, grass, ocean, and buildings from it, while gameplay reads the same world through the renderer-free query primitives (resolveTerrainField, windField, waterSurface, scatter, buildingIndex).",
+        ],
+        added: [
+            "@jgengine/core/world query primitives — renderer-free world sampling so gameplay reads the same world the shell renders: world/terrain (TerrainField, noiseField, resolveTerrainField, resolveGroundStep), world/wind (windField), world/water (waterSurface, waterSurfaceFromDescriptor, CPU Gerstner), world/scatter (scatter — seeded overlap-aware point distribution), world/buildings (generateBuilding, generateBuildingDistrict) and world/buildingIndex (buildingIndex — at/within/nearest/isInside/blockers).",
+            "@jgengine/core/world/features gained composable outdoor descriptors: environment(), terrain(), rain(), snow(), grass(), ocean(), building().",
+            "@jgengine/core/world/regions (createRegionField — blend content-agnostic biomes by nearest selector, extends TerrainField so it ground-snaps) and world/scatterItems (scatterItems — region-driven, grounded, above-water/slope-aware content scatter with pickWeighted).",
+            "@jgengine/core/physics/physicsWorld — standalone fixed-capacity rigid-body sim (SoA buffers, spatial-hash broadphase, sleeping) for many colliding dynamic bodies; independent of the defineGame physics character-controller config.",
+            "ctx.time simulation clock (@jgengine/core/time/simClock) — dt in onTick is game time, so decay/regen/AI written as rate*dt obey pause and fast-forward for free. Configure via defineGame({ time: { scale?, speeds?, dayLength?, start?, startPaused? } }); pause/play/setSpeed/calendar controls, and useGameClock() in React.",
+            "@jgengine/shell environment/terrain/water/weather/structures renderers — EnvironmentScene mounts an environment() descriptor; 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.",
+        ],
+        changed: [],
+        removed: [],
+    },
+    "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/physics/physicsWorld.d.ts

@@ -0,0 +1,136 @@
+export interface PhysicsBounds {
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+}
+export interface PhysicsWorldConfig {
+    /** Maximum bodies the SoA buffers can hold. Fixed at construction; no reallocation later. */
+    capacity: number;
+    /** AABB container; every body is constrained inside it (floor included). */
+    bounds: PhysicsBounds;
+    /** Downward acceleration applied to awake bodies each substep. Default -20. */
+    gravity?: number;
+    /** Broadphase cell edge; tune to ≈ small-body diameter. Default 1. */
+    cellSize?: number;
+    /** Fixed substep length in seconds. Default 1/60. */
+    fixedDt?: number;
+    /** Cap on substeps per `step()` — bounds catch-up work, drops the rest. Default 4. */
+    maxSubsteps?: number;
+    /** Bounce factor on contacts and walls, 0..1. Default 0.2. */
+    restitution?: number;
+    /** Approach speed below which restitution is ignored (contacts rest instead of jittering). Default 1. */
+    restitutionThreshold?: number;
+    /** Coulomb friction coefficient on contacts and the floor, 0..1. Default 0.4. */
+    friction?: number;
+    /** Per-second linear velocity damping (physical energy bleed so piles settle and sleep). Default 0.2. */
+    linearDamping?: number;
+    /** Sequential-impulse velocity iterations per substep (higher = more stable stacks). Default 4. */
+    solverIterations?: number;
+    /** Baumgarte positional-correction fraction per substep, 0..1. Default 0.2. */
+    correctionFactor?: number;
+    /** Penetration tolerated before correction kicks in. Default 0.005. */
+    slop?: number;
+    /** Speed at or below which a body counts as still. Default 0.08. */
+    sleepLinearVelocity?: number;
+    /** Consecutive still substeps before a body sleeps. Default 30. */
+    sleepThresholdSteps?: number;
+    /** Approach speed a contact must exceed to wake a sleeping body (resting contacts don't). Default 0.5. */
+    wakeThreshold?: number;
+}
+export interface PhysicsStats {
+    count: number;
+    awake: number;
+    sleeping: number;
+    contacts: number;
+    pairs: number;
+    substeps: number;
+    stepMs: number;
+}
+export interface AddBodyOptions {
+    position: readonly [number, number, number];
+    halfExtents: readonly [number, number, number];
+    velocity?: readonly [number, number, number];
+    /** ≤ 0 or omitted with `static` → infinite mass (immovable collider). Default 1. */
+    mass?: number;
+    /** Immovable collider: never integrates, never sleeps-out, invMass 0. */
+    static?: boolean;
+    /** Seed the body asleep (a settled bed pays no integration cost until woken). */
+    asleep?: boolean;
+}
+/** Grid cell containing a point, clamped into the grid. Pure — exported for tests. */
+export declare function cellCoord(value: number, min: number, cellSize: number, cells: number): number;
+/** Linear cell index from clamped 3D coords. Pure — exported for tests. */
+export declare function cellIndex(cx: number, cy: number, cz: number, nx: number, ny: number): number;
+export declare class PhysicsWorld {
+    readonly capacity: number;
+    readonly bounds: PhysicsBounds;
+    readonly gravity: number;
+    readonly cellSize: number;
+    readonly fixedDt: number;
+    readonly maxSubsteps: number;
+    readonly restitution: number;
+    readonly restitutionThreshold: number;
+    readonly friction: number;
+    readonly linearDamping: number;
+    readonly solverIterations: number;
+    readonly correctionFactor: number;
+    readonly slop: number;
+    readonly sleepMove2: number;
+    readonly sleepSteps: number;
+    readonly wakeThreshold: number;
+    readonly posX: Float32Array;
+    readonly posY: Float32Array;
+    readonly posZ: Float32Array;
+    readonly velX: Float32Array;
+    readonly velY: Float32Array;
+    readonly velZ: Float32Array;
+    readonly halfX: Float32Array;
+    readonly halfY: Float32Array;
+    readonly halfZ: Float32Array;
+    readonly invMass: Float32Array;
+    readonly flags: Uint8Array;
+    /** 1 for a body that took part in a contact this frame; reset each `step()`. Render tint reads this. */
+    readonly contact: Uint8Array;
+    private readonly sleepTimer;
+    private readonly prevX;
+    private readonly prevY;
+    private readonly prevZ;
+    private readonly nx;
+    private readonly ny;
+    private readonly nz;
+    private readonly numCells;
+    private readonly cellStart;
+    private readonly cursor;
+    private readonly sorted;
+    private readonly bodyCell;
+    private readonly awakeList;
+    private readonly awakeSlot;
+    private awakeCount;
+    private bodyCount;
+    private accumulator;
+    private readonly stats;
+    constructor(config: PhysicsWorldConfig);
+    private addAwake;
+    private removeAwake;
+    get count(): number;
+    get cells(): {
+        nx: number;
+        ny: number;
+        nz: number;
+        total: number;
+    };
+    addBody(options: AddBodyOptions): number;
+    isSleeping(i: number): boolean;
+    wake(i: number): void;
+    wakeAll(): void;
+    clear(): void;
+    /** Advance by a real frame delta; runs whole fixed substeps and carries the remainder. */
+    step(frameDt: number): PhysicsStats;
+    getStats(): PhysicsStats;
+    private substep;
+    private constrainBounds;
+    private buildGrid;
+    private cellOf;
+    private solve;
+    private resolve;
+    private updateSleep;
+}