use-colyseus

useColyseus Hooks 🎣 🏟️

This package contains a set of utility hooks to use Colyseus with React.

Colyseus is a framework for writing your own authoritative multiplayer game servers using JavaScript/TypeScript and Node.js, and easily integrating it with your favorite game engine.

This package still needs to be battle-tested for production, but it gives a good glimpse of how Colyseus and React work together and how to handle external states on React.

Usage

1. Install the package

   pnpm add use-colyseus

2. Create a colyseus.ts file on your React app

   import { colyseus } from "use-colyseus";
   
   import { GameState } from "shared/schema"; // Your room schema
   
   export const {
     client,
     connectToColyseus,
     disconnectFromColyseus,
     useColyseusRoom,
     useColyseusState,
   } = colyseus<GameState>('ws://localhost:2567');

3. Import the hooks from your newly created colyseus.ts file and start building :)

Documentation

• colyseus

  Setup the Colyseus client and type the utility hooks.

  Parameters:

  • endpoint: string
  • schema?: Schema

  Return:

  • Client
  • connectToColyseus
  • disconnectFromColyseus
  • useColyseusRoom
  • useColyseusState

  Example:

  export const {
      client,
      connectToColyseus,
      disconnectFromColyseus,
      useColyseusRoom,
      useColyseusState,
    } = colyseus<GameState>('ws://localhost:2567');

• connectToColyseus

  Connect the client to the specified Colyseus server room. Prevents duplicated connections.

  Parameters:

  • roomName: string
  • options?: unknown

  Return:

  Promise<void>

  Example:

  useEffect(() => {
    (async () => {
      await connectToColyseus("test");
    })();
  
    return () => {
      disconnectFromColyseus();
    };
  }, []);

• disconnectFromColyseus

  Disconnect the client from the current connected Colyseus server

  Parameters:

  Return:

  Promise<void>

  Example:

  useEffect(() => {
    (async () => {
      await connectToColyseus("test");
    })();
  
    return () => {
      disconnectFromColyseus();
    };
  }, []);

• useColyseusRoom

  Access the Colyseus room object. Shouldn't be used to access the state, room.state is not updated. Use useColyseusState instead.

  Parameters:

  Return:

  Room

  Example:

  const room = useColyseusRoom();
  if (!room) return null;
  
  console.log(room.sessionId);

  • useColyseusState

  Access the Colyseus room state. Returns the complete state object updated in real-time. Use a selector to prevent re-renderings.

  Parameters:

  • selector?: (state: S) => unknown

  Return:

  Room

  Example:

  const clients = useColyseusState((state) => state.clients); // Only re-render if `state.clients` has changed
  
  // or
  
  const state = useColyseusState(); // Causes a lot of re-renderings

Acknowledgements

• Endel Dreyer: Creating such a powerful and easy to use network framework.
• Douglas Delavy: Partnership during the development of this package.

---

Get in touch 👋