@crew-games/dev-server

Local development server for testing Crew Games multiplayer games without deploying to the platform.

Why You Need This

When developing multiplayer games locally, you can't just open multiple browser tabs and expect them to communicate. You need a backend to broker messages and sync state between players - that's what LiveKit does in production, and what this dev server does locally.

Features

• ✅ WebSocket Message Broker - Syncs game state and messages between multiple browser tabs
• ✅ Mock Player Data - Simulates authenticated users with names, avatars, emails
• ✅ Session Management - Create isolated game sessions for testing
• ✅ Platform API Simulation - Mocks the same interface games use in production
• ✅ Zero Configuration - Works out of the box with sensible defaults

Installation

npm install --save-dev @crew-games/dev-server

Quick Start

1. Start the dev server:

npx crew-games-dev

This starts:

• HTTP API on http://localhost:3030
• WebSocket server on ws://localhost:3031

2. Open your game in multiple tabs:

http://localhost:5173?session=test&player=player-1
http://localhost:5173?session=test&player=player-2
http://localhost:5173?session=test&player=player-3

Each tab represents a different player in the same game session. The SDK automatically detects dev mode from the URL parameters.

How It Works

In Production

Your game → iframe → postMessage → Platform → LiveKit → Other players

In Development

Your game → WebSocket → Dev Server → WebSocket → Other tabs

The SDK automatically uses WebSocket when it detects ?session=X&player=Y in the URL, otherwise it uses postMessage for production.

Mock Players

The dev server provides 4 mock players by default:

• player-1: Alice Developer ([email protected])
• player-2: Bob Tester ([email protected])
• player-3: Carol QA ([email protected])
• player-4: Dave Engineer ([email protected])

Each player has a unique avatar from DiceBear API.

CLI Options

crew-games-dev [options]

Options:
  -p, --port <port>       HTTP server port (default: 3030)
  -w, --ws-port <port>    WebSocket server port (default: 3031)
  -q, --quiet             Suppress verbose logging
  -h, --help              Show help

Programmatic Usage

import { CrewGamesDevServer } from '@crew-games/dev-server';

const server = new CrewGamesDevServer({
  port: 8080,
  wsPort: 8081,
  verbose: true,
  mockPlayers: [
    {
      id: 'custom-1',
      name: 'Custom Player',
      email: '[email protected]',
      avatar: 'https://...',
    },
  ],
});

await server.start();

// Later...
await server.stop();

Testing Workflow

1. Terminal 1 - Start Dev Server

npx crew-games-dev

2. Terminal 2 - Start Your Game Dev Server

cd my-game
npx vite

3. Browser - Open Multiple Tabs

Tab 1 (Player 1 - Host):

http://localhost:5173?session=game1&player=player-1

Tab 2 (Player 2):

http://localhost:5173?session=game1&player=player-2

Tab 3 (Player 3):

http://localhost:5173?session=game1&player=player-3

Now when Player 1 updates game state, Players 2 and 3 see it instantly!

What Gets Mocked

✅ Game State Synchronization

// In any tab
await this.setState({ round: 2, score: 100 });

// All other tabs receive the update automatically

✅ Player Messaging

// Broadcast to all players
await this.broadcast({ type: 'gameStart' });

// Send to specific player
await this.sendTo('player-2', { type: 'yourTurn' });

✅ Player Information

// Access player data
this.players.forEach(player => {
  console.log(player.name, player.avatar);
});

// Check current player
console.log(this.currentPlayer.name); // "Alice Developer"

✅ Chat Messages

await this.sendChat('Hello everyone!');

API Endpoints

GET /health

Health check and session count

GET /api/player/:playerId

Get mock player profile data

GET /api/mock-players

List all available mock players

POST /api/session/join

Create or join a game session

Debugging

Enable debug mode in your game:

const game = new MyGame({ debug: true });

Or via URL parameter:

http://localhost:5173?session=test&player=player-1&debug=true

This shows detailed logs of all messages and state changes.

Troubleshooting

Problem: Tabs don't see each other's updates

Solution: Make sure all tabs use the same session parameter

Problem: "Failed to connect to dev server"

Solution: Ensure crew-games-dev is running before opening game tabs

Problem: Player data is undefined

Solution: Check that the player parameter matches one of the mock player IDs

Production vs Development

The SDK automatically switches modes:

| Mode | Detection | Communication | |------|-----------|---------------| | Production | No query params | postMessage to parent iframe | | Development | ?session=X&player=Y | WebSocket to dev server |

Your game code stays the same - no conditional logic needed!

License

MIT