@jgengine/shell 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/README.md

@@ -14,3 +14,30 @@ const games: GameRegistry = {
 ```
 
 Peer deps: `react`, `three`, `@react-three/fiber`, `@react-three/drei`, `three-stdlib`. The shell's HUD classes are Tailwind — add an `@source` entry for `node_modules/@jgengine/shell` in your CSS. AGPL-3.0-only.
+
+Weather primitives are available from `@jgengine/shell/weather` for game scene overlays:
+
+```tsx
+import { WeatherLayer, LightningStrike } from "@jgengine/shell/weather";
+
+<WeatherLayer mode="rain" intensity={0.8} wind={[1.5, 0, -0.4]} rain={{ count: 7000 }} />;
+<LightningStrike origin={[0, 22, 0]} target={[4, 0, -6]} strikeKey={stormTick} />;
+```
+
+`RainField` and `SnowField` can also be mounted directly. The primitives use camera-following instanced volumes, prop-driven density controls, shared time/wind uniforms under `WeatherLayer`, and explicit Three resource disposal. They were shaped from ideas in achrefelouafi's MIT RainSystemThreeJS and SnowSystemThreeJS references without bringing over GUI, audio, postprocessing, or app-specific scene setup.
+
+## Terrain primitives
+
+`@jgengine/shell/terrain` exports R3F helpers for shell-local natural scenes:
+
+```tsx
+import { GrassField, ProceduralGround, createProceduralTerrainSampler } from "@jgengine/shell/terrain";
+
+const terrain = { seed: "meadow", size: 48, height: 0.9 };
+const heightAt = createProceduralTerrainSampler(terrain);
+
+<>
+  <ProceduralGround terrain={terrain} />
+  <GrassField area={48} heightAt={heightAt} density={0.65} />
+</>;
+```

package/dist/GamePlayerShell.js

@@ -85,23 +85,31 @@ function EntityModel({ model }) {
     const gltf = useLoader(GLTFLoader, model.url);
     const scene = useMemo(() => gltf.scene.clone(true), [gltf]);
     const scale = model.scale ?? 1;
-    return _jsx("primitive", { object: scene, "position-y": model.y ?? 0, scale: [scale, scale, scale] });
+    const baseY = model.y ?? 0;
+    const dims = model.dims;
+    const centered = (model.anchor ?? "center") === "center" && dims !== undefined;
+    const position = centered
+        ? [-scale * dims.center.x, baseY - scale * dims.minY, -scale * dims.center.z]
+        : [0, baseY, 0];
+    return _jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] });
 }
 function resolveModel(value, assets) {
     if (value === undefined)
         return undefined;
     if (typeof value !== "string")
         return value;
-    const url = assets.resolve(value)?.url;
-    return url === undefined ? undefined : { url };
+    const ref = assets.resolve(value);
+    if (ref === null)
+        return undefined;
+    return ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims };
 }
-function EntityMarker({ entity, model, sprite, isLocal, targeted, onSelect, }) {
+function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, onSelect, }) {
     const color = isLocal ? "#4ade80" : entity.role === "npc" ? colorFromId(entity.name) : "#9ca3af";
     return (_jsxs("group", { position: [entity.position[0], entity.position[1], entity.position[2]], "rotation-y": entity.rotationY, onPointerDown: (event) => {
             event.stopPropagation();
             if (!isLocal)
                 onSelect(entity);
-        }, children: [model !== undefined ? (_jsx(EntityModel, { model: model })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : entity.role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, children: [_jsx("sphereGeometry", { args: [0.45, 16, 16] }), _jsx("meshStandardMaterial", { color: color })] })) : (_jsxs(_Fragment, { children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: color })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
+        }, children: [custom !== undefined && custom !== null ? (custom) : model !== undefined ? (_jsx(EntityModel, { model: model })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : entity.role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, children: [_jsx("sphereGeometry", { args: [0.45, 16, 16] }), _jsx("meshStandardMaterial", { color: color })] })) : (_jsxs(_Fragment, { children: [_jsxs("mesh", { "position-y": 0.95, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx("meshStandardMaterial", { color: color })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
 }
 function GroundPlane() {
     const geometry = useMemo(() => {
@@ -134,7 +142,7 @@ function RockField() {
     }), []);
     return (_jsx(_Fragment, { children: rocks.map((rock) => (_jsxs("mesh", { position: [rock.x, 0.25 * rock.scale, rock.z], rotation: [0.1, rock.rotation, -0.08], scale: [rock.scale * 1.4, rock.scale * 0.7, rock.scale], children: [_jsx("dodecahedronGeometry", { args: [0.8, 0] }), _jsx("meshStandardMaterial", { color: "#6b6f63", roughness: 1 })] }, rock.id))) }));
 }
-function WorldView({ entitySprites, entityModels, objectModels, assets, }) {
+function WorldView({ entitySprites, entityModels, objectModels, environment: Environment, assets, renderEntity, }) {
     const ctx = useGameContext();
     const entities = useSceneEntities();
     const objects = useSceneObjects();
@@ -144,7 +152,7 @@ function WorldView({ entitySprites, entityModels, objectModels, assets, }) {
         const relation = ctx.scene.entity.canReceive(entity.id, "damage") === null ? "hostile" : "friendly";
         ctx.scene.entity.setTarget(player.userId, relation === "hostile" || entity.role === "npc" ? entity.id : null);
     };
-    return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx("gridHelper", { args: [160, 80, "#3a3f4a", "#2b2f38"], "position-y": 0.01 }), _jsx(RockField, {}), entities.map((entity) => (_jsx(EntityMarker, { entity: entity, model: resolveModel(entityModels?.[entity.name], assets), sprite: entitySprites?.[entity.name], isLocal: entity.id === player.userId, targeted: entity.id === targetId, onSelect: handleSelect }, entity.id))), objects.map((object) => {
+    return (_jsxs(_Fragment, { children: [Environment !== undefined ? (_jsx(Environment, {})) : (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx("gridHelper", { args: [160, 80, "#3a3f4a", "#2b2f38"], "position-y": 0.01 }), _jsx(RockField, {})] })), entities.map((entity) => (_jsx(EntityMarker, { entity: entity, custom: renderEntity?.(entity), model: resolveModel(entityModels?.[entity.name], assets), sprite: entitySprites?.[entity.name], isLocal: entity.id === player.userId, targeted: entity.id === targetId, onSelect: handleSelect }, entity.id))), objects.map((object) => {
                 const model = resolveModel(objectModels?.[object.catalogId], assets) ??
                     resolveModel(object.catalogId, assets);
                 return (_jsx("group", { position: [object.position[0], object.position[1], object.position[2]], "rotation-y": object.rotationY, children: model !== undefined ? (_jsx(EntityModel, { model: model })) : (_jsxs("mesh", { "position-y": 0.5, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx("meshStandardMaterial", { color: colorFromId(object.catalogId) })] })) }, object.instanceId));
@@ -161,6 +169,7 @@ function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef
     useFrame((_state, rawDt) => {
         try {
             const dt = Math.min(rawDt, 0.05);
+            const gameDt = ctx.time.advance(dt);
             if (tracker.isDown("turnLeft"))
                 yawRef.current += TURN_SPEED * dt;
             if (tracker.isDown("turnRight"))
@@ -185,9 +194,10 @@ function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef
                     rotationY: intent.moving
                         ? Math.atan2(motion.horizontalVelocityX, motion.horizontalVelocityZ)
                         : player.rotationY,
+                    dt: rawDt,
                 });
             }
-            playable.loop.onTick(ctx, dt);
+            playable.loop.onTick(ctx, gameDt);
             if (tracker.wasPressed("tabTarget")) {
                 if (ctx.game.commands.has("target.cycle"))
                     ctx.game.commands.run("target.cycle", {});
@@ -430,7 +440,7 @@ export function GamePlayerShell({ playable, multiplayer = null, }) {
             else if (event.deltaY > 0 && ctx.game.commands.has("ui.hotbarScrollPrev")) {
                 ctx.game.commands.run("ui.hotbarScrollPrev", {});
             }
-        }, children: [_jsxs(Canvas, { camera: { fov: 55, near: 0.1, far: 300 }, children: [_jsx("color", { attach: "background", args: ["#14161b"] }), _jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 }), _jsxs(GameProvider, { context: ctx, children: [_jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, assets: playable.game.assets }), WorldOverlay !== undefined ? _jsx(WorldOverlay, {}) : null, barsStatId !== null ? _jsx(WorldEntityBars, { statId: barsStatId }) : null, _jsx(WorldFloatText, {}), _jsx(ProjectileTracers, {}), firstPerson ? (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: playable.camera?.firstPerson, followEntityId: playable.camera?.followEntityId })) : (_jsx(GameOrbitCamera, { yawRef: yawRef, pitchRef: pitchRef, config: playable.camera, followEntityId: playable.camera?.followEntityId, onCameraFollow: playable.camera?.onCameraFollow, onDragChange: (dragging) => {
+        }, children: [_jsxs(Canvas, { camera: { fov: 55, near: 0.1, far: 300 }, children: [_jsx("color", { attach: "background", args: ["#14161b"] }), _jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 }), _jsxs(GameProvider, { context: ctx, children: [_jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, environment: playable.environment, assets: playable.game.assets, renderEntity: playable.renderEntity }), WorldOverlay !== undefined ? _jsx(WorldOverlay, {}) : null, barsStatId !== null ? _jsx(WorldEntityBars, { statId: barsStatId }) : null, _jsx(WorldFloatText, {}), _jsx(ProjectileTracers, {}), firstPerson ? (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: playable.camera?.firstPerson, followEntityId: playable.camera?.followEntityId })) : (_jsx(GameOrbitCamera, { yawRef: yawRef, pitchRef: pitchRef, config: playable.camera, followEntityId: playable.camera?.followEntityId, onCameraFollow: playable.camera?.onCameraFollow, onDragChange: (dragging) => {
                                     cameraDraggingRef.current = dragging;
                                 } }))] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef })] }), _jsx(GameUiErrorBoundary, { onRuntimeError: reportRuntimeError, children: _jsx(GameProvider, { context: ctx, children: _jsx(GameUI, {}) }) }), showReticle ? _jsx(Reticle, {}) : null, _jsx(DiagnosticOverlay, { diagnostics: diagnostics })] }));
 }

package/dist/demo/demoGame.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { defineGame } from "@jgengine/core/game/defineGame";
 import { createAssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import { CurrencyPill, HealthBar, SlotGrid } from "@jgengine/react/components";
-import { useFeed, useGameStore, usePlayer, useTarget } from "@jgengine/react/hooks";
+import { useFeed, useGameClock, useGameStore, usePlayer, useTarget } from "@jgengine/react/hooks";
 const HERO = "hero";
 const MOB = "gloomSlime";
 const LOOT_TABLE = "slime-drops";
@@ -39,6 +39,7 @@ const game = defineGame({
     assets: createAssetCatalog(),
     multiplayer: null,
     inventories: { [HOTBAR]: { slots: 4, hud: "hotbar" } },
+    time: { start: 8 * 3600, speeds: [1, 2, 3, 4] },
     input: {
         moveForward: ["KeyW"],
         moveBack: ["KeyS"],
@@ -185,9 +186,16 @@ function KillFeedPanel() {
 function HotbarPanel() {
     return (_jsx(SlotGrid, { inventoryId: HOTBAR, className: "flex gap-1.5", renderSlot: (slot, index) => (_jsxs("div", { className: "w-16 rounded border border-white/20 bg-black/60 px-1.5 py-1 text-center text-[11px]", children: [_jsx("span", { className: "text-white/50", children: index + 1 }), _jsx("p", { className: "truncate text-white", children: slot === null ? "—" : slot.itemId })] })) }));
 }
+function ClockPanel() {
+    const { paused, playSpeed, speeds, calendar, controls } = useGameClock();
+    const pad = (value) => value.toString().padStart(2, "0");
+    return (_jsxs("div", { className: "pointer-events-auto flex items-center gap-2 rounded bg-black/60 px-2 py-1 text-xs", children: [_jsxs("span", { className: "tabular-nums text-white", children: ["Day ", calendar.day + 1, " \u00B7 ", pad(calendar.hour), ":", pad(calendar.minute)] }), _jsx("button", { onClick: () => controls.toggle(), className: "rounded border border-white/25 px-1.5 py-0.5 text-white/80 hover:bg-white/10", children: paused ? "▶" : "⏸" }), _jsx("div", { className: "flex gap-0.5", children: speeds.map((speed) => (_jsxs("button", { onClick: () => controls.setSpeed(speed), className: `rounded border px-1.5 py-0.5 ${!paused && speed === playSpeed
+                        ? "border-amber-300 bg-amber-300/20 text-amber-200"
+                        : "border-white/25 text-white/70 hover:bg-white/10"}`, children: [speed, "\u00D7"] }, speed))) })] }));
+}
 function DemoGameUI() {
     const player = usePlayer();
-    return (_jsxs("div", { className: "pointer-events-none absolute inset-0 font-mono text-white", children: [_jsx("div", { className: "absolute left-1/2 top-4 w-56 -translate-x-1/2", children: _jsx(TargetPanel, { userId: player.userId }) }), _jsxs("div", { className: "absolute right-4 top-4 flex flex-col items-end gap-2", children: [_jsx(CurrencyPill, { currencyId: GOLD, className: "rounded bg-black/60 px-2 py-1 text-sm text-amber-300" }), _jsx(KillFeedPanel, {})] }), _jsx("div", { className: "absolute bottom-4 left-4 w-64", children: _jsx(VitalsPanel, { userId: player.userId }) }), _jsx("div", { className: "absolute bottom-4 left-1/2 -translate-x-1/2", children: _jsx(HotbarPanel, {}) }), _jsx("div", { className: "absolute bottom-4 right-4 max-w-[220px] text-right text-[11px] leading-4 text-white/40", children: "WASD move \u00B7 Space jump \u00B7 Shift sprint \u00B7 Q/E turn \u00B7 Tab target \u00B7 Esc clear \u00B7 1 sword \u00B7 2 zap" })] }));
+    return (_jsxs("div", { className: "pointer-events-none absolute inset-0 font-mono text-white", children: [_jsx("div", { className: "absolute left-4 top-4", children: _jsx(ClockPanel, {}) }), _jsx("div", { className: "absolute left-1/2 top-4 w-56 -translate-x-1/2", children: _jsx(TargetPanel, { userId: player.userId }) }), _jsxs("div", { className: "absolute right-4 top-4 flex flex-col items-end gap-2", children: [_jsx(CurrencyPill, { currencyId: GOLD, className: "rounded bg-black/60 px-2 py-1 text-sm text-amber-300" }), _jsx(KillFeedPanel, {})] }), _jsx("div", { className: "absolute bottom-4 left-4 w-64", children: _jsx(VitalsPanel, { userId: player.userId }) }), _jsx("div", { className: "absolute bottom-4 left-1/2 -translate-x-1/2", children: _jsx(HotbarPanel, {}) }), _jsx("div", { className: "absolute bottom-4 right-4 max-w-[220px] text-right text-[11px] leading-4 text-white/40", children: "WASD move \u00B7 Space jump \u00B7 Shift sprint \u00B7 Q/E turn \u00B7 Tab target \u00B7 Esc clear \u00B7 1 sword \u00B7 2 zap" })] }));
 }
 export const demoGame = {
     game,

package/dist/demo/environmentShowcase.d.ts

@@ -0,0 +1,2 @@
+import type { PlayableGame } from "../registry.js";
+export declare const environmentShowcaseGame: PlayableGame;

package/dist/demo/environmentShowcase.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { building, environment, grass, ocean, rain, terrain, } from "@jgengine/core/world/features";
+import { EnvironmentScene } from "../environment/EnvironmentScene.js";
+import { demoGame } from "./demoGame.js";
+const showcase = environment({
+    terrain: terrain({ bounds: { w: 220, d: 220 }, height: 4, frequency: 0.035, seed: "showcase", waterLevel: -1 }),
+    vegetation: grass({ area: { w: 120, d: 120 }, density: 5, colors: ["#31531f", "#8fbf4a"], seed: "showcase" }),
+    water: ocean({ bounds: { w: 520, d: 520 }, level: -1.4, waveHeight: 0.9, waveSpeed: 0.5, color: "#1f6f92" }),
+    weather: rain({ area: { w: 160, d: 160, h: 70 }, density: 0.5, wind: [1.4, 0.4] }),
+    structures: building({ count: 6, footprint: { w: 12, d: 9 }, stories: [3, 7], storyHeight: 2.8, spacing: 6, seed: "showcase" }),
+});
+export const environmentShowcaseGame = {
+    ...demoGame,
+    environment: () => _jsx(EnvironmentScene, { feature: showcase }),
+};

package/dist/environment/EnvironmentScene.d.ts

@@ -0,0 +1,5 @@
+import type { EnvironmentWorldFeature } from "@jgengine/core/world/features";
+export interface EnvironmentSceneProps {
+    feature: EnvironmentWorldFeature;
+}
+export declare function EnvironmentScene({ feature }: EnvironmentSceneProps): import("react").JSX.Element;

package/dist/environment/EnvironmentScene.js

@@ -0,0 +1,75 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { generateBuildingDistrict } from "@jgengine/core/world/buildings";
+import { resolveTerrainField } from "@jgengine/core/world/terrain";
+import { GeneratedBuilding } from "../structures/GeneratedBuilding.js";
+import { GrassField } from "../terrain/GrassField.js";
+import { ProceduralGround } from "../terrain/ProceduralGround.js";
+import { Ocean } from "../water/Ocean.js";
+import { RainField } from "../weather/RainField.js";
+import { SnowField } from "../weather/SnowField.js";
+import { WeatherUniformProvider } from "../weather/weatherUniforms.js";
+const DEFAULT_TERRAIN_FREQUENCY = 0.03;
+function TerrainGround({ terrain }) {
+    return (_jsx(ProceduralGround, { terrain: {
+            size: [terrain.bounds.w, terrain.bounds.d],
+            height: terrain.height,
+            seed: terrain.seed,
+            moundScale: terrain.frequency ?? DEFAULT_TERRAIN_FREQUENCY,
+            octaves: terrain.octaves,
+            ridged: terrain.ridged,
+            baseOffset: terrain.baseHeight,
+        }, colors: terrain.waterLevel === undefined ? undefined : { waterlineHeight: terrain.waterLevel } }));
+}
+function Vegetation({ grass, field }) {
+    return (_jsx(GrassField, { area: [grass.area.w, grass.area.d], density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: field.sampleHeight, colorBase: grass.colors[0], colorTip: grass.colors[grass.colors.length - 1], wind: { strength: grass.windStrength } }));
+}
+function weatherVolume(area) {
+    return [area.w, area.h ?? 60, area.d];
+}
+function Precipitation({ weather }) {
+    if (weather.kind === "rain") {
+        return (_jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }));
+    }
+    return (_jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }));
+}
+function Weather({ weather }) {
+    return (_jsx(WeatherUniformProvider, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
+}
+function Water({ ocean }) {
+    return (_jsx(Ocean, { "position-y": ocean.level, config: {
+            size: Math.max(ocean.bounds.w, ocean.bounds.d),
+            amplitude: ocean.waveHeight,
+            speed: ocean.waveSpeed,
+            color: { shallow: ocean.color },
+        } }));
+}
+function Structures({ structures }) {
+    const buildings = useMemo(() => {
+        const columns = Math.max(1, Math.ceil(Math.sqrt(structures.count)));
+        const rows = Math.max(1, Math.ceil(structures.count / columns));
+        const spacing = structures.spacing;
+        const origin = [
+            -((columns - 1) * (structures.footprint.w + spacing)) / 2,
+            -((rows - 1) * (structures.footprint.d + spacing)) / 2,
+        ];
+        return generateBuildingDistrict({
+            rows,
+            columns,
+            origin,
+            lotSize: structures.footprint,
+            streetWidth: spacing,
+            floorRange: structures.stories,
+            base: { floorHeight: structures.storyHeight },
+            ...(structures.seed === undefined ? {} : { seed: structures.seed }),
+        }).slice(0, structures.count);
+    }, [structures]);
+    return (_jsx(_Fragment, { children: buildings.map((building) => (_jsx(GeneratedBuilding, { building: building }, building.id))) }));
+}
+export function EnvironmentScene({ feature }) {
+    const field = useMemo(() => resolveTerrainField(feature.terrain), [feature.terrain]);
+    const vegetation = feature.vegetation ?? [];
+    const water = feature.water ?? [];
+    const structures = feature.structures ?? [];
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain }) : null, water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry }, `structures-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+}

