@randbox/react Component Library

@randbox/react is a high-performance React game component library based on Canvas rendering, providing 5 core game components. All components use RandBox as the random number generator to ensure true randomness and fairness.

✨ Features

🎮 5 Core Game Components: Grid lottery, slot machine, scratch card, dice game, rock-paper-scissors
🚀 High Performance: Canvas-based rendering with smooth animation effects
📦 Lightweight: Optimized bundle size (ES module: ~109KB, UMD: ~45KB)
🎨 No CSS Required: All styles rendered via Canvas with no external dependencies
📱 Responsive: Automatically adapts to different screen sizes
🔧 TypeScript: Complete type definition support
🎲 True Random: High-quality random number generation based on RandBox

📦 Installation


npm install @randbox/react randbox
# or
yarn add @randbox/react randbox
# or
pnpm add @randbox/react randbox

🚀 Quick Start


import { GridLottery, DiceGame, ScratchCard } from '@randbox/react';
 
function App() {
  return (
    <div>
      {/* Grid Lottery */}
      <GridLottery
        prizes={['Prize 1', 'Prize 2', 'Prize 3', 'Thank you for playing']}
        onResult={(result) => console.log('Lottery result:', result)}
      />
 
      {/* Dice Game */}
      <DiceGame
        diceCount={2}
        gameMode="sum"
        targetSum={7}
        onResult={(result) => console.log('Dice result:', result)}
      />
 
      {/* Scratch Card */}
      <ScratchCard
        rows={3}
        cols={3}
        symbols={['🍎', '🍌', '🍇']}
        onScratch={(result) => console.log('Scratch result:', result)}
      />
    </div>
  );
}

🎮 Component List

GridLottery - Grid Lottery

Classic nine-grid turntable lottery supporting custom prizes and weights.

SlotMachine - Slot Machine

Multi-reel slot machine style lottery component supporting custom symbols and winning rules.

ScratchCard - Scratch Card

Real scratch experience supporting multiple winning modes (horizontal, vertical, diagonal).

DiceGame - Dice Game

3D effect dice game supporting multiple game modes (simple, sum, big/small, guess, etc.).

RockPaperScissors - Rock Paper Scissors

Classic rock paper scissors game supporting multiple AI strategies and statistics.

🎯 Performance Optimization

Tree-shaking: Supports on-demand imports, unused components won’t be bundled
Canvas Rendering: GPU acceleration for smooth 60fps animations
External Dependencies: React and RandBox as external dependencies to avoid duplicate bundling
Code Minification: Automatically removes console.log and debug code in production

🔧 Technical Specifications

Rendering Engine: HTML5 Canvas
Random Number Generation: RandBox (Mersenne Twister algorithm)
Animation: requestAnimationFrame + easing functions
Responsive: Automatically adapts to container size
TypeScript: Complete type support

📚 API Reference

All components inherit from the BaseGameProps interface:


interface BaseGameProps {
  className?: string;
  style?: React.CSSProperties;
  disabled?: boolean;
  onGameStart?: () => void;
  onGameEnd?: (result: any) => void;
}

Component Detailed Types

GridLottery (Grid Lottery)


interface GridLotteryProps {
  prizes: string[];                    // Prize list
  weights?: number[];                  // Prize weights
  gridSize?: number;                   // Grid size, default 9
  animationDuration?: number;          // Animation duration, default 3000
  buttonText?: string;                 // Button text
  onResult?: (result) => void;        // Result callback
}
 
interface GridLotteryResult {
  position: number;    // Win position (0-8)
  prize: string;       // Won prize
  animation: number[]; // Animation path
}

SlotMachine (Slot Machine)


interface SlotMachineProps {
  reels: string[][];                    // Reel arrays
  weights?: number[][];                 // Weight configuration
  animationDuration?: number;           // Animation duration, default 3000
  buttonText?: string;                  // Button text
  width?: number;                       // Canvas width
  height?: number;                      // Canvas height
  onResult?: (result) => void;         // Result callback
}
 
interface SlotMachineResult {
  results: string[];    // Results from each reel
  isJackpot: boolean;   // Whether it's a jackpot
  combination: string;  // Combination description
}

LuckyWheel (Lucky Wheel)


