GameSync Explorer

Developer Preview

Game Networking API Documentation

Everything you need to integrate real-time multiplayer functionality into your game

Explore API Quick Start

API Endpoints

Core RESTful endpoints for game management and player interactions

POST

/api/game/initialize

AUTH REQUIRED

Initializes a new game session and returns connection parameters.

Request Body:

{
    "game_id": "string",       // Unique game identifier
    "version": "string",       // Game version
    "mode": "string",          // Game mode (e.g., "competitive", "coop")
    "max_players": number,     // Maximum players in session
    "region": "string"         // Preferred server region
}

Response:

{
    "session_id": "string",    // Unique session identifier
    "websocket_url": "string", // WebSocket connection URL
    "auth_token": "string",    // Temporary auth token for WebSocket
    "expires_in": number,      // Token validity in seconds
    "server": "string"         // Assigned game server
}
GET

/api/game/:session_id/players

AUTH REQUIRED

Retrieves all players in the current game session.

Response:

{
    "players": [
        {
            "player_id": "string",
            "username": "string",
            "avatar": "string",
            "ready": boolean,
            "ping": number,
            "team": "string",
            "is_host": boolean
        }
    ],
    "count": number
}

WebSocket Protocol

Real-time communication between game clients and server

Connection Flow

  1. 1

    Establish WebSocket Connection

    Connect to the provided websocket_url with the auth_token

    const socket = new WebSocket('wss://gameserver.example.com/session/abc123?token=xyz456');
  2. 2

    Send Initialization Message

    Send player metadata immediately after connection

    socket.send(JSON.stringify({
    "type": "player_init",
    "data": {
        "player_id": "player123",
        "username": "GameMaster",
        "character": "warrior",
        "loadout": {...}
    }
}));
  3. 3

    Receive Game State

    Server will send initial game state and subsequent updates

Client → Server Messages

Player Input

{
    "type": "player_input",
    "data": {
        "sequence": 123,      // Incrementing sequence number
        "inputs": {           // Game-specific input state
            "move_x": 0.5,
            "move_y": -0.2,
            "buttons": {
                "jump": true,
                "attack": false
            }
        },
        "timestamp": 123456789 // Client timestamp
    }
}

Ready State

{
    "type": "player_ready",
    "data": {
        "ready": true
    }
}

Server → Client Messages

Game State Update

{
    "type": "game_state",
    "data": {
        "players": {
            "player123": {
                "position": [x, y, z],
                "health": 100,
                "state": "moving"
            }
        },
        "world": {
            "time": 120,
            "events": [...]
        },
        "server_time": 123456790
    }
}

Player Joined

{
    "type": "player_joined",
    "data": {
        "player_id": "newplayer456",
        "username": "Newbie",
        "team": "blue"
    }
}

Authentication Requirements

Secure your game sessions with proper authentication

API Authentication

All REST API endpoints require an Authorization header with a valid JWT token.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens can be obtained through your platform's OAuth2 flow or via the authentication API.

WebSocket Authentication

WebSocket connections require:

  • Temporary session token (provided in game initialization)
  • Valid player ID (must match token claims)
  • Connection within token expiration window (typically 30 seconds)
wss://gameserver.example.com/session/abc123?
    token=xyz456&
    player_id=player123

Session Management

Maintaining and monitoring game sessions

Heartbeat Mechanism

Clients must send periodic heartbeat messages to maintain the connection.

Client Heartbeat

{
    "type": "heartbeat",
    "data": {
        "timestamp": 123456789,
        "sequence": 42
    }
}

Server Response

{
    "type": "heartbeat_ack",
    "data": {
        "server_time": 123456790,
        "latency": 42
    }
}

Session Timeouts

Event Timeout Action
No heartbeat received 10 seconds Player marked as disconnected
No reconnection 30 seconds Player removed from session
No active players 5 minutes Session terminated