package/dist/environment/index.d.ts

@@ -0,0 +1 @@
+export { EnvironmentScene, type EnvironmentSceneProps } from "./EnvironmentScene.js";

package/dist/environment/index.js

@@ -0,0 +1 @@
+export { EnvironmentScene } from "./EnvironmentScene.js";

package/dist/environment.d.ts

@@ -0,0 +1 @@
+export * from "./environment/index.js";

package/dist/environment.js

@@ -0,0 +1 @@
+export * from "./environment/index.js";

package/dist/registry.d.ts

@@ -1,4 +1,6 @@
-import type { ComponentType } from "react";
+import type { ComponentType, ReactNode } from "react";
 import type { PlayableGame as EnginePlayableGame } from "@jgengine/core/game/playableGame";
-export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType>;
+import type { SceneEntity } from "@jgengine/core/scene/entityStore";
+export type RenderEntity = (entity: SceneEntity) => ReactNode;
+export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity>;
 export type GameRegistry = Record<string, () => Promise<PlayableGame>>;

package/dist/structures/GeneratedBuilding.d.ts

@@ -0,0 +1,44 @@
+import { type ReactNode } from "react";
+export type BuildingFacade = "front" | "back" | "left" | "right" | "roof";
+export type BuildingPartKind = "wall" | "window" | "awning" | "airConditioner" | "clothesline" | "storefront" | "shutter" | "storeSign" | "roof" | "roofProp" | "guardrail" | "corner";
+export interface BuildingPartPlacement {
+    id: string;
+    kind: BuildingPartKind;
+    facade: BuildingFacade;
+    position: readonly [number, number, number];
+    rotationY: number;
+    scale: readonly [number, number, number];
+}
+export interface GeneratedBuildingData {
+    id: string;
+    parts: readonly BuildingPartPlacement[];
+}
+export interface BuildingMaterialPalette {
+    wall?: string;
+    window?: string;
+    awning?: string;
+    airConditioner?: string;
+    clothesline?: string;
+    storefront?: string;
+    shutter?: string;
+    storeSign?: string;
+    roof?: string;
+    roofProp?: string;
+    guardrail?: string;
+    corner?: string;
+}
+export interface BuildingKitRenderer {
+    renderPart?: (part: BuildingPartPlacement) => ReactNode | undefined;
+}
+export interface BuildingBlockProps {
+    part: BuildingPartPlacement;
+    palette?: BuildingMaterialPalette;
+}
+export interface GeneratedBuildingProps {
+    building: GeneratedBuildingData;
+    palette?: BuildingMaterialPalette;
+    kit?: BuildingKitRenderer;
+    visibleKinds?: readonly BuildingPartKind[];
+}
+export declare function BuildingBlock({ part, palette }: BuildingBlockProps): import("react").JSX.Element;
+export declare function GeneratedBuilding({ building, palette, kit, visibleKinds }: GeneratedBuildingProps): import("react").JSX.Element;

