@omnitronix/bonnys-fortune-game-engine 1.3.1 → 1.3.2

package/src/logic/game-logic-config.interface.ts

@@ -0,0 +1,176 @@
+import {
+  BonnysFortunePrivateState,
+  BonnysFortunePublicState,
+} from './bonnys-fortune.types';
+
+// ---------- Root Config ----------
+export interface BonnysFortuneGameLogicConfigInterface {
+  baseGame: BonnysFortuneGameLogicConfigBaseGame;
+  bonusGames: BonusGamesConfig;
+  scatterGame: ScatterGameWrapper;
+  defaultBetAmountThresholds: number[];
+  defaultBetAmount: number;
+}
+
+export interface BonnysFortuneSessionStateInterface {
+  publicState: BonnysFortunePublicState;
+  privateState: BonnysFortunePrivateState;
+}
+
+// ---------- Base Game ----------
+export interface BonnysFortuneGameLogicConfigBaseGame {
+  symbolMultipliers: SymbolMultiplier[];
+  symbolDefinitions: SymbolDefinitions;
+  baseGameConfig: BaseGameConfig;
+  paidHSymbolWeights: Record<string, number>;
+  paidHSymbolReelWeights: Record<string, [number, number]>;
+  paidScatterReelWeights: Record<string, [number, number]>;
+  bonusGameMeters: Record<BonusGameId, BonusGameMeter>;
+}
+
+export type BonusGameId = 'bonusGame1' | 'bonusGame2' | 'bonusGame3';
+
+export interface SymbolMultiplier {
+  symbolId: number;
+  name: string;
+  multipliers: Record<'x3' | 'x4' | 'x5', number>;
+  isWild: boolean;
+  isScatter: boolean;
+}
+
+export interface SymbolDefinitions {
+  baseSymbols: { minIndex: number; maxIndex: number };
+  specialSymbols: Record<string, number>;
+  collectFeatureSymbols: {
+    multipliers: Record<string, number>;
+    values: Record<string, number>;
+  };
+}
+
+export interface BaseGameConfig {
+  layout: { rows: number; reels: number };
+  winConfig: { minLength: number; maxLength: number };
+  baseBet: number;
+  reelsOptions: {
+    numberOfOptions: number;
+    optionWeights: number[];
+  };
+}
+
+export interface BonusGameMeter {
+  symbol: string;
+  min: number;
+  max: number;
+  percentageLevels: {
+    level1: { min: number; max: number; value: number };
+    level2: { min: number; max: number; value: number };
+    level3: { min: number; max: number; value: number };
+    level4: { min: number; max: number; value: number };
+    level5: { min: number; max: number; value: number };
+  };
+}
+
+// ---------- Bonus Games Configs ----------
+
+export interface BonusGamesConfig {
+  bonusGame1: TreasureHuntBonusGameConfig;
+  bonusGame2: FreeSpinBonusGameConfig;
+  bonusGame3: SteeringToTheFortuneBonusGameConfig;
+}
+
+export interface TreasureHuntBonusGameConfig {
+  type: 'treasure_hunt';
+  potMeter: BonusGameId;
+  config: TreasureHuntBonusConfig;
+}
+
+export interface TreasureHuntBonusConfig {
+  symbolsCount: number;
+  stepsCount: number;
+  jackpotMultipliers: {
+    mini: number;
+    minor: number;
+    major: number;
+    grand: number;
+  };
+  jackpotStartCounts: {
+    mini: number;
+    minor: number;
+    major: number;
+    grand: number;
+  };
+  jackpotScreenCounts: {
+    mini: number;
+    minor: number;
+    major: number;
+    grand: number;
+  };
+  winningWeights: {
+    none: number;
+    mini: number;
+    minor: number;
+    major: number;
+    grand: number;
+  };
+}
+
+export interface FreeSpinBonusGameConfig {
+  type: 'free_spins';
+  potMeter: BonusGameId;
+  config: {
+    spinTypes: SpinTypeConfig[];
+  };
+}
+
+export interface SpinTypeConfig {
+  layout: { rows: number; reels: number };
+  spins: number;
+  multiplier: number;
+  weight: number;
+  reelsOptionsWeights: number[];
+}
+
+export interface SteeringToTheFortuneBonusGameConfig {
+  type: 'steering_to_the_fortune';
+  potMeter: BonusGameId;
+  config: SteeringToTheFortuneConfig;
+}
+
+export interface SteeringToTheFortuneConfig {
+  wheelResults: {
+    type: 'MULTIPLIER' | 'BONUS';
+    value?: number;
+    bonusType?: BonusGameId | 'collectFeature';
+    weight: number;
+  }[];
+}
+
+// ---------- Scatter Game ----------
+export interface ScatterGameWrapper {
+  config: ScatterGameConfig;
+}
+
+export interface ScatterGameConfig {
+  scatterMinNumber: number;
+  scatterSpins: number;
+  scatterCheckpoints: ScatterCheckpoint[];
+  scatterSymbols: ScatterSymbol[];
+  scatterSymbolSpins: WeightOnly[];
+  scatterSymbolSlash: WeightOnly[];
+}
+
+export interface ScatterCheckpoint {
+  spin: number;
+  multiMinValue: number;
+  valueMinValue: number;
+}
+
+export interface ScatterSymbol {
+  symbolId: string;
+  value: number;
+  weight: number;
+}
+
+export interface WeightOnly {
+  weight: number;
+}

