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

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.