package/dist/structures/GeneratedBuilding.js

@@ -0,0 +1,86 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+const DEFAULT_PALETTE = {
+    wall: "#83766a",
+    window: "#8ecae6",
+    awning: "#c2410c",
+    airConditioner: "#d4d4d8",
+    clothesline: "#facc15",
+    storefront: "#3f3f46",
+    shutter: "#52525b",
+    storeSign: "#f97316",
+    roof: "#57534e",
+    roofProp: "#14b8a6",
+    guardrail: "#a8a29e",
+    corner: "#6b6258",
+};
+function colorFor(kind, palette) {
+    return palette?.[kind] ?? DEFAULT_PALETTE[kind];
+}
+function normalFor(facade) {
+    if (facade === "front")
+        return [0, 1];
+    if (facade === "back")
+        return [0, -1];
+    if (facade === "left")
+        return [-1, 0];
+    if (facade === "right")
+        return [1, 0];
+    return [0, 0];
+}
+function outwardOffset(part) {
+    if (part.kind === "wall" || part.kind === "roof" || part.kind === "corner")
+        return 0;
+    if (part.kind === "window" || part.kind === "shutter" || part.kind === "storefront")
+        return 0.025;
+    if (part.kind === "awning" || part.kind === "storeSign")
+        return 0.09;
+    return 0.12;
+}
+function materialFor(part, palette) {
+    const color = colorFor(part.kind, palette);
+    if (part.kind === "window" || part.kind === "storefront") {
+        return _jsx("meshPhysicalMaterial", { color: color, roughness: 0.12, metalness: 0, transparent: true, opacity: 0.56 });
+    }
+    if (part.kind === "storeSign") {
+        return _jsx("meshStandardMaterial", { color: color, emissive: color, emissiveIntensity: 0.6, roughness: 0.5 });
+    }
+    if (part.kind === "roofProp") {
+        return _jsx("meshStandardMaterial", { color: color, roughness: 0.65, metalness: 0.1 });
+    }
+    return _jsx("meshStandardMaterial", { color: color, roughness: 0.88, metalness: 0 });
+}
+function BlockMesh({ part, palette }) {
+    const [nx, nz] = normalFor(part.facade);
+    const offset = outwardOffset(part);
+    const position = [
+        part.position[0] + nx * offset,
+        part.position[1],
+        part.position[2] + nz * offset,
+    ];
+    return (_jsxs("mesh", { position: position, rotation: [0, part.rotationY, 0], castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [part.scale[0], part.scale[1], part.scale[2]] }), materialFor(part, palette)] }));
+}
+export function BuildingBlock({ part, palette }) {
+    if (part.kind === "clothesline") {
+        const [nx, nz] = normalFor(part.facade);
+        const offset = outwardOffset(part);
+        const position = [
+            part.position[0] + nx * offset,
+            part.position[1],
+            part.position[2] + nz * offset,
+        ];
+        return (_jsxs("group", { position: position, rotation: [0, part.rotationY, 0], children: [_jsxs("mesh", { position: [0, 0, -0.09], castShadow: true, children: [_jsx("boxGeometry", { args: [part.scale[0], Math.max(part.scale[1], 0.025), 0.025] }), materialFor(part, palette)] }), _jsxs("mesh", { position: [0, 0, 0.09], castShadow: true, children: [_jsx("boxGeometry", { args: [part.scale[0], Math.max(part.scale[1], 0.025), 0.025] }), materialFor(part, palette)] })] }));
+    }
+    return _jsx(BlockMesh, { part: part, palette: palette });
+}
+export function GeneratedBuilding({ building, palette, kit, visibleKinds }) {
+    const visible = useMemo(() => (visibleKinds === undefined ? null : new Set(visibleKinds)), [visibleKinds]);
+    return (_jsx("group", { name: building.id, children: building.parts.map((part) => {
+            if (visible !== null && !visible.has(part.kind))
+                return null;
+            const rendered = kit?.renderPart?.(part);
+            if (rendered !== undefined)
+                return _jsx("group", { children: rendered }, part.id);
+            return _jsx(BuildingBlock, { part: part, palette: palette }, part.id);
+        }) }));
+}