package/src/logic/handlers/base-game.handler.ts

@@ -0,0 +1,221 @@
+import {
+  BonnysFortuneBaseGameSpinResult,
+  BonnysFortunePrivateState,
+  BonnysFortunePublicState,
+  BonusTrigger,
+  MetersState,
+  SpinResultResponse,
+  SpinType,
+} from '../bonnys-fortune.types';
+
+import { BonnysFortuneGameLogicConfigInterface } from '../game-logic-config.interface';
+import { BonnysFortuneSpinGenerator } from '../bonnys-fortune.spin-generator';
+import { BonnysFortuneWinCalculator } from '../bonnys-fortune.win-calculator';
+import { GameSpinInputDto } from '../../domain/types/game-spin-input.dto';
+import { NumberHelper } from '../../helpers/number-helper';
+import { ReelStripsConfig } from '../../domain/reel-strips-config';
+import { RngService } from '../../rng/rng-service';
+import { UuidHelper } from '../../helpers/uuid-helper';
+
+export class BaseGameHandler {
+  constructor(private readonly rngService: RngService) {}
+
+  public async handleSpin(
+    params: GameSpinInputDto,
+    publicState: BonnysFortunePublicState,
+    privateState: BonnysFortunePrivateState,
+    config: BonnysFortuneGameLogicConfigInterface,
+    reelStripsConfig: ReelStripsConfig,
+    commandId: string,
+  ): Promise<SpinResultResponse<BonnysFortuneBaseGameSpinResult>> {
+    if (privateState.nextSpinType !== SpinType.BASE_GAME_SPIN) {
+      throw new Error(
+        `Cannot execute base spin while a bonus spin (${privateState.nextSpinType}) is expected`,
+      );
+    }
+
+    let screen = await new BonnysFortuneSpinGenerator(
+      this.rngService,
+    ).generateBaseScreen(
+      config,
+      reelStripsConfig,
+      commandId,
+      'base_spin_screen',
+    );
+
+    screen = await new BonnysFortuneSpinGenerator(
+      this.rngService,
+    ).applyBonusSymbols(screen, config, commandId, 'base_spin_bonus_symbols');
+
+    const bonusMetersForBetAmount = privateState.bonusMetersByAmount[params.betAmount];
+    
+    if (!bonusMetersForBetAmount) {
+      throw new Error(
+        `Bet amount ${params.betAmount} is not in allowed thresholds`,
+      );
+    }
+
+    const updatedBonusMeters = this.updateBonusMeters(
+      screen,
+      bonusMetersForBetAmount,
+      config,
+    );
+
+    privateState.bonusMetersByAmount[params.betAmount] = updatedBonusMeters;
+
+    const scatterSymbolId =
+      config.baseGame.symbolDefinitions.specialSymbols.SCATTER;
+
+    const betStake = this.getBetStake(params, config);
+
+    const triggeredBonus = this.findTriggeredBonus(
+      updatedBonusMeters,
+      params.betAmount,
+      screen,
+      scatterSymbolId,
+    );
+
+    const nextSpinType = triggeredBonus
+      ? getSpinTypeForBonus(triggeredBonus.bonusType)
+      : SpinType.BASE_GAME_SPIN;
+
+    const winResult = BonnysFortuneWinCalculator.calculateWins(
+      screen,
+      config,
+      betStake,
+      1,
+      SpinType.BASE_GAME_SPIN,
+    );
+
+    return {
+      result: {
+        spinType: SpinType.BASE_GAME_SPIN,
+        screen,
+        winResult,
+        playerWinning: NumberHelper.toFixedNumber(winResult.totalWin, 2),
+        nextSpinType,
+        triggeredBonus,
+      },
+      publicState: {
+        currentBetAmount: params.betAmount,
+        bonusMeters: updatedBonusMeters,
+      },
+      privateState: {
+        ...privateState,
+        nextSpinType,
+        pendingBonuses: triggeredBonus ? [triggeredBonus] : [],
+      },
+    };
+  }
+
+  private updateBonusMeters(
+    screen: number[][],
+    bonusMeters: MetersState,
+    config?: BonnysFortuneGameLogicConfigInterface,
+  ): MetersState {
+    const symbolsInScreen = screen.flat();
+
+    return Object.fromEntries(
+      Object.entries(bonusMeters).map(([key, bonusMeter]) => {
+        const count = symbolsInScreen.filter(
+          (sym) => sym === bonusMeter.symbolId,
+        ).length;
+
+        const newProgress = NumberHelper.safeSum(bonusMeter.progress, count, 0);
+
+        const cfg = config?.baseGame.bonusGameMeters[key as keyof typeof config.baseGame.bonusGameMeters];
+        const percentageLevels = cfg?.percentageLevels ?? {};
+        const level = this.getMeterLevel(
+          newProgress,
+          bonusMeter.threshold,
+          percentageLevels,
+        );
+
+        return [key, { ...bonusMeter, progress: newProgress, level }];
+      }),
+    );
+  }
+
+  private findTriggeredBonus(
+    bonusMeters: MetersState,
+    betAmount: number,
+    screen?: number[][],
+    scatterSymbolId?: number,
+  ): BonusTrigger | undefined {
+    const triggeredPot = Object.entries(bonusMeters).find(
+      ([, bonusMeter]) => bonusMeter.progress >= bonusMeter.threshold,
+    );
+    if (triggeredPot) {
+      const [bonusType] = triggeredPot;
+      return {
+        bonusId: UuidHelper.generateUuid(),
+        bonusType,
+        betAmount: NumberHelper.toFixedNumber(betAmount, 2),
+      };
+    }
+
+    if (screen && scatterSymbolId !== undefined) {
+      const flatScreen = screen.flat();
+      const scatterCount = flatScreen.filter(
+        (sym) => sym === scatterSymbolId,
+      ).length;
+
+      if (scatterCount >= 3) {
+        return {
+          bonusId: UuidHelper.generateUuid(),
+          bonusType: 'collectFeature',
+          betAmount: NumberHelper.toFixedNumber(betAmount, 2),
+        };
+      }
+    }
+
+    return undefined;
+  }
+
+  private getMeterLevel(
+    progress: number,
+    threshold: number,
+    percentageLevels: Record<
+      string,
+      { min: number; max: number; value: number }
+    >,
+  ): number {
+    for (const [, range] of Object.entries(percentageLevels)) {
+      const minValue = NumberHelper.safeMultiply(range.min, threshold, 4);
+      const maxValue = NumberHelper.safeMultiply(range.max, threshold, 4);
+
+      if (progress >= minValue && progress < maxValue) {
+        return range.value;
+      }
+    }
+
+    return 5;
+  }
+
+  private getBetStake(
+    params: GameSpinInputDto,
+    config: BonnysFortuneGameLogicConfigInterface,
+  ): number {
+    const baseBet = config.baseGame.baseGameConfig.baseBet;
+    return NumberHelper.safeDivide(
+      params.betAmount,
+      params.creditsPerLine === baseBet ? params.creditsPerLine : baseBet,
+      3,
+    );
+  }
+}
+
+export function getSpinTypeForBonus(bonusType: string): SpinType {
+  switch (bonusType) {
+    case 'bonusGame1':
+      return SpinType.BONUS_GAME_1_SPIN;
+    case 'bonusGame2':
+      return SpinType.BONUS_GAME_2_SPIN;
+    case 'bonusGame3':
+      return SpinType.BONUS_GAME_3_SPIN;
+    case 'collectFeature':
+      return SpinType.COLLECT_FEATURE_SPIN;
+    default:
+      return SpinType.BASE_GAME_SPIN;
+  }
+}

