@jgengine/react 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/hooks.d.ts

@@ -8,6 +8,7 @@ import type { InventorySlot } from "@jgengine/core/inventory/inventoryModel";
 import type { StatValue } from "@jgengine/core/scene/entityStats";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { ClockSnapshot, SimClock } from "@jgengine/core/time/simClock";
 import { type PositionedPrompt } from "@jgengine/core/interaction/proximityPrompt";
 export declare function useGameStore<T>(selector: (ctx: GameContext) => T): T;
 export declare function useGame(): {
@@ -41,4 +42,7 @@ export declare function useLeaderboard(stat: string, options: {
 }[];
 export declare function useLocalPlayerDead(healthStatId?: string): boolean;
 export declare function localPlayerEntity(ctx: GameContext): SceneEntity | null;
+export declare function useGameClock(): ClockSnapshot & {
+    controls: SimClock;
+};
 export declare function useActivePrompt<T extends PositionedPrompt>(prompts?: readonly T[]): T | null;

package/dist/hooks.js

@@ -64,6 +64,11 @@ export function localPlayerEntity(ctx) {
         ctx.scene.entity.list().find((entity) => entity.role === "player") ??
         null);
 }
+export function useGameClock() {
+    const ctx = useGameContext();
+    useSyncExternalStore(ctx.subscribe, ctx.version, ctx.version);
+    return { ...ctx.time.snapshot(), controls: ctx.time };
+}
 export function useActivePrompt(prompts) {
     return useGameStore((ctx) => {
         if (prompts === undefined || prompts.length === 0)

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./provider.js";
+export * from "./hooks.js";
+export * from "./components.js";
+export * from "./engineStore.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./provider.js";
+export * from "./hooks.js";
+export * from "./components.js";
+export * from "./engineStore.js";

package/dist/liveBind.d.ts

@@ -0,0 +1,20 @@
+import { type CSSProperties } from "react";
+/**
+ * Drive a DOM/SVG element from a per-frame value without re-rendering React.
+ * Runs one requestAnimationFrame loop, reads `get()` each frame, and calls
+ * `apply(value, element)` so HUDs bound to live engine state (speed, pose)
+ * never re-render and never lag. `get`/`apply` may change without restarting.
+ */
+export declare function useFrameBind<T, E extends Element = Element>(ref: {
+    current: E | null;
+}, get: () => T, apply: (value: T, element: E) => void): void;
+/**
+ * A `<span>` whose text tracks a live value every frame (the 90% case of
+ * useFrameBind). `<LiveText get={() => groundSpeed(car) * KMH} format={Math.round} />`.
+ */
+export declare function LiveText({ get, format, className, style, }: {
+    get: () => number | string;
+    format?: (value: number | string) => string;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/liveBind.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+/**
+ * Drive a DOM/SVG element from a per-frame value without re-rendering React.
+ * Runs one requestAnimationFrame loop, reads `get()` each frame, and calls
+ * `apply(value, element)` so HUDs bound to live engine state (speed, pose)
+ * never re-render and never lag. `get`/`apply` may change without restarting.
+ */
+export function useFrameBind(ref, get, apply) {
+    const getRef = useRef(get);
+    getRef.current = get;
+    const applyRef = useRef(apply);
+    applyRef.current = apply;
+    useEffect(() => {
+        let raf = 0;
+        const tick = () => {
+            const element = ref.current;
+            if (element !== null)
+                applyRef.current(getRef.current(), element);
+            raf = requestAnimationFrame(tick);
+        };
+        raf = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(raf);
+    }, [ref]);
+}
+/**
+ * A `<span>` whose text tracks a live value every frame (the 90% case of
+ * useFrameBind). `<LiveText get={() => groundSpeed(car) * KMH} format={Math.round} />`.
+ */
+export function LiveText({ get, format, className, style, }) {
+    const ref = useRef(null);
+    useFrameBind(ref, get, (value, element) => {
+        const text = format !== undefined ? format(value) : String(value);
+        if (element.textContent !== text)
+            element.textContent = text;
+    });
+    return _jsx("span", { ref: ref, className: className, style: style });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -15,6 +15,10 @@
     "CHANGELOG.md"
   ],
   "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"
@@ -25,7 +29,7 @@
     "check-types": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.5.0"
+    "@jgengine/core": "^0.6.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"