package/dist/terrain/GrassField.d.ts

@@ -0,0 +1,21 @@
+import { type ThreeElements } from "@react-three/fiber";
+import { type GrassBladeGeometryOptions, type GrassRange } from "./grassGeometry.js";
+import { type GrassMaterialOptions, type GrassWindOptions } from "./grassMaterial.js";
+import type { TerrainArea, TerrainHeightSampler } from "./terrainMath.js";
+export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
+    count?: number;
+    density?: number;
+    area?: TerrainArea;
+    seed?: GrassBladeGeometryOptions["seed"];
+    segments?: number;
+    bladeHeight?: GrassRange;
+    bladeWidth?: GrassRange;
+    bladeBend?: GrassRange;
+    heightAt?: TerrainHeightSampler;
+    colorBase?: GrassMaterialOptions["colorBase"];
+    colorTip?: GrassMaterialOptions["colorTip"];
+    colorVariation?: number;
+    wind?: GrassWindOptions | false;
+    roughness?: number;
+}
+export declare function GrassField({ count, density, area, seed, segments, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow, receiveShadow, frustumCulled, ...meshProps }: GrassFieldProps): import("react").JSX.Element;

package/dist/terrain/GrassField.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo } from "react";
+import { createGrassBladeGeometry } from "./grassGeometry.js";
+import { createGrassMaterial } from "./grassMaterial.js";
+export function GrassField({ count = 6000, density = 1, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow = false, receiveShadow = true, frustumCulled = false, ...meshProps }) {
+    const geometry = useMemo(() => createGrassBladeGeometry({
+        count,
+        area,
+        seed,
+        segments,
+        height: bladeHeight,
+        width: bladeWidth,
+        bend: bladeBend,
+        heightAt,
+    }), [area, bladeBend, bladeHeight, bladeWidth, count, heightAt, seed, segments]);
+    const handle = useMemo(() => createGrassMaterial({
+        colorBase,
+        colorTip,
+        colorVariation,
+        wind,
+        roughness,
+    }), [colorBase, colorTip, colorVariation, roughness, wind]);
+    geometry.instanceCount = Math.floor(Math.max(0, Math.min(1, density)) * count);
+    useFrame((state) => {
+        handle.uniforms.uTime.value = state.clock.elapsedTime;
+    });
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    useEffect(() => () => handle.material.dispose(), [handle]);
+    return (_jsx("mesh", { ...meshProps, geometry: geometry, material: handle.material, castShadow: castShadow, receiveShadow: receiveShadow, frustumCulled: frustumCulled }));
+}

