@omnitronix/bonnys-fortune-game-engine 1.0.0-beta.1

package/README.md

@@ -0,0 +1,680 @@
+# Bonny's Fortune Game Engine
+
+![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
+![License](https://img.shields.io/badge/license-UNLICENSED-red.svg)
+![Package](https://img.shields.io/badge/package-%40omnitronix%2Fbonnys--fortune--game--engine-green.svg)
+
+Pure business logic library for the Bonny's Fortune slot game. A framework-agnostic, TypeScript-based game engine that handles all core game mechanics, state management, and bonus game logic.
+
+## What is Bonny's Fortune Game Engine?
+
+The Bonny's Fortune Game Engine is an isolated, framework-agnostic library containing pure business logic for the Bonny's Fortune slot game. It implements a command-based architecture that separates game logic from presentation and infrastructure concerns.
+
+### Core Characteristics
+
+- **Pure Business Logic**: Contains only game rules, calculations, and state transitions
+- **Framework Agnostic**: No dependencies on specific UI frameworks or web servers
+- **Command-Based Architecture**: All interactions through well-defined commands
+- **State Separation**: Distinguishes between public state (visible to players) and private state (server-side only)
+- **RNG Integration**: Supports both external RNG services and local dummy RNG for testing
+- **Audit Trail**: Complete RNG outcome tracking for compliance and debugging
+
+### Game Specifications
+
+- **RTP**: 96%
+- **Game Type**: Slot
+- **Version**: 1.0.0
+- **Layout**: 5 reels × 3 rows
+- **Win Evaluation**: 243 ways to win
+
+## Features
+
+- **Command-Based Architecture**: 6 different command types for all game operations
+- **State Management**: Public/private state separation with type safety
+- **RNG Integration**: Pluggable RNG clients with audit trail support
+- **Configuration Validation**: Uses class-validator for runtime type checking
+- **Multiple Bonus Games**: 4 unique bonus game mechanics
+- **TypeScript Support**: Complete type definitions for all interfaces
+- **Comprehensive Testing**: Full test suite with Jest and coverage reporting
+
+## Architecture Overview
+
+The game engine follows a modular architecture with clear separation of concerns:
+
+### Core Components
+
+- **Game Engine** (`BonnysFortuneV1GameEngine`): Main entry point and command processor
+- **Game Logic** (`BonnysFortuneGameLogic`): Core game rules and state transitions
+- **Handlers**: Specialized handlers for different game modes:
+  - `BaseGameHandler`: Base game spin logic
+  - `TreasureHuntBonusHandler`: Pick-style bonus game
+  - `FreeSpinsBonusHandler`: Free spins with multipliers
+  - `SteeringToTheFortuneBonusHandler`: Wheel of fortune bonus
+  - `CollectFeatureBonusHandler`: Multi-spin collect feature
+- **RNG Service**: Random number generation with pluggable clients
+- **Win Calculator**: Payline/ways evaluation and win computation
+- **Validators**: Configuration and input validation using class-validator
+- **Config Loaders**: File system-based configuration loading
+
+### Directory Structure
+
+```
+src/
+├── bonnys-fortune-v1.game-engine.ts  # Main game engine
+├── logic/                             # Game logic and handlers
+├── config/                            # Configuration loaders
+├── validation/                        # Config validators
+├── rng/                              # RNG clients and service
+├── domain/                           # Types and DTOs
+└── helpers/                          # Utility functions
+```
+
+## Installation
+
+```bash
+npm install @omnitronix/bonnys-fortune-game-engine
+```
+
+> **Note**: This is a private package for Omnitronix internal use only (UNLICENSED).
+
+## Environment Variables
+
+The game engine supports various RNG configurations through environment variables:
+
+| Variable | Description | Values | Default |
+|----------|-------------|--------|---------|
+| `RNG_CLIENT_MODE` | RNG client mode | `local` (DummyRngClient), `external` (HttpRngClient) | `external` |
+| `RNG_CLIENT_URL` | External RNG service HTTP URL | URL string | - |
+| `RNG_CLIENT_GRPC_URL` | External RNG service gRPC URL | URL string | - |
+| `RNG_CLIENT_METHOD` | RNG communication method | `grpc`, `rest` | - |
+| `RNG_CLIENT_POOL_SIZE` | RNG ring buffer pool size | Number | `2000` |
+
+### Environment Examples
+
+**Local Development** (uses dummy RNG):
+```bash
+RNG_CLIENT_MODE=local
+```
+
+**Production Environment** (external RNG via gRPC):
+```bash
+RNG_CLIENT_MODE=external
+RNG_CLIENT_METHOD=grpc
+RNG_CLIENT_GRPC_URL=grpc://rng-prod.omnitronix.com:50051
+RNG_CLIENT_POOL_SIZE=5000
+```
+
+## Quick Start
+
+```typescript
+import { BonnysFortuneV1GameEngine } from '@omnitronix/bonnys-fortune-game-engine';
+
+// Initialize game engine
+const gameEngine = new BonnysFortuneV1GameEngine();
+
+// Get game info
+const info = gameEngine.getGameEngineInfo();
+// { gameCode: 'bonnys-fortune', version: '1.0.0', rtp: 96, gameType: 'slot' }
+
+// Initialize session
+const initCommand = {
+  id: 'cmd-init-123',
+  type: 'INIT_SESSION_STATE',
+  payload: {
+    betAmountThresholds: [10, 25, 50, 100],
+    defaultBetAmount: 10
+  }
+};
+
+const initResult = await gameEngine.processCommand({}, {}, initCommand);
+// Returns: { success, publicState, privateState, outcome, rngOutcome }
+
+// Process spin
+const spinCommand = {
+  id: 'cmd-spin-456',
+  type: 'SPIN',
+  payload: {
+    sessionId: 'session-123',
+    betAmount: 10,
+    gameCode: 'bonnys-fortune',
+    gameVersion: '1.0.0',
+    lines: 10,
+    creditsPerLine: 1
+  }
+};
+
+const spinResult = await gameEngine.processCommand(
+  initResult.publicState,
+  initResult.privateState,
+  spinCommand
+);
+```
+
+## API Reference
+
+### Main Class: `BonnysFortuneV1GameEngine`
+
+#### Constructor
+```typescript
+new BonnysFortuneV1GameEngine()
+```
+- Initializes game engine with configuration
+- Auto-loads game configuration and reel strips from file system
+- Sets up RNG client based on environment variables
+
+#### Methods
+
+**`getGameEngineInfo(): GameEngineInfo`**
+Returns game metadata including code, version, RTP, and game type.
+
+**`processCommand(publicState, privateState, command): Promise<CommandProcessingResult>`**
+Main command processor that handles all game operations.
+
+### Commands
+
+The game engine supports 6 different command types:
+
+#### 1. INIT_SESSION_STATE
+
+**Purpose**: Initialize game session state with bonus meters
+
+**Payload**:
+```typescript
+{
+  betAmountThresholds: number[];
+  defaultBetAmount: number;
+}
+```
+
+**Returns**: Initial public and private state
+
+#### 2. SPIN
+
+**Purpose**: Execute base game spin
+
+**Payload**:
+```typescript
+{
+  sessionId: string;
+  betAmount: number;
+  gameCode: string;
+  gameVersion: string;
+  lines?: number;
+  creditsPerLine?: number;
+}
+```
+
+**Returns**: Spin result with screen, wins, and potential bonus triggers
+
+#### 3. START_BONUS_ROUND
+
+**Purpose**: Start triggered bonus round
+
+**Payload**:
+```typescript
+{
+  sessionId: string;
+  bonusType: string;
+  betAmount: number;
+  gameCode: string;
+  gameVersion: string;
+  lines?: number;
+  creditsPerLine?: number;
+  bonusId: string;
+}
+```
+
+**Returns**: Complete bonus round results
+
+#### 4. UPDATE_SESSION_STATE
+
+**Purpose**: Update session state (e.g., redraw bonus meters after bonus completion)
+
+**Payload**:
+```typescript
+{
+  bonusMeters: {
+    redraw: string[];
+  };
+}
+```
+
+**Returns**: Updated state
+
+#### 5. DEBUG_TRIGGER_BONUS (Testing/Admin)
+
+**Purpose**: Force trigger specific bonus game
+
+**Payload**: `DebugTriggerBonusCommand`
+
+**Returns**: State with pending bonus
+
+#### 6. DEBUG_UPDATE_BONUS_METER_PROGRESS (Testing/Admin)
+
+**Purpose**: Manually set bonus meter progress
+
+**Payload**: `DebugUpdateBonusMeterProgressCommand`
+
+**Returns**: Updated meter state
+
+### State Types
+
+#### PublicState (visible to player)
+```typescript
+{
+  currentBetAmount: number;
+  bonusMeters: {
+    [bonusGameId: string]: {
+      symbolName: string;
+      symbolId: number;
+      threshold: number;
+      progress: number;
+      level: number;
+    }
+  }
+}
+```
+
+#### PrivateState (server-side only)
+```typescript
+{
+  screen?: number[][];
+  nextSpinType: SpinType;
+  pendingBonuses: BonusTrigger[];
+  activeBonus?: BonusTrigger;
+  bonusMetersByAmount: Record<number, MetersState>;
+}
+```
+
+#### CommandProcessingResult
+```typescript
+{
+  success: boolean;
+  publicState: BonnysFortunePublicState;
+  privateState: BonnysFortunePrivateState;
+  outcome?: any; // Spin/bonus result
+  message?: string;
+  rngOutcome?: RngOutcome; // RNG audit trail
+}
+```
+
+## Game Mechanics
+
+### Base Game
+
+- **Layout**: 5 reels × 3 rows
+- **Win Evaluation**: 243 ways to win
+- **Symbols**: 10 base symbols (H1-H3 high, M1-M3 medium, L1-L4 low) + Wild + Scatter
+- **Symbol Multipliers**: Range from 2x (L4) to 500x (H1) for 5-of-a-kind
+- **Bet Levels**: [10, 25, 50, 100, 500, 1000, 2000]
+- **RTP**: 96%
+
+### Bonus Meters System
+
+Progressive meters track collection of specific high-value symbols (H1, H2, H3):
+
+- Each meter has dynamic threshold (min-max range)
+- Progress increases when symbols land on reels
+- 5 progress levels (0-25%, 25-65%, 65-80%, 80-100%, 100%+)
+- Separate meters per bet amount
+- Triggers corresponding bonus game when threshold reached
+
+### Bonus Game 1: Treasure Hunt
+
+**Type**: Pick-style bonus
+
+**Mechanics**:
+- 25 symbols arranged in grid
+- 6 steps/picks to reveal prizes
+- 4 jackpot levels: Mini (20x), Minor (50x), Major (200x), Grand (2000x)
+- Each pick reveals multiplier or jackpot
+- Jackpot triggered when specific count revealed (Mini: 10, Minor: 7, Major: 5, Grand: 3)
+- Starting counts configurable per jackpot level
+
+**Trigger**: Bonus Meter 1 (H1 symbol collection) reaches threshold
+
+**Weighted Selection**: Different probabilities for each prize tier
+
+### Bonus Game 2: Free Spins
+
+**Type**: Free spins with multipliers
+
+**Mechanics**:
+- 6 spin type variants with different configurations
+- Variable layouts: 5×3, 5×4, or 5×5 reels
+- Variable spin counts: 4 or 8 spins
+- Win multipliers: 1x to 20x
+- Each variant has weight for random selection
+- All wins multiplied by selected multiplier
+- Uses alternative reel strips (bonus reels)
+
+**Trigger**: Bonus Meter 2 (H2 symbol collection) reaches threshold
+
+**Reel Options**: 4 reel strip options with configurable weights [1, 1, 4, 4]
+
+### Bonus Game 3: Steering to the Fortune (Wheel)
+
+**Type**: Wheel of fortune / prize wheel
+
+**Mechanics**:
+- Spin wheel once
+- 10 possible outcomes with weighted selection
+- Prize types:
+  - **MULTIPLIER**: Direct win multipliers (5x, 8x, 10x, 15x, 25x, 40x, 80x)
+  - **BONUS**: Triggers another bonus game (collectFeature, bonusGame1, bonusGame2)
+- Multiplier applied to bet amount for wins
+- Bonus prizes trigger immediate transition to other bonus games
+
+**Trigger**: Bonus Meter 3 (H3 symbol collection) reaches threshold
+
+**Weights**: Lower multipliers more common, higher multipliers rare, bonus triggers rare
+
+### Collect Feature (Scatter Bonus)
+
+**Type**: Multi-spin collect feature
+
+**Mechanics**:
+- Triggered by 3+ scatter symbols in base game
+- 6 spins total
+- Each spin reveals 1-3 special symbols
+- Two symbol types:
+  - **Multiplier symbols** (CM1: 1x, CM2: 2x, CM3: 3x) - multiply total value
+  - **Value symbols** (CV1: 1, CV2: 2, CV3: 5) - add to total value
+- Symbols can be "slashed" (disabled) based on weighted probability
+- Checkpoints at specific spins require minimum multipliers/values (Spin 3: 0 multi, 1 value; Spin 2: 1 multi, 2 values)
+- Final win = total values × total multipliers × bet stake
+- Spins continue until all 6 complete
+
+**Trigger**: 3 or more scatter symbols land anywhere on reels during base game
+
+**Symbol Weights**: Values more common than multipliers, higher values rarer
+
+### Special Features
+
+- **Wild Symbol**: Substitutes for all symbols except scatter
+- **Progressive Meters**: Meter progress persists across spins until triggered
+- **Bonus Chaining**: Steering to Fortune can trigger other bonuses
+- **State Transitions**: Game tracks next expected spin type (base game vs bonus)
+
+## Integration Examples
+
+### Example 1: Basic RGS Integration
+
+```typescript
+import 'reflect-metadata';
+import { BonnysFortuneV1GameEngine } from '@omnitronix/bonnys-fortune-game-engine';
+
+class GameSessionService {
+  private gameEngine: BonnysFortuneV1GameEngine;
+  
+  constructor() {
+    this.gameEngine = new BonnysFortuneV1GameEngine();
+  }
+  
+  async createSession(userId: string, betAmount: number) {
+    const initCommand = {
+      id: `init-${userId}-${Date.now()}`,
+      type: 'INIT_SESSION_STATE',
+      payload: {
+        betAmountThresholds: [10, 25, 50, 100, 500, 1000, 2000],
+        defaultBetAmount: betAmount
+      }
+    };
+    
+    const result = await this.gameEngine.processCommand({}, {}, initCommand);
+    
+    // Store result.publicState in database (visible to player)
+    // Store result.privateState securely (server-side only)
+    // Store result.rngOutcome for audit trail
+    
+    return {
+      sessionId: userId,
+      publicState: result.publicState,
+      // Never send privateState to client!
+    };
+  }
+  
+  async processSpin(sessionId: string, publicState: any, privateState: any, betAmount: number) {
+    const spinCommand = {
+      id: `spin-${sessionId}-${Date.now()}`,
+      type: 'SPIN',
+      payload: {
+        sessionId,
+        betAmount,
+        gameCode: 'bonnys-fortune',
+        gameVersion: '1.0.0',
+        lines: 10,
+        creditsPerLine: betAmount / 10
+      }
+    };
+    
+    const result = await this.gameEngine.processCommand(
+      publicState,
+      privateState,
+      spinCommand
+    );
+    
+    // Update states in database
+    // Log RNG outcome for compliance
+    // Return outcome to client
+    
+    return {
+      outcome: result.outcome,
+      publicState: result.publicState,
+      rngOutcome: result.rngOutcome, // For audit
+      // privateState stays on server
+    };
+  }
+}
+```
+
+### Example 2: Handling Bonus Triggers
+
+```typescript
+async handleSpinResult(spinResult: any) {
+  const { outcome, publicState, privateState } = spinResult;
+  
+  // Check if bonus was triggered
+  if (outcome.result.triggeredBonus) {
+    const bonus = outcome.result.triggeredBonus;
+    
+    // Store pending bonus in session
+    // Notify player
+    // Wait for player to start bonus
+    
+    return {
+      type: 'BONUS_TRIGGERED',
+      bonusType: bonus.bonusType,
+      bonusId: bonus.bonusId,
+      message: 'Bonus game triggered! Click to start.',
+    };
+  }
+  
+  // Check if we should start pending bonus
+  if (privateState.pendingBonuses?.length > 0) {
+    const pendingBonus = privateState.pendingBonuses[0];
+    
+    const bonusCommand = {
+      id: `bonus-${Date.now()}`,
+      type: 'START_BONUS_ROUND',
+      payload: {
+        sessionId: spinResult.sessionId,
+        bonusType: pendingBonus.bonusType,
+        betAmount: pendingBonus.betAmount,
+        gameCode: 'bonnys-fortune',
+        gameVersion: '1.0.0',
+        bonusId: pendingBonus.bonusId
+      }
+    };
+    
+    const bonusResult = await this.gameEngine.processCommand(
+      publicState,
+      privateState,
+      bonusCommand
+    );
+    
+    return {
+      type: 'BONUS_COMPLETED',
+      results: bonusResult.outcome.results, // All bonus spins
+      totalWin: bonusResult.outcome.results.reduce(
+        (sum, r) => sum + r.result.playerWinning, 0
+      ),
+      publicState: bonusResult.publicState,
+    };
+  }
+  
+  return {
+    type: 'REGULAR_SPIN',
+    ...outcome
+  };
+}
+```
+
+### Example 3: RNG Configuration for Different Environments
+
+```typescript
+// Local development - use dummy RNG
+// .env.development
+RNG_CLIENT_MODE=local
+
+// Staging - use external RNG service
+// .env.staging
+RNG_CLIENT_MODE=external
+RNG_CLIENT_METHOD=rest
+RNG_CLIENT_URL=https://rng-staging.omnitronix.com
+RNG_CLIENT_POOL_SIZE=2000
+
+// Production - use external RNG with gRPC
+// .env.production
+RNG_CLIENT_MODE=external
+RNG_CLIENT_METHOD=grpc
+RNG_CLIENT_GRPC_URL=grpc://rng-prod.omnitronix.com:50051
+RNG_CLIENT_POOL_SIZE=5000
+```
+
+### Example 4: Testing with Debug Commands
+
+```typescript
+async function testBonusGame() {
+  const gameEngine = new BonnysFortuneV1GameEngine();
+
+  // Initialize session
+  const initResult = await gameEngine.processCommand({}, {}, {
+    id: 'test-init',
+    type: 'INIT_SESSION_STATE',
+    payload: { betAmountThresholds: [10], defaultBetAmount: 10 }
+  });
+
+  // Force trigger treasure hunt bonus
+  const debugResult = await gameEngine.processCommand(
+    initResult.publicState,
+    initResult.privateState,
+    {
+      id: 'test-debug',
+      type: 'DEBUG_TRIGGER_BONUS',
+      payload: {
+        sessionId: 'test-session',
+        bonusType: 'bonusGame1',
+        betAmount: 10
+      }
+    }
+  );
+
+  // Now start the bonus
+  const bonusResult = await gameEngine.processCommand(
+    debugResult.publicState,
+    debugResult.privateState,
+    {
+      id: 'test-bonus-start',
+      type: 'START_BONUS_ROUND',
+      payload: {
+        sessionId: 'test-session',
+        bonusType: 'bonusGame1',
+        betAmount: 10,
+        gameCode: 'bonnys-fortune',
+        gameVersion: '1.0.0',
+        bonusId: debugResult.privateState.pendingBonuses[0].bonusId
+      }
+    }
+  );
+
+  console.log('Bonus results:', bonusResult.outcome);
+}
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run with coverage
+npm run test:coverage
+```
+
+Tests use local RNG (`RNG_CLIENT_MODE=local`) automatically via `jest.setup.js`.
+
+### Building
+
+```bash
+# Clean build
+npm run clean
+npm run build
+
+# Development mode (watch)
+npm run dev
+```
+
+### Linting
+
+```bash
+# Check for issues
+npm run lint
+
+# Auto-fix issues
+npm run lint:fix
+```
+
+## Configuration
+
+Game configuration located in `src/config/game-logic-config/game-logic-config.ts`:
+- Symbol definitions and multipliers
+- Bonus game settings
+- Meter thresholds
+- Bet levels
+- RTP configuration
+
+Reel strips in `src/config/reel-strips-config/`:
+- `reels-BASE.csv` - Base game reel strips
+- `reels-BONUS.csv` - Bonus game 2 (free spins) reel strips
+
+Configuration validated on startup using class-validator.
+
+## Type Exports
+
+The package exports all necessary types for TypeScript integration:
+
+```typescript
+import {
+  BonnysFortuneV1GameEngine,
+  GameEngineInfo,
+  CommandProcessingResult,
+  GameActionCommand,
+  BonnysFortunePublicState,
+  BonnysFortunePrivateState,
+  // ... additional types as needed
+} from '@omnitronix/bonnys-fortune-game-engine';
+```
+
+## License
+
+UNLICENSED - Internal use only for Omnitronix
+
+## Support
+
+For questions or issues, contact the Omnitronix development team.