@jgengine/ws 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/dist/createWsBackend.d.ts

@@ -2,9 +2,13 @@ import { type PoseSyncTuning } from "@jgengine/core/multiplayer/poseSyncGate";
 import type { GameBackend, JoinServerResult } from "@jgengine/core/runtime/transport";
 import type { SessionAttributes } from "@jgengine/core/runtime/hostPersistence";
 import type { MatchFilter, SessionListing } from "@jgengine/core/multiplayer/matchmaking";
-import { type WsPose, type WsPresenceRow } from "./protocol.js";
+import type { ChatSendOutcome, ChatSync } from "@jgengine/core/multiplayer/chatContract";
+import type { VoiceTransport } from "@jgengine/core/multiplayer/voiceContract";
+import { type WsChatMessage, type WsPose, type WsPresenceRow, type WsVoiceParticipant } from "./protocol.js";
+import { type TransportPipeFactory } from "./pipe.js";
 export type WsBackendOptions = {
-    url: string;
+    url?: string;
+    pipe?: TransportPipeFactory;
     userId: string;
     token?: string;
     webSocketFactory?: (url: string) => WebSocket;
@@ -14,8 +18,19 @@ export type WsBackendOptions = {
 };
 export type WsPresenceSync = {
     subscribe: (serverId: string, onChange: (rows: WsPresenceRow[]) => void) => () => void;
+    /** `pose.appearance`, when provided, is forwarded to the host as-is and surfaces on every subscriber's presence row for that user. */
     syncPose: (serverId: string, pose: WsPose) => void;
 };
+export type WsChatSync = {
+    subscribe: (serverId: string, channelId: string, onChange: (messages: WsChatMessage[]) => void) => () => void;
+    send: (serverId: string, channelId: string, body: string) => Promise<ChatSendOutcome>;
+};
+export type WsVoiceSync = {
+    subscribe: (serverId: string, channelId: string, onChange: (participants: WsVoiceParticipant[]) => void) => () => void;
+    join: (serverId: string, channelId: string, streamId?: string) => Promise<void>;
+    leave: (serverId: string, channelId: string) => Promise<void>;
+    publish: (serverId: string, channelId: string, streamId: string) => Promise<void>;
+};
 export type WsBackend = GameBackend & {
     pushFeedEntry: (args: {
         serverId: string;
@@ -36,6 +51,10 @@ export type WsBackend = GameBackend & {
         attributes?: SessionAttributes;
     }) => Promise<JoinServerResult>;
     presenceSync: WsPresenceSync;
+    chatSync: WsChatSync;
+    chatSyncFor: (serverId: string) => ChatSync;
+    voiceSync: WsVoiceSync;
+    voiceTransportFor: (serverId: string) => VoiceTransport;
     close: () => void;
 };
 export declare function createWsBackend(options: WsBackendOptions): WsBackend;

package/dist/createWsBackend.js

@@ -1,6 +1,6 @@
 import { createPoseSyncGate } from "@jgengine/core/multiplayer/poseSyncGate";
 import { decodeWsServerMessage, encodeWsMessage, subscriptionKey, } from "./protocol.js";
-const WS_READY_STATE_OPEN = 1;
+import { webSocketPipe } from "./pipe.js";
 const DEFAULT_POSE_TUNING = {
     minIntervalMs: 100,
     heartbeatMs: 5_000,
@@ -11,8 +11,15 @@ const DEFAULT_POSE_TUNING = {
 export function createWsBackend(options) {
     const now = options.now ?? Date.now;
     const reconnectDelayMs = options.reconnectDelayMs ?? 1_000;
-    const webSocketFactory = options.webSocketFactory ?? ((url) => new WebSocket(url));
-    let socket = null;
+    const pipeFactory = options.pipe ??
+        (() => {
+            const url = options.url;
+            if (url === undefined)
+                throw new Error("WsBackendOptions requires url or pipe");
+            return webSocketPipe(url, options.webSocketFactory);
+        })();
+    let pipe = null;
+    let open = false;
     let ready = null;
     let closed = false;
     let nextId = 1;
@@ -25,12 +32,12 @@ export function createWsBackend(options) {
         pending.clear();
     };
     const rawSend = (message) => {
-        if (socket === null || socket.readyState !== WS_READY_STATE_OPEN)
+        if (pipe === null || !open)
             return;
-        socket.send(encodeWsMessage(message));
+        pipe.send(encodeWsMessage(message));
     };
     const handleMessage = (raw) => {
-        const message = decodeWsServerMessage(typeof raw === "string" ? raw : String(raw));
+        const message = decodeWsServerMessage(raw);
         if (message === null)
             return;
         if (message.t === "reply") {
@@ -46,7 +53,9 @@ export function createWsBackend(options) {
             }
             return;
         }
-        const key = subscriptionKey(message.channel, message.serverId, message.channel === "feed" ? message.action : undefined);
+        const key = subscriptionKey(message.channel, message.serverId, message.channel === "feed" || message.channel === "chat" || message.channel === "voice"
+            ? message.action
+            : undefined);
         const subscription = subscriptions.get(key);
         if (subscription === undefined)
             return;
@@ -62,41 +71,43 @@ export function createWsBackend(options) {
         if (ready !== null)
             return ready;
         ready = new Promise((resolve, reject) => {
-            const nextSocket = webSocketFactory(options.url);
-            socket = nextSocket;
-            nextSocket.onopen = () => {
-                const id = nextId++;
-                pending.set(id, {
-                    resolve: () => {
-                        for (const subscription of subscriptions.values()) {
-                            rawSend({
-                                v: 1,
-                                t: "subscribe",
-                                id: nextId++,
-                                channel: subscription.channel,
-                                serverId: subscription.serverId,
-                                action: subscription.action,
-                            });
-                        }
-                        resolve();
-                    },
-                    reject,
-                });
-                nextSocket.send(encodeWsMessage({ v: 1, t: "hello", id, userId: options.userId, token: options.token }));
-            };
-            nextSocket.onmessage = (event) => handleMessage(event.data);
-            nextSocket.onclose = () => {
-                failPending("Connection closed");
-                socket = null;
-                ready = null;
-                reject(new Error("Connection closed"));
-                if (!closed && subscriptions.size > 0) {
-                    setTimeout(() => {
-                        if (!closed)
-                            void connect().catch(() => undefined);
-                    }, reconnectDelayMs);
-                }
-            };
+            pipe = pipeFactory({
+                onOpen: () => {
+                    open = true;
+                    const id = nextId++;
+                    pending.set(id, {
+                        resolve: () => {
+                            for (const subscription of subscriptions.values()) {
+                                rawSend({
+                                    v: 1,
+                                    t: "subscribe",
+                                    id: nextId++,
+                                    channel: subscription.channel,
+                                    serverId: subscription.serverId,
+                                    action: subscription.action,
+                                });
+                            }
+                            resolve();
+                        },
+                        reject,
+                    });
+                    rawSend({ v: 1, t: "hello", id, userId: options.userId, token: options.token });
+                },
+                onMessage: handleMessage,
+                onClose: () => {
+                    open = false;
+                    failPending("Connection closed");
+                    pipe = null;
+                    ready = null;
+                    reject(new Error("Connection closed"));
+                    if (!closed && subscriptions.size > 0) {
+                        setTimeout(() => {
+                            if (!closed)
+                                void connect().catch(() => undefined);
+                        }, reconnectDelayMs);
+                    }
+                },
+            });
         });
         return ready;
     };
@@ -120,6 +131,7 @@ export function createWsBackend(options) {
             return result;
         },
         async leaveServer(args) {
+            poseGates.delete(args.serverId);
             await request((id) => ({ v: 1, t: "leave", id, serverId: args.serverId }));
         },
         async runCommand(args) {
@@ -191,10 +203,50 @@ export function createWsBackend(options) {
                 .catch(() => undefined);
         },
     };
+    const chatSync = {
+        subscribe(serverId, channelId, onChange) {
+            return addSubscription("chat", serverId, channelId, (data) => onChange(data));
+        },
+        async send(serverId, channelId, body) {
+            try {
+                await request((id) => ({ v: 1, t: "chatSend", id, serverId, channelId, body }));
+                return { ok: true };
+            }
+            catch (error) {
+                return { ok: false, reason: error instanceof Error ? error.message : "Transport error" };
+            }
+        },
+    };
+    const voiceSync = {
+        subscribe(serverId, channelId, onChange) {
+            return addSubscription("voice", serverId, channelId, (data) => onChange(data));
+        },
+        async join(serverId, channelId, streamId) {
+            await request((id) => ({ v: 1, t: "voiceJoin", id, serverId, channelId, streamId }));
+        },
+        async leave(serverId, channelId) {
+            await request((id) => ({ v: 1, t: "voiceLeave", id, serverId, channelId }));
+        },
+        async publish(serverId, channelId, streamId) {
+            await request((id) => ({ v: 1, t: "voicePublish", id, serverId, channelId, streamId }));
+        },
+    };
     return {
         transport,
         feeds,
         presenceSync,
+        chatSync,
+        chatSyncFor: (serverId) => ({
+            subscribe: (channelId, onChange) => chatSync.subscribe(serverId, channelId, onChange),
+            send: (channelId, body) => chatSync.send(serverId, channelId, body),
+        }),
+        voiceSync,
+        voiceTransportFor: (serverId) => ({
+            join: (channelId, streamId) => voiceSync.join(serverId, channelId, streamId),
+            leave: (channelId) => voiceSync.leave(serverId, channelId),
+            publish: (channelId, streamId) => voiceSync.publish(serverId, channelId, streamId),
+            subscribers: (channelId, onChange) => voiceSync.subscribe(serverId, channelId, onChange),
+        }),
         async pushFeedEntry(args) {
             await request((id) => ({
                 v: 1,
@@ -239,8 +291,9 @@ export function createWsBackend(options) {
         close: () => {
             closed = true;
             failPending("Backend closed");
-            socket?.close();
-            socket = null;
+            pipe?.close();
+            pipe = null;
+            open = false;
             ready = null;
         },
     };

package/dist/host.d.ts

@@ -0,0 +1,85 @@
+import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
+import type { HostPersistence, ServerListing, SessionAttributes } from "@jgengine/core/runtime/hostPersistence";
+import type { MatchFilter, SessionListing } from "@jgengine/core/multiplayer/matchmaking";
+import type { GameRuntimePlayerView, GameRuntimeServerView, JoinServerResult, TransportRunCommandResult } from "@jgengine/core/runtime/transport";
+export type HostChangeEvent = {
+    type: "server";
+    serverId: string;
+} | {
+    type: "player";
+    serverId: string;
+    userId: string;
+} | {
+    type: "feed";
+    serverId: string;
+    action: string;
+};
+export type GameHostOptions = {
+    runtimes?: GameRuntime[];
+    persistence: HostPersistence;
+    tickMs?: number;
+    slotsPerServer?: number;
+    now?: () => number;
+    createServerId?: () => string;
+};
+export type GameHost = {
+    joinServer: (args: {
+        userId: string;
+        gameId: string;
+        serverId?: string;
+        attributes?: SessionAttributes;
+    }) => Promise<JoinServerResult>;
+    browseServers: (args: {
+        gameId: string;
+        filter?: MatchFilter;
+        limit?: number;
+    }) => Promise<SessionListing[]>;
+    joinByCode: (args: {
+        userId: string;
+        gameId: string;
+        code: string;
+    }) => Promise<JoinServerResult | null>;
+    leaveServer: (args: {
+        userId: string;
+        serverId: string;
+    }) => Promise<void>;
+    runCommand: (args: {
+        userId: string;
+        serverId: string;
+        command: string;
+        input: unknown;
+    }) => Promise<TransportRunCommandResult>;
+    getServerView: (args: {
+        userId: string;
+        serverId: string;
+    }) => Promise<GameRuntimeServerView | null>;
+    getPlayerView: (args: {
+        userId: string;
+        serverId: string;
+    }) => Promise<GameRuntimePlayerView | null>;
+    getFeed: (args: {
+        userId: string;
+        serverId: string;
+        action: string;
+    }) => Promise<unknown[]>;
+    pushFeedEntry: (args: {
+        userId: string;
+        serverId: string;
+        action: string;
+        entry: unknown;
+    }) => Promise<void>;
+    listOpenServers: (args: {
+        gameId: string;
+        limit?: number;
+    }) => Promise<ServerListing[]>;
+    tickOnce: () => Promise<{
+        ticked: number;
+        saved: number;
+    }>;
+    flushAll: () => Promise<number>;
+    start: () => void;
+    stop: () => Promise<void>;
+    subscribe: (listener: (event: HostChangeEvent) => void) => () => void;
+};
+export declare function createGameHost(options: GameHostOptions): GameHost;
+export declare function memoryPersistence(now?: () => number): HostPersistence;