package/src/logic/handlers/collect-feature-bonus.handler.ts

@@ -0,0 +1,301 @@
+import {
+  BonnysFortunePrivateState,
+  BonnysFortunePublicState,
+  BonusRoundResult,
+  CollectFeatureSpinResult,
+  SpinType,
+} from '../bonnys-fortune.types';
+
+import { BonnysFortuneGameLogicConfigInterface } from '../game-logic-config.interface';
+import { GameSpinInputDto } from '../../domain/types/game-spin-input.dto';
+import { NumberHelper } from '../../helpers/number-helper';
+import { RngService } from '../../rng/rng-service';
+
+interface ScatterSymbol {
+  symbolId: string;
+  value: number;
+  weight: number;
+}
+
+export class CollectFeatureBonusHandler {
+  constructor(private rngService: RngService) {}
+
+  public async generateFullBonusRound(
+    params: GameSpinInputDto,
+    publicState: BonnysFortunePublicState,
+    privateState: BonnysFortunePrivateState,
+    config: BonnysFortuneGameLogicConfigInterface,
+    commandId: string,
+  ): Promise<BonusRoundResult<CollectFeatureSpinResult>> {
+    const betStake = this.getBetStake(params, config);
+    const scatterConfig = config.scatterGame.config;
+    const results = [];
+
+    const initialPublicState = { ...publicState };
+    const initialPrivateState = { ...privateState };
+
+    let spinsLeft = scatterConfig.scatterSpins;
+    let totalValues = 0;
+    let totalMultipliers = 1;
+    let totalWin = 0;
+
+    const checkpoints = await Promise.all(
+      scatterConfig.scatterCheckpoints.map(async (cp, index) => {
+        const actionId = `checkpoint_${index}`;
+        const result = await this.rngService.getSingleNumber(
+          0,
+          1,
+          commandId,
+          actionId,
+        );
+        return cp.spin - 1 + result.value;
+      }),
+    );
+
+    for (
+      let spinIndex = 0;
+      spinIndex < scatterConfig.scatterSpins;
+      spinIndex++
+    ) {
+      const { result, updatedState, updatedPublicState, updatedPrivateState } =
+        await this.executeSingleSpin(
+          spinIndex,
+          spinsLeft,
+          totalValues,
+          totalMultipliers,
+          totalWin,
+          betStake,
+          scatterConfig,
+          checkpoints,
+          publicState,
+          privateState,
+          commandId,
+        );
+
+      results.push({
+        result,
+        publicState: updatedPublicState,
+        privateState: updatedPrivateState,
+      });
+
+      totalValues = updatedState.totalValues;
+      totalMultipliers = updatedState.totalMultipliers;
+      totalWin = updatedState.totalWin;
+      spinsLeft = updatedState.spinsLeft;
+      publicState = updatedPublicState;
+      privateState = updatedPrivateState;
+
+      if (spinsLeft <= 0) break;
+    }
+
+    return {
+      results,
+      publicState: initialPublicState,
+      privateState: initialPrivateState,
+    };
+  }
+
+  private async executeSingleSpin(
+    spinIndex: number,
+    spinsLeft: number,
+    totalValues: number,
+    totalMultipliers: number,
+    totalWin: number,
+    betStake: number,
+    scatterConfig: any,
+    checkpoints: number[],
+    publicState: BonnysFortunePublicState,
+    privateState: BonnysFortunePrivateState,
+    commandId: string,
+  ): Promise<{
+    result: CollectFeatureSpinResult;
+    updatedState: {
+      spinsLeft: number;
+      totalValues: number;
+      totalMultipliers: number;
+      totalWin: number;
+    };
+    updatedPublicState: BonnysFortunePublicState;
+    updatedPrivateState: BonnysFortunePrivateState;
+  }> {
+    const symbolCount = await this.weightedPick(
+      scatterConfig.scatterSymbolSpins,
+      commandId,
+      `spin_${spinIndex}_symbol_count`,
+    );
+
+    const symbols: string[] = [];
+    let multiCount = 0;
+    let valueCount = 0;
+
+    for (let i = 0; i < symbolCount; i++) {
+      const symbol = await this.weightedPickSymbol(
+        scatterConfig.scatterSymbols,
+        commandId,
+        `spin_${spinIndex}_symbol_${i}`,
+      );
+      symbols.push(symbol.symbolId);
+      if (symbol.symbolId.startsWith('CM')) multiCount++;
+      else valueCount++;
+    }
+
+    if (checkpoints.includes(spinsLeft)) {
+      const cpIndex = checkpoints.indexOf(spinsLeft);
+      const cp = scatterConfig.scatterCheckpoints[cpIndex];
+      if (
+        (totalMultipliers < cp.multiMinValue && multiCount === 0) ||
+        (totalValues < cp.valueMinValue && valueCount === 0)
+      ) {
+        symbols[0] = 'CV1';
+      }
+    }
+
+    const slashedCount = Math.min(
+      await this.weightedPick(
+        scatterConfig.scatterSymbolSlash,
+        commandId,
+        `spin_${spinIndex}_slashed_count`,
+      ),
+      symbolCount,
+    );
+    const slashed: boolean[] = Array(symbolCount).fill(false);
+    for (let i = 0; i < slashedCount; i++) slashed[i] = true;
+
+    let currentValues = 0;
+    let currentMultipliers = 0;
+
+    for (let i = 0; i < slashed.length; i++) {
+      if (slashed[i]) {
+        const symbol = scatterConfig.scatterSymbols.find(
+          (s: ScatterSymbol) => s.symbolId === symbols[i],
+        );
+        if (!symbol) continue;
+        if (symbols[i].startsWith('CM'))
+          currentMultipliers = NumberHelper.safeSum(
+            currentMultipliers,
+            symbol.value,
+            2,
+          );
+        else
+          currentValues = NumberHelper.safeSum(currentValues, symbol.value, 2);
+      }
+    }
+
+    const newTotalValues = NumberHelper.safeSum(totalValues, currentValues, 2);
+    const newTotalMultipliers = NumberHelper.safeSum(
+      totalMultipliers,
+      currentMultipliers,
+      2,
+    );
+    const newTotalWin = NumberHelper.safeMultiply(
+      NumberHelper.safeMultiply(newTotalValues, newTotalMultipliers, 2),
+      betStake,
+      2,
+    );
+    const playerWinning = NumberHelper.safeSum(newTotalWin, -totalWin, 2);
+
+    spinsLeft -= 1;
+
+    const result: CollectFeatureSpinResult = {
+      spinIndex,
+      spinType: SpinType.COLLECT_FEATURE_SPIN,
+      symbols,
+      slashed,
+      currentValues,
+      currentMultipliers,
+      totalValues: newTotalValues,
+      totalMultipliers: newTotalMultipliers,
+      playerWinning,
+      totalWin: newTotalWin,
+      spinsLeft,
+      nextSpinType:
+        spinsLeft > 0 ? SpinType.COLLECT_FEATURE_SPIN : SpinType.BASE_GAME_SPIN,
+    };
+
+    const updatedPublicState: BonnysFortunePublicState = {
+      ...publicState,
+    };
+
+    const updatedPrivateState: BonnysFortunePrivateState = {
+      ...privateState,
+      nextSpinType:
+        spinsLeft > 0 ? SpinType.COLLECT_FEATURE_SPIN : SpinType.BASE_GAME_SPIN,
+      activeBonus: spinsLeft > 0 ? privateState.activeBonus : undefined,
+    };
+
+    return {
+      result,
+      updatedState: {
+        spinsLeft,
+        totalValues: newTotalValues,
+        totalMultipliers: newTotalMultipliers,
+        totalWin: newTotalWin,
+      },
+      updatedPublicState,
+      updatedPrivateState,
+    };
+  }
+
+  private async weightedPick(
+    items: Array<{ count?: number; weight: number }>,
+    commandId: string,
+    actionId: string,
+  ): Promise<number> {
+    const sum = items.reduce(
+      (acc, item) => NumberHelper.safeSum(acc, item.weight, 2),
+      0,
+    );
+
+    let { value: draw } = await this.rngService.getSingleNumber(
+      0,
+      sum - 1,
+      commandId,
+      actionId,
+    );
+
+    for (const item of items) {
+      if (draw < item.weight) {
+        return item.count || items.indexOf(item) + 1;
+      }
+      draw -= item.weight;
+    }
+    return 1;
+  }
+
+  private async weightedPickSymbol(
+    symbols: ScatterSymbol[],
+    commandId: string,
+    actionId: string,
+  ): Promise<ScatterSymbol> {
+    const sum = symbols.reduce(
+      (acc, s) => NumberHelper.safeSum(acc, s.weight, 2),
+      0,
+    );
+
+    const result = await this.rngService.getSingleNumber(
+      0,
+      sum - 1,
+      commandId,
+      actionId,
+    );
+    let drawValue = result.value;
+
+    for (const s of symbols) {
+      if (drawValue < s.weight) return s;
+      drawValue -= s.weight;
+    }
+    return symbols[0];
+  }
+
+  private getBetStake(
+    params: GameSpinInputDto,
+    config: BonnysFortuneGameLogicConfigInterface,
+  ): number {
+    const baseBet = config.baseGame.baseGameConfig.baseBet;
+    return NumberHelper.safeDivide(
+      params.betAmount,
+      params.creditsPerLine === baseBet ? params.creditsPerLine : baseBet,
+      3,
+    );
+  }
+}