Documentation

React SDK

The official React SDK for LuduStack, enabling seamless integration of gamification features into your React applications.

Installation

Install the SDK using npm or yarn:

npm install @ludustack/react

Getting Started

Wrap your application with the LudustackProvider and provide your API credentials:

import { LudustackProvider } from '@ludustack/react';

function App() {
  return (
    <LudustackProvider
      apiKey="your-api-key"
    >
      <YourApp />
    </LudustackProvider>
  );
}

Important

Never expose your API key in client-side code. For React applications, consider setting up a backend proxy to handle API requests securely.

Available Hooks

The React SDK provides several hooks to interact with the LuduStack platform:

useGame - Manage games and their state
usePlayer - Access and update player information
useLeaderboard - Access leaderboard data
useOperations - Perform game operations like giving points and XP

Usage Examples

Using Player Data

Access and update player information:

import { usePlayer } from '@ludustack/react';

function PlayerProfile() {
  const { 
    player, 
    isLoading, 
    error, 
    updatePlayer,
    givePoints 
  } = usePlayer('player-123');

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>{player.displayName}</h2>
      <p>Level: {player.level}</p>
      <p>Points: {player.points}</p>
      <button 
        onClick={() => updatePlayer({ displayName: 'New Name' })}
      >
        Update Name
      </button>
      <button
        onClick={() => givePoints(100)}
      >
        Add 100 Points
      </button>
    </div>
  );
}

Game Management

Manage game state and give points to players:

import { useGame, useOperations } from '@ludustack/react';

function GameControl() {
  const { 
    game, 
    isLoading, 
    error, 
    startGame,
    pauseGame,
    resumeGame,
    completeGame,
  } = useGame('game-123');
  
  // Using operations hook (recommended for operations)
  const { givePoints } = useOperations();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  const handleLevelComplete = () => {
    givePoints('player-123', 50, 'game-123', 'level_completed');
  };

  return (
    <div>
      <h2>{game.name}</h2>
      <p>Status: {game.status}</p>
      <div className="button-group">
        <button onClick={startGame} disabled={game.status !== 'pending'}>
          Start Game
        </button>
        <button onClick={pauseGame} disabled={game.status !== 'active'}>
          Pause Game
        </button>
        <button onClick={resumeGame} disabled={game.status !== 'paused'}>
          Resume Game
        </button>
        <button onClick={completeGame} disabled={game.status === 'completed'}>
          Complete Game
        </button>
        <button onClick={handleLevelComplete}>
          Complete Level (+50 points)
        </button>
      </div>
    </div>
  );
}

Game Operations

Perform operations like giving points and XP to players:

import { useOperations } from '@ludustack/react';

function GameOperations() {
  const { 
    givePoints, 
    giveXp, 
  } = useOperations();

  const handleRewardPlayer = async () => {
    // Give points to a player
    await givePoints(
      'player-123',         // Player ID
      'quest_completed'     // Optional action name
    );
  };

  return (
    <div>
      <h2>Game Operations</h2>
      <button onClick={handleRewardPlayer}>
        Reward Player
      </button>
    </div>
  );
}

Display a Leaderboard

Show a leaderboard in your application:

import { useLeaderboard } from '@ludustack/react';

function Leaderboard() {
  const { 
    leaderboard, 
    isLoading, 
    error,
    refresh
  } = useLeaderboard({
    gameId: 'game-123',      // Optional filter by game
    limit: 10,               // Number of entries to show
    period: 'weekly'         // 'all-time', 'monthly', 'weekly', 'daily'
  });

  if (isLoading) return <div>Loading leaderboard...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>Weekly Leaderboard</h2>
      <button onClick={refresh}>Refresh</button>
      <table>
        <thead>
          <tr>
            <th>Rank</th>
            <th>Player</th>
            <th>Score</th>
          </tr>
        </thead>
        <tbody>
          {leaderboard.entries.map((entry) => (
            <tr key={entry.playerId}>
              <td>{entry.rank}</td>
              <td>{entry.playerName}</td>
              <td>{entry.score}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

UI Components

The SDK also includes ready-to-use UI components:

import { 
  PlayerBadge, 
  PointsDisplay, 
  LeaderboardTable
} from '@ludustack/react';

function GameUI() {
  return (
    <div>
      <PlayerBadge playerId="player-123" />
      <PointsDisplay playerId="player-123" />
      
      <h2>Leaderboard</h2>
      <LeaderboardTable leaderboardId="leaderboard-123" limit={5} />
    </div>
  );
}

Provider Configuration

The LudustackProvider accepts these configuration options:

// Initialize the provider with options
<LuduStackProvider 
  apiKey="your-api-key" 
  gameId="your-game-id"
  baseURL="https://ludustack.com/api"  // Optional
  // Current API version: v2
>
  <YourApp />
</LuduStackProvider>

For non-React applications, check out our JavaScript SDK documentation.

For full API reference, visit the API Reference section.