@omnitronix/happy-panda-game-engine 0.0.2 → 0.0.3

package/README.md

@@ -1,13 +1,67 @@
 # Happy Panda Game Engine
 
-![Version](https://img.shields.io/badge/version-0.0.1-blue.svg)
+![Version](https://img.shields.io/badge/version-0.0.2-blue.svg)
 ![License](https://img.shields.io/badge/license-UNLICENSED-red.svg)
-![RTP](https://img.shields.io/badge/RTP-95.91%25-green.svg)
-![C++ Parity](https://img.shields.io/badge/C++_Parity-VERIFIED-brightgreen.svg)
+![Package](https://img.shields.io/badge/package-%40omnitronix%2Fhappy--panda--game--engine-green.svg)
 
-TypeScript implementation of the Happy Red Panda (Cherry Master) slot game math model. Achieves C++ parity with the original `CherryMaster_A_2.cpp` implementation.
+Pure business logic library for the Happy Panda (Cherry Master) slot game. A framework-agnostic, TypeScript-based game engine that handles all core game mechanics, bonus systems, and jackpot logic. Achieves C++ parity with the original `CherryMaster_A_2.cpp` implementation.
 
-## C++ Parity Status - VERIFIED
+## What is Happy Panda Game Engine?
+
+The Happy Panda Game Engine is an isolated, framework-agnostic library containing pure business logic for the Happy Panda 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 pluggable RNG providers for testing and production
+- **Audit Trail**: Complete RNG outcome tracking for compliance and debugging
+- **C++ Parity**: Verified against original C++ implementation with 100M spin validation
+
+### Game Specifications
+
+- **RTP**: 96.05% (verified at 95.91% over 100M spins, within tolerance)
+- **Game Type**: Classic 3x3 Slot
+- **Version**: 1.0.0
+- **Layout**: 3 reels x 3 rows
+- **Win Evaluation**: 8/16 bidirectional paylines + wall wins + scatter wins
+- **Modes**: 8-line (SINGLE) and 16-line (BOTH)
+
+## RTP Validation Results
+
+### 100 Million Spin Verification
+
+```
+================================================================
+  HAPPY PANDA RTP VERIFICATION - 100 MILLION SPINS
+================================================================
+
+Configuration:
+  - Game Direction: SINGLE (8 lines)
+  - Bet per spin: 8
+  - Seeds: 10 x 10M = 100M total paid spins
+  - C++ Target RTP: 96.05%
+
+RTP Breakdown by Spin Type:
+----------------------------------------------------------------
+  PAID_SPIN     :  62.54% | C++: 63.51% | Diff: -0.97%
+  BONUS_JACKPOT :  16.24% | C++: 13.56% | Diff: +2.68%
+  BONUS_CHERRY  :   3.96% | C++: 3.67% | Diff: +0.29%
+  BONUS_BELL    :   5.06% | C++: 5.83% | Diff: -0.77%
+  BONUS_BAR1    :   5.47% | C++: 6.31% | Diff: -0.84%
+  RESPIN_CHERRY :   2.64% | C++: 3.18% | Diff: -0.54%
+----------------------------------------------------------------
+  TOTAL         :  95.91% | C++: 96.05%
+
+Statistics:
+  - Standard Deviation: 0.32%
+  - Range: 95.54% - 96.40%
+
+  STATUS: PASS - RTP within 0.15% tolerance
+================================================================
+```
 
 | Metric | TypeScript | C++ Target | Difference | Status |
 |--------|------------|------------|------------|--------|
@@ -21,13 +75,243 @@ TypeScript implementation of the Happy Red Panda (Cherry Master) slot game math
 
 **No configuration values from XLSX were modified** - only calculation logic was adjusted to match C++ behavior.
 
-## Game Specifications
+## Features
 
-- **RTP**: 96.05% target (95.91% achieved, -0.14% variance)
-- **Game Type**: Classic 3x3 Slot
-- **Modes**: 8-line (SINGLE) and 16-line (BOTH)
-- **Bet Stakes**: 1, 2, 5, 10, 20, 50
-- **Symbols**: 12 base symbols + special symbols
+- **Command-Based Architecture**: 3 different command types for all game operations
+- **State Management**: Public/private state separation with type safety
+- **RNG Integration**: Pluggable RNG providers with audit trail support
+- **Bidirectional Paylines**: 8 or 16 paylines with left-to-right and right-to-left evaluation
+- **Wall Wins**: Full 3x3 matrix wins with multiple types (pure, mixed, fruits, colors)
+- **Scatter Wins**: Seven symbols pay anywhere on screen
+- **Bonus System**: 5 distinct bonus types with counter-based triggers
+- **Jackpot System**: Progressive and pool jackpots
+- **TypeScript Support**: Complete type definitions for all interfaces
+- **Comprehensive Testing**: Full test suite with Jest and 100M spin RTP validation
+
+## Architecture Overview
+
+The game engine follows a modular architecture with clear separation of concerns:
+
+### Core Components
+
+- **Game Engine** (`HappyPandaEngine`): Main entry point and command processor
+- **V1 Wrapper** (`HappyPandaV1GameEngine`): Service integration wrapper with GameEngine interface
+- **Spin Generator**: Grid generation with weighted random selection
+- **Win Evaluator**: Line, wall, scatter, and special win detection
+- **Counter Manager**: Bonus counter management and trigger logic
+- **Jackpot Manager**: Progressive and pool jackpot handling
+
+### Directory Structure
+
+```
+src/
+├── happy-panda-v1.game-engine.ts  # V1 service wrapper
+├── engine/
+│   └── happy-panda-engine.ts       # Main engine class
+├── config/
+│   └── happy-panda.config.ts       # All game configuration (XLSX values)
+├── rng/
+│   ├── spin-generator.ts           # Grid generation with C++ parity
+│   └── weighted-random.ts          # Weighted random selection
+├── logic/
+│   ├── handlers/
+│   │   └── spin-handler.ts         # Spin orchestration
+│   └── services/
+│       ├── win-evaluator.ts        # Win detection (line/wall/scatter)
+│       ├── counter-manager.ts      # Bonus counter management
+│       └── jackpot-manager.ts      # Jackpot handling
+├── domain/
+│   └── types.ts                    # Type definitions
+└── __tests__/
+    ├── rtp-simulation.test.ts      # RTP validation
+    ├── rtp-diagnostic.test.ts      # RTP breakdown by spin type
+    ├── cpp-parity.test.ts          # C++ parity tests
+    └── win-evaluator.test.ts       # Win evaluation tests
+
+docs/
+├── RTP-MATCHING.md                 # RTP implementation details
+└── TEST-PROTOCOL-RTP-100M.md       # 100M spin test protocol
+```
+
+## Installation
+
+```bash
+npm install @omnitronix/happy-panda-game-engine
+```
+
+> **Note**: This is a private package for Omnitronix internal use only (UNLICENSED).
+
+## Quick Start
+
+```typescript
+import { HappyPandaV1GameEngine } from '@omnitronix/happy-panda-game-engine';
+
+// Initialize game engine
+const gameEngine = new HappyPandaV1GameEngine();
+
+// Get engine info
+const info = gameEngine.getGameEngineInfo();
+// { gameCode: 'happy-panda', version: '1.0.0', rtp: 96.05, gameType: 'slot', gameName: 'Happy Panda', provider: 'Omnitronix' }
+
+// Initialize session
+const initCommand = {
+  id: 'cmd-init-123',
+  type: 'INIT_SESSION_STATE',
+  payload: {
+    gameDirection: 0,  // 0 = SINGLE (8 lines), 1 = BOTH (16 lines)
+    betStake: 1
+  }
+};
+
+const initResult = await gameEngine.processCommand(null, null, initCommand);
+// Returns: { success: true, publicState, privateState, outcome, rngOutcome }
+
+// Process spin
+const spinCommand = {
+  id: 'cmd-spin-456',
+  type: 'SPIN',
+  payload: {}
+};
+
+const spinResult = await gameEngine.processCommand(
+  initResult.publicState,
+  initResult.privateState,
+  spinCommand
+);
+```
+
+## API Reference
+
+### Main Class: `HappyPandaV1GameEngine`
+
+Implements the standard `GameEngine` interface for integration with game-engine-service.
+
+#### Constructor
+
+```typescript
+new HappyPandaV1GameEngine()
+```
+
+- Initializes game engine with tracked RNG provider
+- Ready to process commands immediately
+
+#### Methods
+
+**`getGameEngineInfo(): GameEngineInfo`**
+Returns game metadata including code, version, RTP, and provider.
+
+```typescript
+{
+  gameCode: 'happy-panda',
+  version: '1.0.0',
+  rtp: 96.05,
+  gameType: 'slot',
+  gameName: 'Happy Panda',
+  provider: 'Omnitronix'
+}
+```
+
+**`processCommand(publicState, privateState, command): Promise<CommandProcessingResult>`**
+Main command processor that handles all game operations.
+
+### Commands
+
+The game engine supports 3 different command types:
+
+#### 1. INIT_SESSION_STATE
+
+**Purpose**: Initialize game session state
+
+**Payload**:
+```typescript
+{
+  gameDirection?: number;  // 0 = SINGLE (8 lines), 1 = BOTH (16 lines). Default: 0
+  betStake?: number;       // Bet multiplier. Default: 1
+}
+```
+
+**Returns**: Initial public and private state with default values
+
+#### 2. SPIN
+
+**Purpose**: Execute a spin
+
+**Payload**: None required (uses current state)
+
+**Returns**: Spin result with grid, wins, and state updates
+
+**Result Structure**:
+```typescript
+{
+  success: true,
+  publicState: PublicState,
+  privateState: PrivateState,
+  outcome: {
+    sessionId: string,
+    grid: Symbol[][],        // 3x3 grid
+    wins: SpinWinResult,     // All wins
+    state: PublicState,
+    jackpotWon: number,      // Jackpot payout (if any)
+    poolJackpotWon: number,  // Pool jackpot payout (if any)
+    bonusTriggered: SpinType | null,
+    isBonusComplete: boolean
+  },
+  rngOutcome: RngOutcome     // Audit trail
+}
+```
+
+#### 3. GET_SYMBOLS
+
+**Purpose**: Retrieve symbol definitions
+
+**Payload**: None
+
+**Returns**: Array of symbol definitions with names and values
+
+### State Types
+
+#### PublicState (visible to player)
+
+```typescript
+{
+  gameDirection: GameDirection;    // 0 = SINGLE, 1 = BOTH
+  betStake: number;                // Bet multiplier
+  betGame: number;                 // Total bet (8 or 16 x betStake)
+  currentSpinType: SpinType;       // Current spin type
+  spinsRemaining: number;          // Remaining bonus spins
+  grid: Symbol[][];                // Current 3x3 grid
+  bonusJackpotValue: number;       // Progressive jackpot
+  poolJackpotValue: number;        // Pool jackpot
+  hasPendingBonus: boolean;        // Indicates pending bonus
+}
+```
+
+#### PrivateState (server-side only)
+
+```typescript
+{
+  counters: BonusCounters;         // Bonus trigger counters
+  pendingBonuses: PendingBonuses;  // Queued bonuses
+  nextSpinType: SpinType;          // Next spin type
+  accumulatedBonusWins: number;    // Bonus sequence wins
+  centerCherrySymbol: Symbol | null; // For respin feature
+}
+```
+
+#### CommandProcessingResult
+
+```typescript
+{
+  success: boolean;
+  publicState: PublicState;
+  privateState: PrivateState;
+  outcome?: SpinResponse;
+  message?: string;
+  rngOutcome?: RngOutcome;  // RNG audit trail
+}
+```
+
+## Game Mechanics
 
 ### Symbol Set
 
@@ -46,148 +330,336 @@ TypeScript implementation of the Happy Red Panda (Cherry Master) slot game math
 | 10 | CH_S | Cherry Special |
 | 11 | BA_S | Super Bar |
 
-## Win Types
+### Win Types
+
+#### 1. Line Wins
 
-### 1. Line Wins
-- 8 paylines (8-line mode) or 16 paylines (16-line mode)
+- 8 paylines (SINGLE mode) or 16 paylines (BOTH mode)
 - Evaluated left-to-right and right-to-left in 16-line mode
 - Cherry pays on 1, 2, or 3 matches
+- Line shapes follow classic 3x3 patterns
 
-### 2. Wall Wins (Matrix/Screen Wins)
-- Full 3x3 of same symbol (or mixed for special types)
-- Types: Pure symbol, Cherry mix (CH+CH_S), Any Bar mix, All Fruits, All Colors
-- **Suppresses** line wins when active
+#### 2. Wall Wins (Matrix/Screen Wins)
+
+- Full 3x3 of same symbol
+- Special mixed types:
+  - **Cherry Mix**: CH + CH_S combinations
+  - **Any Bar Mix**: BA1 + BA2 + BA3 + BA_S
+  - **All Fruits**: ME + BE + PR + OR
+  - **All Colors**: Mixed symbol colors
+- **Important**: Wall wins suppress line wins when active
+
+#### 3. Scatter Wins (Seven)
 
-### 3. Scatter Wins (Seven)
 - 2-9 Seven symbols anywhere on screen
 - Super Seven only = doubled payout
-- **Suppresses** line wins when active
+- **Important**: Scatter wins suppress line wins when active
+
+#### 4. Special Wins (Bonus modes only)
 
-### 4. Special Wins (Bonus modes only)
-- Cherry pieces (Jackpot Bonus)
-- Bell scatter (Bell Bonus)
-- Super Bar scatter (Bar1 Bonus)
+- **Cherry Pieces**: Count of cherry pieces (Jackpot Bonus)
+- **Bell Scatter**: Bell count anywhere (Bell Bonus)
+- **Super Bar Scatter**: Super Bar count anywhere (Bar1 Bonus)
 
-## Bonus System
+### Bonus System
 
-### Bonus Types
+Five distinct bonus types with counter-based triggers:
 
-| Bonus | Trigger | Description |
-|-------|---------|-------------|
-| Jackpot | 3x Cherry on first 8 lines | Cherry pieces with jackpot chance |
-| Cherry | Cherry pair counter reaches 0 | Cherry respin feature |
-| Bell | Bell triple counter reaches 0 | Bell scatter pays |
-| Bar1 | Bar1 triple counter reaches 0 | Super Bar scatter pays |
-| Respin | Lone center cherry on losing spin | 1-2 corner respins |
+| Bonus | Trigger | Spins | Description |
+|-------|---------|-------|-------------|
+| **Jackpot** | 3x Cherry on first 8 lines | 3 | Cherry pieces with progressive jackpot chance |
+| **Cherry** | Cherry pair counter = 0 | Variable | Cherry respin feature |
+| **Bell** | Bell triple counter = 0 | 5 | Bell scatter pays + pool jackpot |
+| **Bar1** | Bar1 triple counter = 0 | 7 | Super Bar scatter pays |
+| **Respin** | Lone center cherry on losing spin | 1-2 | Corner respin feature |
 
 ### Counter System
-- Counters decrement on specific symbol combinations
-- When counter reaches 0, bonus triggers
-- Each bonus has different spin allocation
 
-## Project Structure
+Each bonus has an associated counter that decrements on specific symbol combinations:
 
-```
-src/
-├── engine/
-│   └── happy-panda-engine.ts    # Main engine class
-├── config/
-│   └── happy-panda.config.ts    # All game configuration (XLSX values)
-├── rng/
-│   ├── spin-generator.ts        # Grid generation with C++ parity
-│   └── weighted-random.ts       # Weighted random selection
-├── logic/
-│   ├── handlers/
-│   │   └── spin-handler.ts      # Spin orchestration
-│   └── services/
-│       ├── win-evaluator.ts     # Win detection
-│       └── counter-manager.ts   # Bonus counter management
-├── domain/
-│   └── types.ts                 # Type definitions
-└── __tests__/
-    ├── rtp-simulation.test.ts   # RTP validation
-    ├── rtp-diagnostic.test.ts   # RTP breakdown by spin type
-    └── cpp-parity.test.ts       # C++ parity tests
+- **Jackpot Counter**: Decrements on specific patterns, triggers at 0
+- **Cherry Counter**: Decrements on cherry pairs, resets to 6 or 9
+- **Bell Counter**: Decrements on bell triples, resets to 3 or 5
+- **Bar1 Counter**: Decrements on bar1 triples, resets to 1
 
-docs/
-├── RTP-MATCHING.md              # RTP implementation details
-└── TEST-PROTOCOL-RTP-100M.md    # 100M spin test protocol
+### Jackpot System
+
+Two jackpot types:
+
+- **Progressive Jackpot** (`bonusJackpotValue`): Accumulates on losing paid spins, paid during Jackpot Bonus
+- **Pool Jackpot** (`poolJackpotValue`): Accumulates separately, paid when Bell Bonus triggers
+
+## Integration Examples
+
+### Example 1: Basic RGS Integration
+
+```typescript
+import { HappyPandaV1GameEngine } from '@omnitronix/happy-panda-game-engine';
+
+class GameSessionService {
+  private gameEngine: HappyPandaV1GameEngine;
+
+  constructor() {
+    this.gameEngine = new HappyPandaV1GameEngine();
+  }
+
+  async createSession(userId: string, gameDirection: number, betStake: number) {
+    const initCommand = {
+      id: `init-${userId}-${Date.now()}`,
+      type: 'INIT_SESSION_STATE',
+      payload: { gameDirection, betStake }
+    };
+
+    const result = await this.gameEngine.processCommand(null, null, 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) {
+    const spinCommand = {
+      id: `spin-${sessionId}-${Date.now()}`,
+      type: 'SPIN',
+      payload: {}
+    };
+
+    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
+    };
+  }
+}
 ```
 
-## Usage
+### Example 2: Handling Bonus Triggers
 
 ```typescript
-import { HappyPandaEngine } from '@omnitronix/happy-panda-game-engine';
-import { CommandType, GameDirection } from '@omnitronix/happy-panda-game-engine';
+async handleSpinResult(spinResult: any) {
+  const { outcome, publicState, privateState } = spinResult;
+
+  // Check win types
+  console.log(`Total Payout: ${outcome.wins.totalPayout}`);
+  console.log(`Line Wins: ${outcome.wins.lineWins.length}`);
+  console.log(`Wall Win: ${outcome.wins.wallWin ? 'Yes' : 'No'}`);
+  console.log(`Scatter Wins: ${outcome.wins.scatterWins.length}`);
+
+  // Check for jackpot
+  if (outcome.jackpotWon > 0) {
+    console.log(`JACKPOT WON: ${outcome.jackpotWon}`);
+  }
+
+  if (outcome.poolJackpotWon > 0) {
+    console.log(`POOL JACKPOT WON: ${outcome.poolJackpotWon}`);
+  }
+
+  // Check if bonus was triggered
+  if (outcome.bonusTriggered) {
+    return {
+      type: 'BONUS_TRIGGERED',
+      bonusType: outcome.bonusTriggered,
+      spinsRemaining: publicState.spinsRemaining,
+      message: `${outcome.bonusTriggered} bonus triggered!`
+    };
+  }
+
+  // Check if bonus sequence completed
+  if (outcome.isBonusComplete) {
+    return {
+      type: 'BONUS_COMPLETE',
+      message: 'Bonus sequence completed'
+    };
+  }
+
+  return {
+    type: 'REGULAR_SPIN',
+    totalPayout: outcome.wins.totalPayout
+  };
+}
+```
 
-// Create engine with RNG provider
-const engine = new HappyPandaEngine(rngProvider);
+### Example 3: Game Direction Modes
 
-// Initialize session
-const { state } = await engine.handleCommand({
-  command: CommandType.INIT_SESSION_STATE,
-  sessionId: 'session-123',
-  gameDirection: GameDirection.SINGLE, // 8-line mode
-  betStake: 1,
+```typescript
+// 8-line mode (SINGLE)
+const single8Lines = await gameEngine.processCommand(null, null, {
+  id: 'init-single',
+  type: 'INIT_SESSION_STATE',
+  payload: { gameDirection: 0, betStake: 1 }
 });
+// Total bet = 8 x betStake = 8
 
-// Execute spin
-const { state: newState, response } = await engine.handleCommand(
-  { command: CommandType.SPIN, sessionId: 'session-123' },
-  state
-);
-
-console.log(response.wins.totalPayout);
-console.log(response.grid);
+// 16-line mode (BOTH)
+const both16Lines = await gameEngine.processCommand(null, null, {
+  id: 'init-both',
+  type: 'INIT_SESSION_STATE',
+  payload: { gameDirection: 1, betStake: 1 }
+});
+// Total bet = 16 x betStake = 16
 ```
 
-## Testing
+## Development
+
+### Running Tests
 
 ```bash
 # Run all tests
 npm test
 
+# Run tests in watch mode
+npm run test:watch
+
+# Run with coverage
+npm run test:cov
+
 # Run RTP diagnostic (100K spins)
 npm test -- --testNamePattern="RTP Diagnostic"
 
-# Run specific test file
-npm test -- --testPathPattern="rtp-simulation"
+# Run C++ parity tests
+npm test -- --testPathPattern="cpp-parity"
 ```
 
-## RTP Validation Results
+### Building
 
-### 100 Million Spin Simulation
+```bash
+# Clean build
+npm run clean
+npm run build
 
+# Development mode
+npm run build
 ```
-================================================================
-  HAPPY PANDA RTP VERIFICATION - 100 MILLION SPINS
-================================================================
 
-Configuration:
-  - Game Direction: SINGLE (8 lines)
-  - Bet per spin: 8
-  - Seeds: 10 x 10M = 100M total paid spins
-  - C++ Target RTP: 96.05%
+### Linting
 
-RTP Breakdown by Spin Type:
-----------------------------------------------------------------
-  PAID_SPIN     :  62.54% | C++: 63.51% | Diff: -0.97%
-  BONUS_JACKPOT :  16.24% | C++: 13.56% | Diff: +2.68%
-  BONUS_CHERRY  :   3.96% | C++: 3.67% | Diff: +0.29%
-  BONUS_BELL    :   5.06% | C++: 5.83% | Diff: -0.77%
-  BONUS_BAR1    :   5.47% | C++: 6.31% | Diff: -0.84%
-  RESPIN_CHERRY :   2.64% | C++: 3.18% | Diff: -0.54%
-----------------------------------------------------------------
-  TOTAL         :  95.91% | C++: 96.05%
+```bash
+# Check for issues
+npm run lint
 
-Statistics:
-  - Standard Deviation: 0.32%
-  - Range: 95.54% - 96.40%
+# Auto-fix issues
+npm run lint -- --fix
+```
 
-  STATUS: PASS - RTP within 0.15% tolerance
-================================================================
+## Configuration
+
+Game configuration located in `src/config/happy-panda.config.ts`:
+
+- Symbol definitions and IDs
+- Paytable values for all win types
+- Line shapes for 8 and 16 line modes
+- Reel strip weights by spin type
+- Bonus counter initial values
+- Jackpot accumulation rates
+
+All values match the original Excel specification (`CherryMaster_A_2_26.05.2025.xlsx`).
+
+## Type Exports
+
+The package exports all necessary types for TypeScript integration:
+
+```typescript
+import {
+  // V1 Game Engine
+  HappyPandaV1GameEngine,
+  GameEngine,
+  GameEngineInfo,
+  GameActionCommand,
+  CommandProcessingResult,
+  RngOutcome,
+  RngOutcomeRecord,
+
+  // Core Engine
+  HappyPandaEngine,
+
+  // Configuration
+  Symbol,
+  SpinType,
+  ScreenWinType,
+  GRID,
+  LINE_SHAPES,
+  LINES_PER_DIRECTION,
+
+  // Domain Types
+  Grid,
+  Position,
+  LineWin,
+  WallWin,
+  ScatterWin,
+  SpecialWin,
+  SpinWinResult,
+  BonusCounters,
+  PendingBonuses,
+  JackpotState,
+  GameDirection,
+  GameState,
+  PublicState,
+  PrivateState,
+  SpinRequest,
+  SpinResponse,
+  SessionState,
+  RngProvider,
+  CommandType,
+  GameCommand,
+
+  // Logic Services
+  evaluateSpin,
+  evaluateLineWins,
+  evaluateWallWin,
+  evaluateScatterWins,
+  generateGrid,
+} from '@omnitronix/happy-panda-game-engine';
 ```
 
+## Key Differences from Traditional Slots
+
+### Classic 3x3 Layout
+
+- **Traditional Modern**: 5+ reels, multiple rows
+- **Happy Panda**: Classic 3x3 grid with bidirectional paylines
+- **Advantage**: Nostalgic gameplay, simpler visual presentation
+
+### Bidirectional Paylines
+
+- **8-Line Mode**: Left-to-right only
+- **16-Line Mode**: Both directions (LTR + RTL)
+- **Strategic Choice**: Player chooses mode based on bet preference
+
+### Wall Wins (Matrix Wins)
+
+- **Screen-filling wins**: Full 3x3 of same/related symbols
+- **Multiple types**: Pure, cherry mix, bar mix, fruits, colors
+- **Important**: Wall wins suppress line wins (no double-counting)
+
+### Counter-Based Bonuses
+
+- **Not scatter-triggered**: Bonuses trigger via counter depletion
+- **Progressive build-up**: Counters decrement on specific symbol combos
+- **Multiple bonus types**: 5 distinct bonus modes with different mechanics
+
+### Dual Jackpot System
+
+- **Progressive Jackpot**: Accumulates on losses, paid in Jackpot Bonus
+- **Pool Jackpot**: Separate accumulator, paid with Bell Bonus
+- **Dual opportunity**: Two paths to jackpot wins
+
 ## Documentation
 
 - **Test Protocol**: `docs/TEST-PROTOCOL-RTP-100M.md` - Complete 100M spin test results
@@ -195,18 +667,10 @@ Statistics:
 - **C++ Source**: `math/Happy Red Panda/CherryMaster_A_2.cpp`
 - **Excel Spec**: `math/Happy Red Panda/CherryMaster_A_2_26.05.2025.xlsx`
 
-## Installation
-
-```bash
-npm install @omnitronix/happy-panda-game-engine
-```
-
-## Build
-
-```bash
-npm run build
-```
-
 ## License
 
 UNLICENSED - Internal use only for Omnitronix
+
+## Support
+
+For questions or issues, contact the Omnitronix development team.

package/dist/happy-panda-v1.game-engine.js

@@ -4,36 +4,35 @@
  *
  * Wrapper class that adapts HappyPandaEngine to the standard GameEngine interface
  * expected by the game-engine-service infrastructure.
+ *
+ * Uses the proper RNG infrastructure matching Heroes of Aether and Bonny's Fortune:
+ * - RngClientFactory for environment-based client selection
+ * - RngService for audit trail tracking
+ * - Full RNG outcome reporting for compliance
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HappyPandaV1GameEngine = void 0;
 const happy_panda_engine_1 = require("./engine/happy-panda-engine");
 const types_1 = require("./domain/types");
+const rng_client_factory_1 = require("./rng/rng-client.factory");
+const rng_service_1 = require("./rng/rng-service");
 /**
- * RNG adapter that tracks outcomes for the game engine service
+ * RNG Provider adapter that bridges RngService to the engine's RngProvider interface
  */
-class TrackedRngProvider {
-    constructor() {
-        this.outcomes = new Map();
+class RngServiceAdapter {
+    constructor(rngService) {
+        this.rngService = rngService;
         this.currentCommandId = '';
-        this.seedCounter = 0;
+        this.actionCounter = 0;
     }
     setCommandId(commandId) {
         this.currentCommandId = commandId;
-        if (!this.outcomes.has(commandId)) {
-            this.outcomes.set(commandId, []);
-        }
+        this.actionCounter = 0;
     }
     async random(max) {
-        const result = Math.floor(Math.random() * max);
-        const record = {
-            result,
-            seed: this.seedCounter++,
-            min: 0,
-            max: max - 1,
-        };
-        this.outcomes.get(this.currentCommandId)?.push(record);
-        return result;
+        const actionId = `rng_${this.actionCounter++}`;
+        const { value } = await this.rngService.getSingleNumber(0, max - 1, this.currentCommandId, actionId);
+        return value;
     }
     async randomBatch(count, max) {
         const results = [];
@@ -42,33 +41,29 @@ class TrackedRngProvider {
         }
         return results;
     }
-    getOutcomes(commandId) {
-        const records = this.outcomes.get(commandId) || [];
-        const outcome = {};
-        records.forEach((record, index) => {
-            outcome[`rng_${index}`] = record;
-        });
-        return outcome;
-    }
-    clearOutcomes(commandId) {
-        this.outcomes.delete(commandId);
-    }
 }
 /**
  * Happy Panda V1 Game Engine
  *
  * Implements the standard GameEngine interface for use with game-engine-service.
+ * Uses proper RNG infrastructure with full audit trail support.
  */
 class HappyPandaV1GameEngine {
-    constructor() {
+    constructor(config = {}) {
         this.gameCode = 'happy-panda';
         this.version = '1.0.0';
         this.rtp = 96.05;
         this.gameType = 'slot';
         this.gameName = 'Happy Panda';
         this.provider = 'Omnitronix';
-        this.rngProvider = new TrackedRngProvider();
-        this.engine = new happy_panda_engine_1.HappyPandaEngine(this.rngProvider);
+        // Create RNG client based on environment (local for dev, external for prod)
+        const rngClient = rng_client_factory_1.RngClientFactory.create({ metrics: config.metrics });
+        // Wrap in service for audit trail tracking
+        this.rngService = new rng_service_1.RngService(rngClient);
+        // Create adapter to bridge to engine's RngProvider interface
+        this.rngAdapter = new RngServiceAdapter(this.rngService);
+        // Initialize engine with RNG adapter
+        this.engine = new happy_panda_engine_1.HappyPandaEngine(this.rngAdapter);
     }
     getGameEngineInfo() {
         return {
@@ -81,7 +76,9 @@ class HappyPandaV1GameEngine {
         };
     }
     async processCommand(publicState, privateState, command) {
-        this.rngProvider.setCommandId(command.id);
+        // Register command for RNG audit trail
+        this.rngService.registerCommand(command.id);
+        this.rngAdapter.setCommandId(command.id);
         try {
             switch (command.type) {
                 case 'INIT_SESSION_STATE': {
@@ -94,8 +91,8 @@ class HappyPandaV1GameEngine {
                         gameDirection,
                         betStake,
                     });
-                    const rngOutcome = this.rngProvider.getOutcomes(command.id);
-                    this.rngProvider.clearOutcomes(command.id);
+                    const rngOutcome = this.rngService.getRngOutcomeForCommand(command.id);
+                    this.rngService.removeCommand(command.id);
                     return {
                         success: true,
                         publicState: result.state.publicState,
@@ -107,6 +104,7 @@ class HappyPandaV1GameEngine {
                 }
                 case 'SPIN': {
                     if (!publicState || !privateState) {
+                        this.rngService.removeCommand(command.id);
                         return {
                             success: false,
                             publicState: publicState,
@@ -126,8 +124,8 @@ class HappyPandaV1GameEngine {
                         command: types_1.CommandType.SPIN,
                         sessionId: command.id,
                     }, sessionState);
-                    const rngOutcome = this.rngProvider.getOutcomes(command.id);
-                    this.rngProvider.clearOutcomes(command.id);
+                    const rngOutcome = this.rngService.getRngOutcomeForCommand(command.id);
+                    this.rngService.removeCommand(command.id);
                     return {
                         success: true,
                         publicState: result.state.publicState,
@@ -142,7 +140,7 @@ class HappyPandaV1GameEngine {
                         command: types_1.CommandType.GET_SYMBOLS,
                         sessionId: command.id,
                     });
-                    this.rngProvider.clearOutcomes(command.id);
+                    this.rngService.removeCommand(command.id);
                     return {
                         success: true,
                         publicState: publicState,
@@ -152,7 +150,7 @@ class HappyPandaV1GameEngine {
                     };
                 }
                 default: {
-                    this.rngProvider.clearOutcomes(command.id);
+                    this.rngService.removeCommand(command.id);
                     return {
                         success: false,
                         publicState: publicState,
@@ -163,7 +161,7 @@ class HappyPandaV1GameEngine {
             }
         }
         catch (error) {
-            this.rngProvider.clearOutcomes(command.id);
+            this.rngService.removeCommand(command.id);
             return {
                 success: false,
                 publicState: publicState,

package/dist/happy-panda-v1.game-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"happy-panda-v1.game-engine.js","sourceRoot":"","sources":["../src/happy-panda-v1.game-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"happy-panda-v1.game-engine.js","sourceRoot":"","sources":["../src/happy-panda-v1.game-engine.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -7,7 +7,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateGrid = exports.evaluateScatterWins = exports.evaluateWallWin = exports.evaluateLineWins = exports.evaluateSpin = exports.CommandType = exports.GameDirection = exports.LINES_PER_DIRECTION = exports.LINE_SHAPES = exports.GRID = exports.ScreenWinType = exports.SpinType = exports.Symbol = exports.HappyPandaEngine = exports.HappyPandaV1GameEngine = void 0;
+exports.RngService = exports.RngClientFactory = exports.DummyRngClient = exports.generateGrid = exports.evaluateScatterWins = exports.evaluateWallWin = exports.evaluateLineWins = exports.evaluateSpin = exports.CommandType = exports.GameDirection = exports.LINES_PER_DIRECTION = exports.LINE_SHAPES = exports.GRID = exports.ScreenWinType = exports.SpinType = exports.Symbol = exports.HappyPandaEngine = exports.HappyPandaV1GameEngine = void 0;
 // V1 Game Engine (for game-engine-service integration)
 var happy_panda_v1_game_engine_1 = require("./happy-panda-v1.game-engine");
 Object.defineProperty(exports, "HappyPandaV1GameEngine", { enumerable: true, get: function () { return happy_panda_v1_game_engine_1.HappyPandaV1GameEngine; } });
@@ -34,4 +34,10 @@ Object.defineProperty(exports, "evaluateWallWin", { enumerable: true, get: funct
 Object.defineProperty(exports, "evaluateScatterWins", { enumerable: true, get: function () { return services_1.evaluateScatterWins; } });
 var rng_1 = require("./rng");
 Object.defineProperty(exports, "generateGrid", { enumerable: true, get: function () { return rng_1.generateGrid; } });
+var dummy_rng_client_1 = require("./rng/dummy-rng-client");
+Object.defineProperty(exports, "DummyRngClient", { enumerable: true, get: function () { return dummy_rng_client_1.DummyRngClient; } });
+var rng_client_factory_1 = require("./rng/rng-client.factory");
+Object.defineProperty(exports, "RngClientFactory", { enumerable: true, get: function () { return rng_client_factory_1.RngClientFactory; } });
+var rng_service_1 = require("./rng/rng-service");
+Object.defineProperty(exports, "RngService", { enumerable: true, get: function () { return rng_service_1.RngService; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,uDAAuD;AACvD,2EAAsE;AAA7D,oIAAA,sBAAsB,OAAA;AAU/B,cAAc;AACd,mCAA4C;AAAnC,0GAAA,gBAAgB,OAAA;AAEzB,gBAAgB;AAChB,mCAOkB;AANhB,gGAAA,MAAM,OAAA;AACN,kGAAA,QAAQ,OAAA;AACR,uGAAA,aAAa,OAAA;AACb,8FAAA,IAAI,OAAA;AACJ,qGAAA,WAAW,OAAA;AACX,6GAAA,mBAAmB,OAAA;AAGrB,eAAe;AACf,mCAwBkB;AAbhB,uGAAA,aAAa,OAAA;AAQb,qGAAA,WAAW,OAAA;AAOb,yCAAyC;AACzC,6CAAwG;AAA/F,wGAAA,YAAY,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,2GAAA,eAAe,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAC7E,6BAAqC;AAA5B,mGAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,uDAAuD;AACvD,2EAAsE;AAA7D,oIAAA,sBAAsB,OAAA;AAU/B,cAAc;AACd,mCAA4C;AAAnC,0GAAA,gBAAgB,OAAA;AAEzB,gBAAgB;AAChB,mCAOkB;AANhB,gGAAA,MAAM,OAAA;AACN,kGAAA,QAAQ,OAAA;AACR,uGAAA,aAAa,OAAA;AACb,8FAAA,IAAI,OAAA;AACJ,qGAAA,WAAW,OAAA;AACX,6GAAA,mBAAmB,OAAA;AAGrB,eAAe;AACf,mCAwBkB;AAbhB,uGAAA,aAAa,OAAA;AAQb,qGAAA,WAAW,OAAA;AAOb,yCAAyC;AACzC,6CAAwG;AAA/F,wGAAA,YAAY,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,2GAAA,eAAe,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAC7E,6BAAqC;AAA5B,mGAAA,YAAY,OAAA;AAQrB,2DAAwD;AAA/C,kHAAA,cAAc,OAAA;AACvB,+DAA6E;AAApE,sHAAA,gBAAgB,OAAA;AACzB,iDAA+C;AAAtC,yGAAA,UAAU,OAAA"}

package/dist/rng/dummy-rng-client.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Dummy RNG Client
+ *
+ * Local RNG client for development and testing.
+ * Uses Math.random() for all operations.
+ * Returns seed value of 0 (non-cryptographic, for testing only).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DummyRngClient = void 0;
+class DummyRngClient {
+    /**
+     * Generate a single random integer in range [min, max]
+     */
+    async getSingleNumber(min, max, _seed) {
+        const randomValue = Math.random();
+        const result = Math.floor(randomValue * (max - min + 1)) + min;
+        return { value: result, seed: 0 };
+    }
+    /**
+     * Generate multiple random integers in range [min, max]
+     */
+    async getBatchNumbers(min, max, count, _seed) {
+        const results = [];
+        for (let i = 0; i < count; i++) {
+            const randomValue = Math.random();
+            results.push(Math.floor(randomValue * (max - min + 1)) + min);
+        }
+        return results;
+    }
+    /**
+     * Generate multiple random integers with individual seeds
+     */
+    async getBatchNumbersWithSeeds(min, max, count, _seed) {
+        const results = [];
+        for (let i = 0; i < count; i++) {
+            const randomValue = Math.random();
+            results.push({
+                value: Math.floor(randomValue * (max - min + 1)) + min,
+                seed: 0,
+            });
+        }
+        return results;
+    }
+    /**
+     * Generate a single random float in range [0, 1)
+     */
+    async getSingleFloat(_seed) {
+        return { value: Math.random(), seed: 0 };
+    }
+    /**
+     * Generate multiple random floats in range [0, 1)
+     */
+    async getBatchFloats(count, _seed) {
+        const values = [];
+        const seeds = [];
+        for (let i = 0; i < count; i++) {
+            values.push(Math.random());
+            seeds.push(0);
+        }
+        return { values, seeds };
+    }
+    /**
+     * Alternative method for single random number
+     */
+    async getRandomNumber(min, max, _seed) {
+        return this.getSingleNumber(min, max, _seed);
+    }
+    /**
+     * Alternative method for single random float
+     */
+    async getRandomFloat(_seed) {
+        return this.getSingleFloat(_seed);
+    }
+}
+exports.DummyRngClient = DummyRngClient;
+//# sourceMappingURL=dummy-rng-client.js.map

package/dist/rng/dummy-rng-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dummy-rng-client.js","sourceRoot":"","sources":["../../src/rng/dummy-rng-client.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAQH,MAAa,cAAc;IACzB;;OAEG;IACH,KAAK,CAAC,eAAe,CACnB,GAAW,EACX,GAAW,EACX,KAAc;QAEd,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;QAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CACnB,GAAW,EACX,GAAW,EACX,KAAa,EACb,KAAc;QAEd,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,wBAAwB,CAC5B,GAAW,EACX,GAAW,EACX,KAAa,EACb,KAAc;QAEd,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC;gBACX,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG;gBACtD,IAAI,EAAE,CAAC;aACR,CAAC,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,KAAc;QACjC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAClB,KAAa,EACb,KAAc;QAEd,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CACnB,GAAW,EACX,GAAW,EACX,KAAc;QAEd,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,KAAc;QACjC,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;CACF;AA3FD,wCA2FC"}

package/dist/rng/index.js

@@ -19,4 +19,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 __exportStar(require("./weighted-random"), exports);
 __exportStar(require("./spin-generator"), exports);
+// RNG Service and Client Infrastructure
+__exportStar(require("./rng-client.interface"), exports);
+__exportStar(require("./dummy-rng-client"), exports);
+__exportStar(require("./rng-client.factory"), exports);
+__exportStar(require("./rng-service"), exports);
 //# sourceMappingURL=index.js.map

package/dist/rng/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rng/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;GAEG;AACH,oDAAkC;AAClC,mDAAiC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rng/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;GAEG;AACH,oDAAkC;AAClC,mDAAiC;AAEjC,wCAAwC;AACxC,yDAAuC;AACvC,qDAAmC;AACnC,uDAAqC;AACrC,gDAA8B"}

package/dist/rng/rng-client.factory.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * RNG Client Factory
+ *
+ * Factory pattern for creating RNG clients based on environment configuration.
+ * Matches the pattern used in Heroes of Aether and Bonny's Fortune.
+ *
+ * Environment Variables:
+ * - RNG_CLIENT_MODE: 'local' (DummyRngClient) or 'external' (production RngClient)
+ * - RNG_CLIENT_URL: HTTP endpoint for external RNG service
+ * - RNG_CLIENT_GRPC_URL: gRPC endpoint for external RNG service
+ * - RNG_CLIENT_METHOD: 'grpc' or 'rest'
+ * - RNG_CLIENT_POOL_SIZE: Ring buffer pool size (default: 2000)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RngClientFactory = void 0;
+const dummy_rng_client_1 = require("./dummy-rng-client");
+class RngClientFactory {
+    /**
+     * Create an RNG client based on environment configuration.
+     *
+     * @param config Optional configuration overrides
+     * @returns IRngClient instance (DummyRngClient for local, external client for production)
+     */
+    static create(config = {}) {
+        const mode = process.env.RNG_CLIENT_MODE || 'external';
+        if (mode === 'local') {
+            console.log('[RngClientFactory] Creating DummyRngClient (local mode)');
+            return new dummy_rng_client_1.DummyRngClient();
+        }
+        // For external mode, we would use @omnitronix/rng-client-core
+        // For now, fall back to DummyRngClient if external client not available
+        console.log('[RngClientFactory] External RNG mode requested');
+        const rngClientConfig = {
+            serverUrl: process.env.RNG_CLIENT_URL,
+            grpcUrl: process.env.RNG_CLIENT_GRPC_URL,
+            clientMethod: process.env.RNG_CLIENT_METHOD,
+            poolingSize: parseInt(process.env.RNG_CLIENT_POOL_SIZE || '2000'),
+            metrics: config.metrics,
+        };
+        // Try to load external RNG client
+        try {
+            // Dynamic import to avoid hard dependency
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { RngClient } = require('@omnitronix/rng-client-core');
+            console.log('[RngClientFactory] Creating external RngClient');
+            return new RngClient(rngClientConfig);
+        }
+        catch (error) {
+            console.warn('[RngClientFactory] @omnitronix/rng-client-core not available, falling back to DummyRngClient');
+            console.warn('[RngClientFactory] Install @omnitronix/rng-client-core for production use');
+            return new dummy_rng_client_1.DummyRngClient();
+        }
+    }
+}
+exports.RngClientFactory = RngClientFactory;
+//# sourceMappingURL=rng-client.factory.js.map

package/dist/rng/rng-client.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng-client.factory.js","sourceRoot":"","sources":["../../src/rng/rng-client.factory.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAGH,yDAAoD;AAUpD,MAAa,gBAAgB;IAC3B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,SAAgC,EAAE;QAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,UAAU,CAAC;QAEvD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;YACvE,OAAO,IAAI,iCAAc,EAAE,CAAC;QAC9B,CAAC;QAED,8DAA8D;QAC9D,wEAAwE;QACxE,OAAO,CAAC,GAAG,CAAC,gDAAgD,CAAC,CAAC;QAE9D,MAAM,eAAe,GAAoB;YACvC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;YACrC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;YACxC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAoC;YAC9D,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,MAAM,CAAC;YACjE,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC;QAEF,kCAAkC;QAClC,IAAI,CAAC;YACH,0CAA0C;YAC1C,8DAA8D;YAC9D,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAAC;YAC7D,OAAO,CAAC,GAAG,CAAC,gDAAgD,CAAC,CAAC;YAC9D,OAAO,IAAI,SAAS,CAAC,eAAe,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CACV,8FAA8F,CAC/F,CAAC;YACF,OAAO,CAAC,IAAI,CACV,2EAA2E,CAC5E,CAAC;YACF,OAAO,IAAI,iCAAc,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;CACF;AA5CD,4CA4CC"}

package/dist/rng/rng-client.interface.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * RNG Client Interface
+ *
+ * Contract for all RNG clients (local and external).
+ * Matches the pattern used in Heroes of Aether and Bonny's Fortune.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=rng-client.interface.js.map

package/dist/rng/rng-client.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng-client.interface.js","sourceRoot":"","sources":["../../src/rng/rng-client.interface.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/rng/rng-service.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * RNG Service
+ *
+ * Core RNG service with audit trail tracking for compliance.
+ * Wraps an IRngClient and tracks all RNG outcomes per command.
+ * Matches the pattern used in Heroes of Aether and Bonny's Fortune.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RngService = void 0;
+/**
+ * RNG Service
+ *
+ * Provides RNG operations with full audit trail tracking.
+ * Each command ID can have multiple action IDs, allowing fine-grained tracking
+ * of all RNG calls within a single game command.
+ */
+class RngService {
+    constructor(rngClient) {
+        this.rngClient = rngClient;
+        this.rngOutcomes = {};
+    }
+    /**
+     * Register a command for RNG tracking.
+     * Call this at the start of command processing.
+     */
+    registerCommand(commandId) {
+        if (!this.rngOutcomes[commandId]) {
+            this.rngOutcomes[commandId] = {};
+        }
+    }
+    /**
+     * Remove a command's RNG outcomes.
+     * Call this after command processing to clean up.
+     */
+    removeCommand(commandId) {
+        delete this.rngOutcomes[commandId];
+    }
+    /**
+     * Check if a command has RNG outcomes
+     */
+    hasCommandRngOutcome(commandId) {
+        return !!this.rngOutcomes[commandId];
+    }
+    /**
+     * Get the count of RNG outcomes for a command
+     */
+    getRngOutcomeCountForCommand(commandId) {
+        const outcomes = this.rngOutcomes[commandId];
+        return outcomes ? Object.keys(outcomes).length : 0;
+    }
+    /**
+     * Store an RNG outcome for audit trail
+     */
+    storeSeedForCommand(commandId, actionId, result, seed, min, max) {
+        this.registerCommand(commandId);
+        this.rngOutcomes[commandId][actionId] = { result, seed, min, max };
+    }
+    /**
+     * Get cached seed for a command/action (for replay scenarios)
+     */
+    getSeedForCommand(commandId, actionId) {
+        return this.rngOutcomes[commandId]?.[actionId]?.seed;
+    }
+    /**
+     * Get all RNG outcomes for a command
+     */
+    getRngOutcomeForCommand(commandId) {
+        return this.rngOutcomes[commandId] || {};
+    }
+    /**
+     * Get all RNG outcomes across all commands
+     */
+    getAllRngOutcome() {
+        return { ...this.rngOutcomes };
+    }
+    /**
+     * Generate a single random integer in range [min, max]
+     * Tracks the outcome for audit trail
+     */
+    async getSingleNumber(min, max, commandId, actionId) {
+        // Check if we already have a cached result (for replay)
+        const existingSeed = this.getSeedForCommand(commandId, actionId);
+        if (existingSeed !== undefined) {
+            const existingResult = this.rngOutcomes[commandId][actionId];
+            return { value: existingResult.result, seed: existingResult.seed };
+        }
+        // Generate new random number
+        const response = await this.rngClient.getSingleNumber(min, max);
+        // Store for audit trail
+        this.storeSeedForCommand(commandId, actionId, response.value, response.seed, min, max);
+        return response;
+    }
+    /**
+     * Generate multiple random integers in range [min, max]
+     * Each number is tracked individually with incrementing action IDs
+     */
+    async getBatchNumbers(min, max, count, commandId, actionId) {
+        const results = [];
+        for (let i = 0; i < count; i++) {
+            const result = await this.getSingleNumber(min, max, commandId, `${actionId}_${i}`);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Generate a weighted random selection
+     * Returns the index selected based on weights
+     */
+    async getWeightedRandomIndex(weights, commandId, actionId) {
+        const total = weights.reduce((acc, w) => acc + w, 0);
+        const { value: rand } = await this.getSingleNumber(0, total - 1, commandId, actionId);
+        let cumulative = 0;
+        for (let i = 0; i < weights.length; i++) {
+            cumulative += weights[i];
+            if (rand < cumulative) {
+                return i;
+            }
+        }
+        return weights.length - 1;
+    }
+}
+exports.RngService = RngService;
+//# sourceMappingURL=rng-service.js.map

package/dist/rng/rng-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng-service.js","sourceRoot":"","sources":["../../src/rng/rng-service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnitronix/happy-panda-game-engine",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Happy Panda Game Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",