Skip to content

Getting Started

Quick guide to get Signal Fish Server running and connect your first client.

Installation

Using Rust

Bash
cargo run

The server starts on port 3536 by default.

Using Docker

Bash
docker run -p 3536:3536 ghcr.io/ambiguous-interactive/signal-fish-server:latest

Using Docker Compose

Bash
docker compose up

First Connection

Connect your WebSocket client to:

Text Only
ws://localhost:3536/v2/ws

A ws://localhost:3536/v3/ws endpoint is also available. Protocol v3 is purely additive over v2 (this v2 flow works unchanged) and adds optional capability negotiation — see the Protocol Reference for details.

Basic Client Flow

Here's a minimal example showing a complete session:

JavaScript
const ws = new WebSocket('ws://localhost:3536/v2/ws');

ws.onopen = () => {
  // Create a room by joining without a room code
  ws.send(JSON.stringify({
    type: 'JoinRoom',
    data: {
      game_name: 'my-game',
      player_name: 'Player1',
      max_players: 4
    }
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.type === 'RoomJoined') {
    console.log('Room code:', message.data.room_code);
    // Share this code with other players
  }

  if (message.type === 'PlayerJoined') {
    console.log('Player joined:', message.data.player.name);
  }

  if (message.type === 'GameData') {
    console.log('Received game data:', message.data.data);
  }
};

Joining an Existing Room

JavaScript
ws.send(JSON.stringify({
  type: 'JoinRoom',
  data: {
    game_name: 'my-game',
    room_code: 'ABC123',
    player_name: 'Player2'
  }
}));

Sending Game Data

JavaScript
ws.send(JSON.stringify({
  type: 'GameData',
  data: {
    // The outer `data` is the serde content tag; the inner `data`
    // is the GameData variant's field name.
    data: {
      action: 'move',
      x: 100,
      y: 200
    }
  }
}));

Health Check

Verify the server is running:

Bash
curl http://localhost:3536/v2/health

Next Steps