useRoomMessage(), useLobbyRoom(), useQueueRoom(), createLobbyContext(). closes #7

Author: endel

README.md

@@ -83,6 +83,108 @@ const players = useRoomState(room, (state) => state.players);
 
 Only components that read `players` will re-render when the players map changes.
 
+### `useRoomMessage(room, type, callback)`
+
+Subscribes to Colyseus room messages. The callback is kept in a ref so it is always up-to-date without re-subscribing. Automatically unsubscribes when the room changes or the component unmounts.
+
+```tsx
+import { useRoom, useRoomMessage } from "@colyseus/react";
+
+function Chat() {
+  const { room } = useRoom(() => client.joinOrCreate("game_room"));
+  const [messages, setMessages] = useState<string[]>([]);
+
+  useRoomMessage(room, "chat", (message) => {
+    setMessages((prev) => [...prev, message]);
+  });
+
+  return (
+    <ul>
+      {messages.map((msg, i) => <li key={i}>{msg}</li>)}
+    </ul>
+  );
+}
+```
+
+Pass `"*"` as the type to listen to all message types.
+
+### `useLobbyRoom(callback, deps?)`
+
+Connects to a Colyseus [Lobby Room](https://docs.colyseus.io/builtin-rooms/lobby/) and provides a live-updating list of available rooms. The list is automatically maintained as rooms are created, updated, and removed.
+
+```tsx
+import { Client } from "@colyseus/sdk";
+import { useLobbyRoom } from "@colyseus/react";
+
+const client = new Client("ws://localhost:2567");
+
+function Lobby() {
+  const { rooms, error, isConnecting } = useLobbyRoom(
+    () => client.joinOrCreate("lobby"),
+  );
+
+  if (isConnecting) return <p>Connecting...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <ul>
+      {rooms.map((room) => (
+        <li key={room.roomId}>
+          {room.name} — {room.clients}/{room.maxClients} players
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**Return value:**
+
+| Field | Type | Description |
+|---|---|---|
+| `rooms` | `RoomAvailable<Metadata>[]` | Live list of available rooms |
+| `room` | `Room \| undefined` | The underlying lobby room connection |
+| `error` | `Error \| undefined` | Connection error, if any |
+| `isConnecting` | `boolean` | `true` while connecting to the lobby |
+
+### `useQueueRoom(connect, consume, deps?)`
+
+Manages the full lifecycle of a Colyseus matchmaking queue: connecting to the queue room, tracking group size, receiving a seat reservation, confirming, and consuming the seat to join the match room. Cleans up both rooms on unmount.
+
+```tsx
+import { Client } from "@colyseus/sdk";
+import { useQueueRoom } from "@colyseus/react";
+
+const client = new Client("ws://localhost:2567");
+
+function Matchmaking() {
+  const { room, clients, isWaiting, error } = useQueueRoom(
+    () => client.joinOrCreate("queue", { rank: 1200 }),
+    (reservation) => client.consumeSeatReservation(reservation),
+  );
+
+  if (error) return <p>Error: {error.message}</p>;
+  if (room) return <GameScreen room={room} />;
+  if (isWaiting) return <p>Waiting for match... {clients} players in group</p>;
+  return <p>Connecting...</p>;
+}
+```
+
+The first argument connects to the queue room. The second argument is called with the `SeatReservation` once a match is found — use `client.consumeSeatReservation()` to join the match room.
+
+**Return value:**
+
+| Field | Type | Description |
+|---|---|---|
+| `room` | `Room \| undefined` | The match room, once the seat has been consumed |
+| `queue` | `Room \| undefined` | The queue room while waiting (undefined after match is joined) |
+| `clients` | `number` | Number of clients in the current matchmaking group |
+| `seat` | `SeatReservation \| undefined` | The seat reservation, once received |
+| `error` | `Error \| undefined` | Connection or matchmaking error |
+| `isWaiting` | `boolean` | `true` while connected to the queue and waiting for a match |
+
+## Contexts
+
 ### `createRoomContext()`
 
 Creates a set of hooks and a `RoomProvider` component that share a single room connection across React reconciler boundaries (e.g. DOM + React Three Fiber). The room is stored in a closure-scoped external store rather than React Context, so the hooks work in any reconciler tree that imports them.
@@ -129,6 +231,62 @@ function UI() {
 
 The returned `useRoom()` and `useRoomState(selector?)` work identically to the standalone hooks but don't require you to pass the room as an argument.
 
+### `createLobbyContext()`
+
+Creates a `LobbyProvider` and `useLobby` hook for sharing lobby room data globally across your app — useful when you need room metadata available persistently alongside an active game room, not just on a lobby screen. Like `createRoomContext`, it uses a closure-scoped external store so the hook works across reconciler boundaries.
+
+```tsx
+import { Client } from "@colyseus/sdk";
+import { createLobbyContext, createRoomContext } from "@colyseus/react";
+
+const client = new Client("ws://localhost:2567");
+
+const { LobbyProvider, useLobby } = createLobbyContext<MyMetadata>();
+const { RoomProvider, useRoom, useRoomState } = createRoomContext();
+```
+
+**Wrap your app with `LobbyProvider` (can nest with `RoomProvider`):**
+
+```tsx
+function App() {
+  return (
+    <LobbyProvider connect={() => client.joinLobby()}>
+      <RoomProvider connect={() => client.joinOrCreate("game_room")}>
+        <UI />
+        <Canvas>
+          <GameScene />
+        </Canvas>
+      </RoomProvider>
+    </LobbyProvider>
+  );
+}
+```
+
+`LobbyProvider` accepts a `connect` callback (same as `useLobbyRoom`) and an optional `deps` array. The lobby connection persists independently of the game room.
+
+**Access lobby data from any component — even deep inside the game:**
+
+```tsx
+function RoomBrowser() {
+  const { rooms, error, isConnecting } = useLobby();
+
+  if (isConnecting) return <p>Loading rooms...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <ul>
+      {rooms.map((room) => (
+        <li key={room.roomId}>
+          {room.metadata.displayName} — {room.clients}/{room.maxClients}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+The returned `useLobby()` hook provides the same fields as `useLobbyRoom` (`rooms`, `room`, `error`, `isConnecting`).
+
 ## Credits
 
 Inspiration and previous work by [@pedr0fontoura](https://github.com/pedr0fontoura) — [use-colyseus](https://github.com/pedr0fontoura/use-colyseus/).

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/react",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "type": "module",
   "scripts": {
     "dev": "tsdown --watch --format esm,cjs",

src/context/createLobbyContext.ts

@@ -0,0 +1,86 @@
+import { useSyncExternalStore, useEffect, type ReactNode, type DependencyList } from "react";
+import { Room } from "@colyseus/sdk";
+import { useLobbyRoom as useLobbyRoomOriginal, type UseLobbyRoomResult } from "../room/useLobbyRoom";
+
+interface LobbyProviderProps {
+  connect: (() => Promise<Room>) | null | undefined | false;
+  deps?: DependencyList;
+  children: ReactNode;
+}
+
+/**
+ * Creates a LobbyProvider and useLobby hook for sharing lobby room data
+ * (available rooms + metadata) globally across your app.
+ *
+ * Uses a closure-scoped external store (not React Context), so the hook
+ * works in any reconciler tree that imports it.
+ *
+ * This is useful when you need lobby metadata available persistently
+ * alongside an active game room — not just on a lobby screen.
+ *
+ * @template Metadata - The type of room metadata
+ *
+ * @example
+ * ```tsx
+ * const { LobbyProvider, useLobby } = createLobbyContext<MyMetadata>();
+ *
+ * // Wrap your app (can nest with RoomProvider)
+ * <LobbyProvider connect={() => client.joinLobby()}>
+ *   <RoomProvider connect={() => client.joinOrCreate("game")}>
+ *     <App />
+ *   </RoomProvider>
+ * </LobbyProvider>
+ *
+ * // In any component:
+ * const { rooms } = useLobby();
+ * rooms.map(r => r.metadata.displayName)
+ * ```
+ */
+export function createLobbyContext<Metadata = any>() {
+  let snapshot: UseLobbyRoomResult<Metadata> = {
+    rooms: [],
+    room: undefined,
+    error: undefined,
+    isConnecting: true,
+  };
+  const listeners = new Set<() => void>();
+
+  function subscribe(listener: () => void) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  function getSnapshot(): UseLobbyRoomResult<Metadata> {
+    return snapshot;
+  }
+
+  function setSnapshot(next: UseLobbyRoomResult<Metadata>) {
+    snapshot = next;
+    for (const listener of listeners) listener();
+  }
+
+  /**
+   * Manages the lobby room lifecycle. Render once near the root of your app.
+   * Lobby state is shared via the closure-scoped external store, not React Context.
+   */
+  function LobbyProvider({ connect, deps = [], children }: LobbyProviderProps) {
+    const { rooms, room, error, isConnecting } = useLobbyRoomOriginal<Metadata>(connect, deps);
+
+    useEffect(() => {
+      setSnapshot({ rooms, room, error, isConnecting });
+    }, [rooms, room, error, isConnecting]);
+
+    return children;
+  }
+
+  /**
+   * Returns the list of available rooms, the lobby room instance,
+   * error, and connection status.
+   * Works in DOM tree, R3F tree, or any other reconciler tree.
+   */
+  function useLobby(): UseLobbyRoomResult<Metadata> {
+    return useSyncExternalStore(subscribe, getSnapshot);
+  }
+
+  return { LobbyProvider, useLobby };
+}

src/createRoomContext.ts src/context/createRoomContext.tssrc/createRoomContext.ts renamed to src/context/createRoomContext.ts

@@ -1,9 +1,10 @@
 import { useSyncExternalStore, useEffect, type ReactNode, type DependencyList } from "react";
 import { Schema } from "@colyseus/schema";
 import { Room } from "@colyseus/sdk";
-import { useRoom as useRoomLifecycle, type UseRoomResult } from "./useRoom";
-import { useRoomState as useRoomStateOriginal } from "./schema/useRoomState";
-import type { Snapshot } from "./schema/createSnapshot";
+import { useRoom as useRoomLifecycle, type UseRoomResult } from "../room/useRoom";
+import { useRoomState as useRoomStateOriginal } from "../schema/useRoomState";
+import { useRoomMessage as useRoomMessageStandalone } from "../room/useRoomMessage";
+import type { Snapshot } from "../schema/createSnapshot";
 
 interface RoomProviderProps<T, State> {
   connect: (() => Promise<Room<T, State>>) | null | undefined | false;
@@ -88,5 +89,17 @@ export function createRoomContext<T = any, State extends Schema = Schema>() {
     return useRoomStateOriginal(room, selector);
   }
 
-  return { RoomProvider, useRoom, useRoomState };
+  /**
+   * Subscribes to room messages without needing to pass the room.
+   * The room is resolved from the store automatically.
+   */
+  function useRoomMessage(
+    type: string | number | "*",
+    callback: (...args: any[]) => void
+  ): void {
+    const { room } = useSyncExternalStore(subscribe, getSnapshot);
+    useRoomMessageStandalone(room, type, callback);
+  }
+
+  return { RoomProvider, useRoom, useRoomState, useRoomMessage };
 }

src/index.ts

@@ -1,5 +1,11 @@
 export { useRoomState } from './schema/useRoomState';
-export { useRoom } from './useRoom';
-export { createRoomContext } from './createRoomContext';
-export type { UseRoomResult } from './useRoom';
+export { useRoom } from './room/useRoom';
+export { useRoomMessage } from './room/useRoomMessage';
+export { createRoomContext } from './context/createRoomContext';
+export { createLobbyContext } from './context/createLobbyContext';
+export { useLobbyRoom } from './room/useLobbyRoom';
+export { useQueueRoom } from './room/useQueueRoom';
+export type { UseRoomResult } from './room/useRoom';
+export type { UseLobbyRoomResult } from './room/useLobbyRoom';
+export type { UseQueueRoomResult } from './room/useQueueRoom';
 export type { Snapshot } from './schema/createSnapshot';

src/room/useLobbyRoom.ts

@@ -0,0 +1,53 @@
+import { Room, type RoomAvailable } from "@colyseus/sdk";
+import { useState, useEffect, type DependencyList } from "react";
+import { useRoom } from "./useRoom";
+
+export interface UseLobbyRoomResult<Metadata = any> {
+  rooms: RoomAvailable<Metadata>[];
+  room: Room | undefined;
+  error: Error | undefined;
+  isConnecting: boolean;
+}
+
+export function useLobbyRoom<Metadata = any>(
+  callback: (() => Promise<Room>) | null | undefined | false,
+  deps: DependencyList = []
+): UseLobbyRoomResult<Metadata> {
+  const { room, error, isConnecting } = useRoom(callback, deps);
+  const [rooms, setRooms] = useState<RoomAvailable<Metadata>[]>([]);
+
+  useEffect(() => {
+    if (!room) {
+      setRooms([]);
+      return;
+    }
+
+    const unsubs: (() => void)[] = [];
+
+    unsubs.push(room.onMessage("rooms", (roomList: RoomAvailable<Metadata>[]) => {
+      setRooms(roomList);
+    }));
+
+    unsubs.push(room.onMessage("+", ([roomId, roomData]: [string, RoomAvailable<Metadata>]) => {
+      setRooms(prev => {
+        const index = prev.findIndex(r => r.roomId === roomId);
+        if (index !== -1) {
+          const next = [...prev];
+          next[index] = roomData;
+          return next;
+        }
+        return [...prev, roomData];
+      });
+    }));
+
+    unsubs.push(room.onMessage("-", (roomId: string) => {
+      setRooms(prev => prev.filter(r => r.roomId !== roomId));
+    }));
+
+    return () => {
+      unsubs.forEach(unsub => unsub());
+    };
+  }, [room]);
+
+  return { rooms, room, error, isConnecting };
+}