@jgengine/core 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -15,6 +15,30 @@ the latest and surface the migration steps.
 
 _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

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/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/meta/changelog.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";
 export interface ChangelogEntry {
     migrate: readonly string[];
     added: readonly string[];

package/dist/meta/changelog.js

@@ -1,5 +1,23 @@
-export const VERSION = "0.5.0";
+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).",

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;
+}