React Integration

Games.fun provides a React SDK with hooks and components for easy integration. This guide shows how to use the React SDK in your game.

Installation

npm install @games-fun/react @games-fun/sdk

Provider Setup

Wrap your app with the Games.fun provider:

import { GamesFunProvider } from '@games-fun/react';

function App() {
    return (
        <GamesFunProvider 
            options={{ 
                debug: true,
                gameServerUrl: "your-validation-endpoint"
            }}
            onInitialized={(connection) => {
                console.log('SDK initialized:', connection);
            }}
            onError={(error) => {
                console.error('SDK error:', error);
            }}
        >
            <Game />
        </GamesFunProvider>
    );
}

Game Context

Create a game context to manage state:

import { createContext, useContext, useState, useEffect } from 'react';
import { useGamesFun } from '@games-fun/react';

interface GameContextType {
    gameState: GameState | null;
    isAuthenticated: boolean;
    authToken: string | null;
    getAuthToken: () => Promise<void>;
    purchaseItem: (itemId: string, price: number) => Promise<void>;
    useItem: (itemId: string) => Promise<void>;
}

const GameContext = createContext<GameContextType | null>(null);

export function GameProvider({ children }: { children: React.ReactNode }) {
    const { connection, triggerAction } = useGamesFun();
    const [gameState, setGameState] = useState<GameState | null>(null);
    const [isAuthenticated, setIsAuthenticated] = useState(false);
    const [authToken, setAuthToken] = useState<string | null>(null);
    const gameServerRef = useRef<GameServer | null>(null);

    // Initialize game server when connected
    useEffect(() => {
        if (!connection?.privyId) return;

        const gameServer = new GameServer('wss://your-game-server');
        
        gameServer.on('init', ({ state }) => {
            setGameState(state);
        });

        gameServer.on('stateUpdate', (state) => {
            setGameState(state);
        });

        gameServer.connect(connection.privyId);
        gameServerRef.current = gameServer;

        return () => gameServer.disconnect();
    }, [connection?.privyId]);

    // Authentication
    const getAuthToken = async () => {
        try {
            const result = await triggerAction("issueJWT", {});
            if (result.params?.jwt) {
                setAuthToken(result.params.jwt);
                setIsAuthenticated(true);
                gameServerRef.current?.setJWT(result.params.jwt);
            }
        } catch (error) {
            console.error('Authentication failed:', error);
            throw error;
        }
    };

    // Game actions
    const purchaseItem = async (itemId: string, price: number) => {
        if (!gameServerRef.current || !isAuthenticated) {
            throw new Error('Server not connected or authentication required');
        }

        try {
            await gameServerRef.current.purchaseItem(itemId, price);
        } catch (error) {
            if (error.message.includes('Authentication')) {
                setAuthToken(null);
                setIsAuthenticated(false);
                gameServerRef.current.setJWT(null);
            }
            throw error;
        }
    };

    return (
        <GameContext.Provider value={{
            gameState,
            isAuthenticated,
            authToken,
            getAuthToken,
            purchaseItem
        }}>
            {children}
        </GameContext.Provider>
    );
}

export function useGame() {
    const context = useContext(GameContext);
    if (!context) {
        throw new Error('useGame must be used within a GameProvider');
    }
    return context;
}

Components

Authentication Component

function Authentication() {
    const { isAuthenticated, authToken, getAuthToken } = useGame();

    return (
        <div className="auth-panel">
            <h3>Authentication</h3>
            <div className="auth-status">
                {isAuthenticated ? (
                    <span className="status-authenticated">✓ Authenticated</span>
                ) : (
                    <span className="status-unauthenticated">✗ Not authenticated</span>
                )}
            </div>
            <div className="auth-buttons">
                <button 
                    onClick={getAuthToken} 
                    disabled={isAuthenticated}
                >
                    Authenticate
                </button>
            </div>
            {authToken && (
                <div className="token-display">
                    JWT: {authToken.substring(0, 8)}...
                </div>
            )}
        </div>
    );
}

Shop Component

