Game Server

Your game server handles real-time communication, state management, and action validation. This guide explains how to set up a WebSocket server that integrates with Games.fun.

Server Setup

First, install required packages:

npm install ws @games-fun/server-sdk

Basic server setup:

import { WalletClient, JWTUtils } from '@games-fun/server-sdk';
import WebSocket from 'ws';

// Initialize wallet client
const walletClient = new WalletClient({
    apiKey: process.env.GAMES_FUN_API_KEY
});

// Set up WebSocket server
const wss = new WebSocket.Server({ port: 3001 });
const gameManager = new GameManager();

State Management

Create a game manager to handle state:

class GameManager {
    private states: Map<string, GameState> = new Map();
    
    getState(playerId: string): GameState {
        if (!this.states.has(playerId)) {
            this.states.set(playerId, {
                coins: 0,
                inventory: {},
                lastAction: null
            });
        }
        return this.states.get(playerId)!;
    }
    
    updateState(playerId: string, update: Partial<GameState>) {
        const state = this.getState(playerId);
        this.states.set(playerId, { ...state, ...update });
        return this.states.get(playerId)!;
    }
}

interface GameState {
    coins: number;
    inventory: Record<string, number>;
    lastAction: {
        type: string;
        timestamp: number;
        data?: any;
    } | null;
}

Connection Handling

Handle WebSocket connections:

wss.on('connection', (ws) => {
    let playerId: string | null = null;
    let isAuthenticated = false;

    ws.on('message', async (data) => {
        try {
            const message = JSON.parse(data.toString());

            // Handle player registration
            if (message.type === 'register') {
                playerId = message.playerId;
                const state = gameManager.getState(playerId);
                
                ws.send(JSON.stringify({
                    type: 'init',
                    state,
                    config: gameConfig
                }));
                return;
            }

            // Require authentication for other actions
            if (!isAuthenticated && message.type !== 'authenticate') {
                ws.send(JSON.stringify({
                    type: 'error',
                    error: 'Authentication required'
                }));
                return;
            }

            // Handle messages based on type
            switch (message.type) {
                case 'authenticate':
                    await handleAuthentication(message, ws);
                    break;
                case 'purchase':
                    await handlePurchase(message, ws, playerId!);
                    break;
                case 'use_item':
                    await handleItemUse(message, ws, playerId!);
                    break;
                // Add other message handlers
            }
        } catch (error) {
            ws.send(JSON.stringify({
                type: 'error',
                error: error instanceof Error ? error.message : 'Unknown error'
            }));
        }
    });

    // Handle disconnection
    ws.on('close', () => {
        if (playerId) {
            // Clean up player state if needed
        }
    });
});

Message Handlers

Implement handlers for different message types:

async function handleAuthentication(message: any, ws: WebSocket) {
    const { token } = message;
    
    try {
        const authResult = await verifyPlayerToken(token);
        if (!authResult.valid) {
            throw new Error('Invalid token');
        }

        isAuthenticated = true;
        ws.send(JSON.stringify({
            type: 'auth_status',
            isAuthenticated: true
        }));
    } catch (error) {
        ws.send(JSON.stringify({
            type: 'auth_status',
            isAuthenticated: false,
            error: error instanceof Error ? error.message : 'Auth failed'
        }));
    }
}

async function handlePurchase(message: any, ws: WebSocket, playerId: string) {
    const { itemId, price } = message;
    const state = gameManager.getState(playerId);

    // Check if player can afford item
    if (state.coins < price) {
        throw new Error('Insufficient coins');
    }

    // Update state
    state.coins -= price;
    state.inventory[itemId] = (state.inventory[itemId] || 0) + 1;
    state.lastAction = {
        type: 'purchase',
        timestamp: Date.now(),
        data: { itemId, price }
    };

    // Save and broadcast update
    gameManager.updateState(playerId, state);
    ws.send(JSON.stringify({
        type: 'state_update',
        state
    }));
}

Action Validation

Validate actions from the Games.fun platform:

app.post('/api/validate', async (req, res) => {
    const { actionName, requestId, params } = req.body;
    
    try {
        // Validate origin
        if (process.env.NODE_ENV === 'production' && 
            req.headers.origin !== 'https://games.fun') {
            return res.status(403).json({ error: 'Unauthorized origin' });
        }

        // Handle different actions
        switch (actionName) {
            case 'transferTokens':
                await validateTransfer(params);
                break;
            case 'useItem':
                await validateItemUse(params);
                break;
            default:
                throw new Error(`Unknown action: ${actionName}`);
        }

        res.json({
            success: true,
            actionName,
            requestId,
            timestamp: new Date().toISOString()
        });
    } catch (error) {
        res.status(400).json({
            success: false,
            error: error instanceof Error ? error.message : 'Validation failed'
        });
    }
});

State Broadcasting

Send updates to relevant clients:

function broadcastStateUpdate(playerId: string, state: GameState) {
    wss.clients.forEach(client => {
        if (client.readyState === WebSocket.OPEN && 
            client.playerId === playerId) {
            client.send(JSON.stringify({
                type: 'state_update',
                state
            }));
        }
    });
}

Error Handling

Handle common server scenarios:

// Connection errors
wss.on('error', (error) => {
    console.error('WebSocket server error:', error);
});

// Message parsing errors
ws.on('message', (data) => {
    try {
        const message = JSON.parse(data.toString());
        // Handle message...
    } catch (error) {
        ws.send(JSON.stringify({
            type: 'error',
            error: 'Invalid message format'
        }));
    }
});

// State update errors
function safeStateUpdate(playerId: string, update: Partial<GameState>) {
    try {
        const newState = gameManager.updateState(playerId, update);
        broadcastStateUpdate(playerId, newState);
    } catch (error) {
        console.error(`State update failed for ${playerId}:`, error);
        // Handle error...
    }
}

Best Practices

1. Authentication

   • Always verify JWT tokens

   • Implement token refresh

   • Clear invalid tokens

   • Log auth failures

2. State Management

   • Use atomic updates

   • Validate state changes

   • Handle race conditions

   • Back up state regularly

3. Error Handling

   • Provide clear error messages

   • Log all errors

   • Handle disconnections

   • Implement reconnection

4. Security

   • Validate all inputs

   • Rate limit requests

   • Check permissions

   • Sanitize outputs

Next Steps

• React Integration - Use with React components

• Development Guide - Testing and deployment