package/dist/terrain/ProceduralGround.d.ts

@@ -0,0 +1,9 @@
+import { type ThreeElements } from "@react-three/fiber";
+import { type ProceduralTerrainConfig, type TerrainVertexColorOptions } from "./terrainMath.js";
+export interface ProceduralGroundProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
+    terrain?: ProceduralTerrainConfig;
+    colors?: TerrainVertexColorOptions;
+    roughness?: number;
+    metalness?: number;
+}
+export declare function ProceduralGround({ terrain, colors, roughness, metalness, receiveShadow, ...meshProps }: ProceduralGroundProps): import("react").JSX.Element;

package/dist/terrain/ProceduralGround.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "@react-three/fiber";
+import { useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { createProceduralGroundGeometry } from "./terrainMath.js";
+export function ProceduralGround({ terrain, colors, roughness = 0.94, metalness = 0, receiveShadow = true, ...meshProps }) {
+    const geometry = useMemo(() => createProceduralGroundGeometry(terrain, colors), [colors, terrain]);
+    const material = useMemo(() => new THREE.MeshStandardMaterial({
+        color: "#ffffff",
+        roughness,
+        metalness,
+        vertexColors: true,
+    }), [metalness, roughness]);
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    useEffect(() => () => material.dispose(), [material]);
+    return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });
+}