function Shop() {
    const { gameState, isAuthenticated, purchaseItem } = useGame();
    const { connection } = useGamesFun();

    const handlePurchase = async (itemId: string, price: number) => {
        try {
            await purchaseItem(itemId, price);
        } catch (error) {
            if (error instanceof SDKError) {
                switch (error.code) {
                    case 'NO_WALLET':
                        alert('Please connect your wallet');
                        break;
                    case 'INSUFFICIENT_BALANCE':
                        alert('Not enough tokens');
                        break;
                    default:
                        alert(`Error: ${error.message}`);
                }
            }
        }
    };

    return (
        <div className="shop">
            <h3>Shop</h3>
            <div className="balance">
                Points: {gameState?.coins || 0}
                {connection?.tokenBalance && (
                    <span>Tokens: {connection.tokenBalance}</span>
                )}
            </div>
            <div className="items">
                {Object.entries(gameConfig.items).map(([id, item]) => (
                    <div key={id} className="item">
                        <h4>{item.name}</h4>
                        <p>{item.description}</p>
                        <button
                            onClick={() => handlePurchase(id, item.price)}
                            disabled={!isAuthenticated}
                        >
                            Buy for {item.price} points
                        </button>
                    </div>
                ))}
            </div>
        </div>
    );
}

Inventory Component

function Inventory() {
    const { gameState, useItem } = useGame();

    if (!gameState) return null;

    return (
        <div className="inventory">
            <h3>Inventory</h3>
            <div className="items">
                {Object.entries(gameState.inventory).map(([itemId, count]) => (
                    <div key={itemId} className="item">
                        <span>{itemId}: {count}</span>
                        <button 
                            onClick={() => useItem(itemId)}
                            disabled={count === 0}
                        >
                            Use
                        </button>
                    </div>
                ))}
            </div>
        </div>
    );
}

Hooks

useGamesFun

Access SDK connection and actions:

function GameStatus() {
    const { connection, triggerAction } = useGamesFun();

    if (!connection) {
        return <div>Connecting...</div>;
    }

    return (
        <div>
            <div>Connected: {connection.privyId}</div>
            <div>Wallet: {connection.walletAddress}</div>
            <div>Balance: {connection.tokenBalance}</div>
        </div>
    );
}

useGamesFunActions

Register and use game actions:

function TokenActions() {
    const actions = useGamesFunActions({
        transferTokens: "Transfer tokens to game wallet",
        issueJWT: "Get JWT authentication token"
    });

    const handleTransfer = async () => {
        try {
            await actions.transferTokens({
                recipient: gameWalletAddress,
                amount: 100
            });
        } catch (error) {
            console.error('Transfer failed:', error);
        }
    };

    return (
        <button onClick={handleTransfer}>
            Transfer 100 Tokens
        </button>
    );
}

Error Handling

Handle common scenarios:

function ErrorBoundary({ children }: { children: React.ReactNode }) {
    const [error, setError] = useState<Error | null>(null);

    if (error) {
        return (
            <div className="error-display">
                <h3>Error</h3>
                <p>{error.message}</p>
                <button onClick={() => setError(null)}>
                    Try Again
                </button>
            </div>
        );
    }

    return (
        <ErrorBoundary onError={setError}>
            {children}
        </ErrorBoundary>
    );
}

Development Mode

Enable dev mode for testing:

function App() {
    return (
        <GamesFunProvider 
            options={{ 
                debug: true,
                dev: {
                    enabled: true,
                    mock: {
                        wallet: {
                            tokenBalance: '1000'
                        }
                    }
                }
            }}
        >
            <Game />
        </GamesFunProvider>
    );
}

Best Practices

1. State Management

   • Use context for game state

   • Handle loading states

   • Show error messages

   • Keep UI responsive

2. Authentication

   • Check auth before actions

   • Handle token expiry

   • Show auth status

   • Clear invalid tokens

3. Error Handling

   • Use error boundaries

   • Show helpful messages

   • Provide retry options

   • Log errors properly

4. Development

   • Use dev mode locally

   • Test error cases

   • Mock responses

   • Check console logs

Next Steps

• Development Guide - Testing and deployment