@jgengine/shell 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -11,6 +11,53 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.8.0
+
+Transport-agnostic multiplayer (socket.io, WebRTC p2p, LAN/Fly adapters) plus grid/voxel
+and puzzle primitives, HUD-only presentation, cumulative leveling, and a round of
+controller/camera/sensor additions. **Breaking:** the `gameui` component kit moved out of
+`@jgengine/react` onto the shadcn registry.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.8.0` (the eight packages version in lockstep).
+- Additive only, except for `gameui` — every other 0.7.0 API is unchanged; opt into any of the below by importing it directly.
+- **Breaking:** replace any `@jgengine/react/gameui` import with the equivalent registry component (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), and swap `GameUiThemeProvider` for `--jg-*` CSS variables on a wrapper element. `GameIcon` and friends moved to `@jgengine/react/gameIcons`.
+- `leveling({ thresholdMode: 'cumulative' })` is opt-in; the default `perLevel` behavior is unchanged.
+- `defineGame.physics.gravity`/`jumpVelocity` are now read by the built-in kinematics controller every frame — if a game already set them expecting a no-op, jump/fall now actually reflects them; omit both to keep the previous defaults.
+
+### Added
+
+- Cumulative leveling — `leveling({ thresholdMode: 'cumulative' })` tracks xp as a lifetime total that resolves upward across levels and clamps at the max-level threshold once capped (#12).
+- Direction-aware pool depletion — `EffectSystem.canReceive(instanceId, effect, magnitude?)` takes an optional signed magnitude; negative checks the opposite direction and returns `pools-depleted` only when every stat in the receive order is already at max, so heals reach fully-depleted targets (#168).
+- Puzzle primitives — `puzzle/cellGrid` (uniform-cell boards: line-clear, match-3 cascade, run detection) and `puzzle/fallingPiece` (rotation-state shapes, ghost drop, lock delay, classic gravity/level/score curves) for Tetris/match-3 games (#166).
+- Voxel field — `world/voxelField` (`createVoxelField`, chunked block lattice, neighbors/exposedFaces, 3D DDA raycast, dirty-tracked `chunkVersion`) for voxel games and instanced renderers; assert on `field.summary()` the way environment worlds assert on `summarizeEnvironment` (#166).
+- `defineGame` games may omit `assets` (an empty catalog is injected); `PlayableGame.presentation: 'hud'` mounts no 3D canvas/camera/pointer for board/card/menu games; an `environment()` world auto-renders as the shell's backdrop when `PlayableGame.environment` is unset (#166).
+- Declared-action intent board — `turn/intent` `createIntentBoard` for one-turn-ahead intents (Slay-the-Spire style): declare/peek/all/consume/clear (#168).
+- `turnLoop` lifecycle hooks — `config.onTurnStart`/`onTurnEnd` fire on every `advanceTurn()`; `ctx.game.turn.loop(id, config)` lazily creates/returns a notify-wrapped `TurnLoop` so every mutation (`advanceTurn`/`advancePhase`/`advanceRound`/`spend`/`gain`/`refill`/`setOrder`/...) auto-bumps `ctx.version()` with no manual wiring (#163/#168).
+- `ctx.game.store` — a reactive per-game keyed store (`set`/`delete`/`get`/`has`/`subscribe`/`mapSnapshot`/`arraySnapshot`) plus `@jgengine/react`'s `useGameStore` selector hook, replacing hand-rolled module-level stores for ad-hoc reactive game state; `ctx.game.cards.pile(id, config?)` lazily creates/returns a notify-wrapped `CardPile` the same way; `createCardPile` gained an `onChange` hook for headless use; `CommandDefinition.apply` may return void for side-effect-only commands (#163).
+- Camera — `sideScroll` rig (fixed lateral follow for 2.5D platformers/beat-'em-ups), a `none` rig (no camera mounted; pairs with `PlayableGame.presentation: 'hud'`), `rts.pan: false` (static backdrop camera: no pan/edge-scroll/rotate/zoom, still re-centers on the follow target), and the `observer` rig now defaults to the local player when `bind` is unset (#167).
+- Sensors + session — `sensor/concealment` (`colorDistance`/`concealmentScore`/`createConcealmentSensor`), `sensor/freezeMonitor` (`createFreezeMonitor`), `session/roles` (`assignRoles`); `createRoundState`'s `RoundConfig.teams` accepts per-team roles and an optional `winCondition` that `evaluate()` checks each tick, and takes an optional `phaseOrder` for arbitrary named phase cycles (`concludeRound`/`evaluate` settle only while the current phase is neither the first nor the last entry) (#151).
+- Appearance replication — presence rows carry an optional per-slot appearance channel (cosmetic ids, hex tints, model keys) alongside pose, riding the existing pose message with no protocol bump; wire `ctx.player.cosmetics.get(userId)` into the outgoing pose (#151).
+- `ctx.input` — a per-frame held-action snapshot (`publish(held)`/`isDown(action)`/`held()`) without bumping `ctx.version()`; action bindings gained `repeatMs` (repeat-fire while held); every command resolved from a bound action now carries `aim`; `pointer.secondaryCommand` runs a command on right-click off the same raycast as move/ping (#164).
+- Object spatial queries + entity patching — `ctx.scene.object.at`/`inBox`/`raycast`/`raycastAll` over unit-box objects; `ctx.scene.entity.update(id, patch)` for name/position/rotation/role/movement/behaviors/meta; per-instance `renderObject`/`objectStyles` overrides; `pointerService.worldHitCenter()` + pointer-lock center-ray aiming (#165).
+- Controller movement config — `PlayerMovementConfig` (`mode`: free/axis/grid, `axis`, `cellSize`, `collideObjects`, `beforeCommit` pre-commit hook) for the shell-driven walk controller; `defineGame.physics.gravity`/`jumpVelocity` are honored by the built-in walk controller (distinct from the standalone `physics/physicsWorld` rigid-body sim); `ctx.player.motion.impulse`/`setVerticalVelocity`/`setY`/`takePending` (`MotionIntents`); `entity.spawnPoseOf`/`resetToSpawn`/`resetAllToSpawn` (#162).
+- Model material/animation + paint — `ModelConfig.tint`/`metalness`/`roughness`/`animation` (GLTF clip playback, paused pose holds); `PointerHit.uv` + `pointerService.sampleSurface()` for material-aware picking; `ctx.scene.entity.paint` runtime paint layer, auto-rendered via a per-instance canvas texture with no per-game wiring; remote-player appearance tint recolors the shell's default capsule (#151).
+- **Transport pipe seam** (`@jgengine/ws/pipe`) — `createWsBackend` runs over any bidirectional string channel, not just a raw `WebSocket`: `TransportPipe`/`TransportPipeHandlers`/`TransportPipeFactory`, with `webSocketPipe(url, webSocketFactory?)` as the default. `createWsBackend({ userId, url?, pipe? })` — `url` stays the common case, `pipe` opens the seam to socket.io, WebRTC, and in-process loopback below.
+- **Browser-safe authoritative host** — `createGameHost` and `memoryPersistence` moved from `@jgengine/node` to `@jgengine/ws/host` (zero Node dependencies; `@jgengine/node` re-exports both unchanged from `@jgengine/node/host` / `@jgengine/node/persistence`, so existing imports keep working). `@jgengine/ws/hostRouter`'s `createHostRouter({ host, authenticate?, poseRules?, positionHistoryMs?, chatRateLimit?, chatHistoryLimit?, chatMaxBodyLength?, now? })` extracts the ws wire-protocol session logic out of `createGameWsServer` into a transport-agnostic `HostRouter` (`connect(transport) → { handleRaw, close }`, `rewind`, `close`); `@jgengine/node`'s `createGameWsServer` is now a thin binding of this router onto the `ws` npm package, same public API. `loopbackPipe(router): TransportPipeFactory` connects a `createWsBackend` straight into an in-process router.
+- **Socket.IO transport** — `@jgengine/ws/socketIoPipe` (`SocketIoLikeSocket` structural type, `socketIoPipe(socket)`, `createSocketIoBackend({ socket, userId, … })`) and `@jgengine/node/socketIoServer` (`attachGameSocketIoServer({ io, host, …router options }): { rewind, close }`, structural `SocketIoLikeServer`/`SocketIoLikeServerSocket`) ride the existing ws JSON protocol over socket.io's `send`/`message` frames — no socket.io dependency in either package's types. New `socketIo({ topology?, url? })` adapter in `@jgengine/core/runtime/adapter`.
+- **WebRTC peer-to-peer** (`@jgengine/ws/peer`) — one browser tab hosts, authoritatively, with no server process. `createPeerHost({ userId, host?, runtimes?, persistence?, tickMs?, router?, rtc? })` runs a `GameHost` + `HostRouter` in the host tab (`backend` is the host player's own loopback connection, `accept(offerCode) → Promise<answerCode>` per guest); `createPeerGuest({ userId, token?, rtc? })` offers/connects from the joining side. `encodePeerSignal`/`decodePeerSignal` turn SDP into copy-pasteable base64url codes for manual cross-machine signaling; `broadcastChannelSignaling(room)` automates it for same-origin multi-tab play, with `announcePeerHost`/`joinPeerSession` wiring host/guest to a `PeerSignaling` in one call. New `p2p({ topology?, room? })` adapter (topology defaults `"private"`).
+- **LAN adapter + Fly sugar** — `lan({ topology?, port?, path? })` in `@jgengine/core/runtime/adapter` resolves through `@jgengine/shell/multiplayer`'s `resolveShellMultiplayer` to `ws(s)://<page hostname>:<port ?? 8080><path ?? /ws>` derived from `window.location`, so any browser on the LAN auto-connects to whichever machine served the page — no URL configuration. `fly({ app, topology?, path? })` is `ws` sugar for a Fly.io deploy: resolves to `wss://<app>.fly.dev<path ?? "/ws">`. `apps/dev`'s Vite server now listens on the network (`server: { host: true }`) and exposes `?p2p=host` / `?p2p=join` query params wired through the new `resolvePeerShellMultiplayer({ gameId, role, room?, userId?, feedActions? })`.
+- `ws()` (`@jgengine/core/runtime/adapter`) gained an optional `url` field, carried through by `resolveShellMultiplayer` (`args.url ?? adapter.url ?? default`).
+
+### Removed
+
+- **The `gameui` component kit** (`@jgengine/react/gameui`) — the themed HUD kit (bars, slots, feedback, meters, panels, screens, reticles, icons) and its `GameUiThemeProvider`/`useGameUiTheme` theming have been removed. **Breaking** for anyone importing `@jgengine/react/gameui` (or its subpaths/barrel). The components now ship as installable shadcn registry items at `https://jgengine.com/r/<name>.json` (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), styled with Tailwind + `--jg-*` CSS variables instead of a theme object. The icon catalog (`GameIcon`, `iconForAction`, `iconForItemId`, `isGameIconName`, `GameIconName`) moved to `@jgengine/react/gameIcons`. To theme, set the `--jg-*` variables on a wrapper element (the registry's `jg-theme` presets mirror the old `ember`/`synthwave`/`fieldkit` palettes) instead of wrapping in `GameUiThemeProvider`.
+
+### Docs
+
+- Added [CREDITS.md](CREDITS.md) crediting [achrefelouafi](https://github.com/achrefelouafi) for the MIT Three.js reference projects behind the procedural building, water, rain, and snow renderers, with links from the root, `@jgengine/core`, and `@jgengine/shell` READMEs.
+
 ## 0.7.0
 
 The engine-gaps release — 22 system-level additions across turn/tactics, cards & boards,

package/README.md

@@ -24,7 +24,32 @@ import { WeatherLayer, LightningStrike } from "@jgengine/shell/weather";
 <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.
+`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](https://github.com/achrefelouafi/RainSystemThreeJS) and [SnowSystemThreeJS](https://github.com/achrefelouafi/SnowSystemThreeJS) references (see [CREDITS.md](../../CREDITS.md)) without bringing over GUI, audio, postprocessing, or app-specific scene setup.
+
+## Water
+
+`@jgengine/shell/water` renders the Gerstner ocean surface from `@jgengine/core`:
+
+```tsx
+import { Ocean } from "@jgengine/shell/water";
+
+<Ocean />;
+```
+
+Summed Gerstner waves, crest-driven foam, and Fresnel water color were shaped from achrefelouafi's MIT [OceanThreejs](https://github.com/achrefelouafi/OceanThreejs) reference (see [CREDITS.md](../../CREDITS.md)).
+
+## Structures
+
+`GeneratedBuilding` renders the seeded facade/roof kit produced by `generateBuilding` in `@jgengine/core`:
+
+```tsx
+import { GeneratedBuilding } from "@jgengine/shell/structures/GeneratedBuilding";
+import { generateBuilding } from "@jgengine/core/world/buildings";
+
+<GeneratedBuilding building={generateBuilding({ seed: "block-a", floors: 6 })} />;
+```
+
+The component vocabulary (windows, awnings, AC units, clotheslines, storefronts, shutters, store signs, roof props, guardrails) and placement logic follow achrefelouafi's MIT [BuildingGeneratorThreeJS](https://github.com/achrefelouafi/BuildingGeneratorThreeJS) (see [CREDITS.md](../../CREDITS.md)).
 
 ## Terrain primitives
 

package/dist/GameHost.d.ts

@@ -0,0 +1,12 @@
+import { type ResolveShellMultiplayerArgs, type ShellMultiplayer } from "./multiplayer.js";
+import type { PlayableGame } from "./registry.js";
+export interface GameHostProps {
+    playable: PlayableGame;
+    gameId?: string;
+    wsUrl?: string;
+    /** Prebuilt multiplayer session. When present (including `null`), it is used as-is and no resolution is attempted. */
+    multiplayer?: ShellMultiplayer | null;
+    /** Tried before the built-in {@link resolveShellMultiplayer}; falls back to it when this returns `null`. */
+    resolveMultiplayer?: (args: ResolveShellMultiplayerArgs) => ShellMultiplayer | null;
+}
+export declare function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer }: GameHostProps): import("react").JSX.Element;

package/dist/GameHost.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { multiplayerAdapterKind } from "@jgengine/core/runtime/adapter";
+import { GamePlayerShell } from "./GamePlayerShell.js";
+import { resolveShellMultiplayer } from "./multiplayer.js";
+const warnedAdapterKinds = new Set();
+function warnUndrivenAdapter(kind) {
+    if (warnedAdapterKinds.has(kind))
+        return;
+    warnedAdapterKinds.add(kind);
+    console.warn(`GameHost: game declares multiplayer adapter "${kind}", which the built-in shell resolver cannot drive. ` +
+        "Running offline. Pass a prebuilt session via the multiplayer prop, or a resolveMultiplayer prop, to GameHost.");
+}
+export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer }) {
+    const resolved = useMemo(() => {
+        if (multiplayer !== undefined)
+            return multiplayer;
+        const args = {
+            game: playable.game,
+            gameId: gameId ?? playable.game.name,
+            url: wsUrl,
+            force: wsUrl !== undefined,
+        };
+        const session = resolveMultiplayer?.(args) ?? resolveShellMultiplayer(args);
+        if (session === null) {
+            const kind = multiplayerAdapterKind(playable.game.multiplayer);
+            if (kind !== null && kind !== "offline")
+                warnUndrivenAdapter(kind);
+        }
+        return session;
+    }, [playable, gameId, wsUrl, multiplayer, resolveMultiplayer]);
+    return _jsx(GamePlayerShell, { playable: playable, multiplayer: resolved });
+}

package/dist/GamePlayer.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from "react";
+import type { ShellMultiplayer } from "./multiplayer.js";
+import type { GameRegistry } from "./registry.js";
+export type GamePlayerProps = {
+    gameId: string;
+    registry: GameRegistry;
+    fallbackGameId?: string;
+    loading?: ReactNode;
+    multiplayer?: ShellMultiplayer | null;
+};
+export declare function GamePlayer({ gameId, registry, fallbackGameId, loading, multiplayer }: GamePlayerProps): import("react").JSX.Element;

package/dist/GamePlayer.js

@@ -0,0 +1,24 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { GamePlayerShell } from "./GamePlayerShell.js";
+import { resolveGameLoader } from "./registry.js";
+export function GamePlayer({ gameId, registry, fallbackGameId, loading = null, multiplayer = null }) {
+    const [playable, setPlayable] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        setPlayable(null);
+        const load = resolveGameLoader(registry, gameId, fallbackGameId);
+        if (load !== undefined) {
+            void load().then((game) => {
+                if (!cancelled)
+                    setPlayable(game);
+            });
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [gameId, fallbackGameId]);
+    if (playable === null)
+        return _jsx(_Fragment, { children: loading });
+    return _jsx(GamePlayerShell, { playable: playable, multiplayer: multiplayer });
+}

package/dist/GamePlayerShell.d.ts

@@ -1,6 +1,38 @@
+import { type ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { Aim } from "@jgengine/core/scene/spatial";
+import { type CollisionObstacle, type MovementTuningOverrides } from "@jgengine/core/movement/movementModel";
+import type { PhysicsConfig } from "@jgengine/core/game/defineGame";
+import { type GameContext } from "@jgengine/core/runtime/gameContext";
+import type { MotionIntentBatch } from "@jgengine/core/runtime/motionIntents";
+import type { SkyEnvironmentDescriptor, WorldFeature } from "@jgengine/core/world/features";
+import { type SceneObject } from "@jgengine/core/scene/objectStore";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
-export declare function GamePlayerShell({ playable, multiplayer, }: {
+/** Actions from `input` currently held down, for `ctx.input.publish` (#164.1); includes reserved movement/jump actions. */
+export declare function heldActionsFor(tracker: Pick<ActionStateTracker<string>, "isDown">, actions: readonly string[]): string[];
+/** Whether a bound action should fire this frame: on press, or on repeat interval while held (shared by `FrameDriver` and `HudOnlyDriver`). */
+export declare function shouldFireBoundAction(tracker: Pick<ActionStateTracker<string>, "isDown" | "wasPressed">, action: string, input: PlayableGame["game"]["input"], repeatFiredAt: ReadonlyMap<string, number>, now: number): boolean;
+/** Resolves and runs the command bound to `action` via the shell's action→command convention (shared by `FrameDriver` and `HudOnlyDriver`). */
+export declare function dispatchBoundAction(ctx: GameContext, action: string, yaw: number, pitch: number, aim: Aim): void;
+/** Placed scene objects within `radius` of `center`, as `CollisionObstacle`s for `resolveObstacleStep` (#162.1). */
+export declare function nearbyObstacles(objects: readonly SceneObject[], center: readonly [number, number, number], radius?: number): CollisionObstacle[];
+/** Applies a pending `MotionIntentBatch` to a vertical velocity: impulses add, then `verticalVelocity` replaces the result outright (#162.4). */
+export declare function applyMotionImpulses(currentVelocity: number, batch: MotionIntentBatch | null): number;
+/** The world's declared sky, when its world feature is an environment with one (#196.1). */
+export declare function resolveWorldSky(world: WorldFeature | undefined): SkyEnvironmentDescriptor | undefined;
+/**
+ * Maps the game's declared `physics` onto the movement controllers' tuning
+ * overrides. `PhysicsConfig.gravity` is a signed world acceleration (negative
+ * points down, matching every game's config and the Y-up convention), but the
+ * controllers integrate `velocityY -= gravityAcceleration * dt` and so expect a
+ * positive downward magnitude. Negating here is what keeps a down-pointing
+ * gravity pulling the player *down*; passing the signed value straight through
+ * flipped the sign and launched airborne players upward instead.
+ */
+export declare function resolvePhysicsTuning(physics: PhysicsConfig | undefined): MovementTuningOverrides | undefined;
+/** True when the world is an environment feature with terrain, so the voxel controller should sample its height. */
+export declare function hasEnvironmentTerrain(world: WorldFeature | undefined): boolean;
+export declare function GamePlayerShell({ playable, multiplayer: rawMultiplayer, }: {
     playable: PlayableGame;
     multiplayer?: ShellMultiplayer | null;
 }): import("react").JSX.Element;