interface LuckyWheelProps {
  prizes: string[];                     // Prize list
  weights?: number[];                   // Prize weights
  colors?: string[];                    // Custom colors
  animationDuration?: number;           // Animation duration, default 4000
  buttonText?: string;                  // Button text
  onResult?: (result) => void;         // Result callback
}
 
interface LuckyWheelResult {
  prizeIndex: number;  // Won prize index
  prize: string;       // Won prize
  angle: number;       // Final rotation angle
  round: number;       // Round number
}

DiceGame (Dice Game)


interface DiceGameProps {
  diceCount?: number;                   // Number of dice, default 1
  sides?: number;                       // Number of sides on dice, default 6
  gameMode?: DiceGameMode;              // Game mode
  targetSum?: number;                   // Target sum
  onResult?: (result) => void;         // Result callback
}
 
type DiceGameMode = 'simple' | 'sum' | 'bigSmall' | 'guess' | 'even_odd' | 'specific';
 
interface DiceGameResult {
  results: number[];    // Dice results array
  total: number;        // Sum of dice values
  gameMode: string;     // Game mode
  isWin?: boolean;      // Whether won
  message: string;      // Result description
}

ScratchCard (Scratch Card)


interface ScratchCardProps {
  rows?: number;                        // Number of rows, default 3
  cols?: number;                        // Number of columns, default 3
  symbols?: string[];                   // Symbol array
  winProbability?: number;              // Win probability, default 0.3
  width?: number;                       // Canvas width, default 300
  height?: number;                      // Canvas height, default 200
  onScratch?: (result) => void;        // Scratch callback
  onNewCard?: () => void;              // New card callback
}
 
interface ScratchCardResult {
  grid: string[][];                     // Card grid content
  isWinner: boolean;                    // Whether winner
  scratchProgress?: number;             // Scratch progress (0-1)
  winningInfo?: {                       // Win information
    pattern: string[];
    name: string;
    prize: string;
    positions: Array<{ row: number; col: number; }>;
  };
}

RockPaperScissors (Rock Paper Scissors)


interface RockPaperScissorsProps {
  choices?: string[];                   // Available choices
  emojis?: Record<string, string>;      // Emoji icons
  showStats?: boolean;                  // Show statistics, default true
  strategy?: RPSStrategy;               // AI strategy, default 'random'
  width?: number;                       // Canvas width
  height?: number;                      // Canvas height
  onResult?: (result) => void;         // Result callback
}
 
type RPSStrategy = 'random' | 'counter' | 'pattern';
type RPSResultType = 'win' | 'lose' | 'tie';
 
interface RPSResult {
  playerChoice: string;      // Player's choice
  computerChoice: string;    // Computer's choice
  result: RPSResultType;     // Game result
  message: string;           // Result description
  emoji: {                   // Emoji icons
    player: string;
    computer: string;
  };
  round: number;             // Round number
}
 
interface RPSStats {
  totalGames: number;  // Total games played
  wins: number;        // Wins
  losses: number;      // Losses
  ties: number;        // Ties
  winRate: string;     // Win rate (percentage)
}

CoinFlip (Coin Flip)


interface CoinFlipProps {
  animationDuration?: number;           // Animation duration, default 2000
  showStats?: boolean;                  // Show statistics, default true
  width?: number;                       // Canvas width
  height?: number;                      // Canvas height
  onResult?: (result) => void;         // Result callback
}
 
type CoinSide = 'heads' | 'tails';
 
interface CoinFlipResult {
  result: CoinSide;   // Coin result
  round: number;      // Round number
  timestamp: number;  // Timestamp
}
 
interface CoinFlipStats {
  totalFlips: number;  // Total flips
  heads: number;       // Heads count
  tails: number;       // Tails count
  headsRate: string;   // Heads rate
  tailsRate: string;   // Tails rate
}

Each component also has its own specific properties and type definitions. See the dedicated documentation for each component.

🎨 Custom Styling

Since all components are Canvas-based, style customization is mainly done through component properties:


// Control component appearance through container styles
<div style={{ border: '2px solid #ccc', borderRadius: '10px' }}>
  <GridLottery {...props} />
</div>
 
// Control Canvas content through component properties
<DiceGame
  style={{ border: '1px solid #ddd' }}
  className="my-dice-game"
/>

🤝 Contributing

Contributions are welcome! Please check our Contributing Guide .

📄 License

MIT License - see LICENSE file for details.