package/dist/terrain/grassGeometry.d.ts

@@ -0,0 +1,27 @@
+import * as THREE from "three";
+import { type TerrainSeed } from "./random.js";
+import { type TerrainArea, type TerrainHeightSampler } from "./terrainMath.js";
+export type GrassRange = number | readonly [min: number, max: number];
+export interface GrassBladeGeometryOptions {
+    count?: number;
+    area?: TerrainArea;
+    seed?: TerrainSeed;
+    segments?: number;
+    height?: GrassRange;
+    width?: GrassRange;
+    bend?: GrassRange;
+    heightAt?: TerrainHeightSampler;
+}
+export interface ResolvedGrassBladeGeometryOptions {
+    count: number;
+    area: TerrainArea;
+    seed: TerrainSeed;
+    segments: number;
+    height: readonly [min: number, max: number];
+    width: readonly [min: number, max: number];
+    bend: readonly [min: number, max: number];
+    heightAt: TerrainHeightSampler;
+}
+export declare function resolveGrassRange(value: GrassRange | undefined, fallback: readonly [number, number]): readonly [number, number];
+export declare function resolveGrassBladeGeometryOptions(options?: GrassBladeGeometryOptions): ResolvedGrassBladeGeometryOptions;
+export declare function createGrassBladeGeometry(options?: GrassBladeGeometryOptions): THREE.InstancedBufferGeometry;