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

package/dist/rng/rng-client.interface.d.ts

@@ -0,0 +1,51 @@
+/**
+ * RNG Client Interface
+ *
+ * Contract for all RNG clients (local and external).
+ * Matches the pattern used in Heroes of Aether and Bonny's Fortune.
+ */
+export interface RngSingleResponse {
+    value: number;
+    seed: number;
+}
+export interface RngBatchResponse {
+    values: number[];
+    seeds: number[];
+}
+/**
+ * RNG Client Interface
+ *
+ * All RNG clients must implement this interface to ensure
+ * consistent behavior between local (testing) and external (production) clients.
+ */
+export interface IRngClient {
+    /**
+     * Generate a single random integer in range [min, max]
+     */
+    getSingleNumber(min: number, max: number, seed?: number): Promise<RngSingleResponse>;
+    /**
+     * Generate multiple random integers in range [min, max]
+     */
+    getBatchNumbers(min: number, max: number, count: number, seed?: number): Promise<number[]>;
+    /**
+     * Generate multiple random integers with individual seeds
+     */
+    getBatchNumbersWithSeeds(min: number, max: number, count: number, seed?: number): Promise<RngSingleResponse[]>;
+    /**
+     * Generate a single random float in range [0, 1)
+     */
+    getSingleFloat(seed?: number): Promise<RngSingleResponse>;
+    /**
+     * Generate multiple random floats in range [0, 1)
+     */
+    getBatchFloats(count: number, seed?: number): Promise<RngBatchResponse>;
+    /**
+     * Alternative method for single random number
+     */
+    getRandomNumber(min: number, max: number, seed?: number): Promise<RngSingleResponse>;
+    /**
+     * Alternative method for single random float
+     */
+    getRandomFloat(seed?: number): Promise<RngSingleResponse>;
+}
+//# sourceMappingURL=rng-client.interface.d.ts.map

package/dist/rng/rng-client.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng-client.interface.d.ts","sourceRoot":"","sources":["../../src/rng/rng-client.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,eAAe,CACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE9B;;OAEG;IACH,eAAe,CACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAErB;;OAEG;IACH,wBAAwB,CACtB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAEhC;;OAEG;IACH,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE1D;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAExE;;OAEG;IACH,eAAe,CACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE9B;;OAEG;IACH,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3D"}

package/dist/rng/rng-service.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+import { IRngClient } from './rng-client.interface';
+/**
+ * RNG outcome record for audit trail
+ */
+export interface RngOutcomeRecord {
+    result: number;
+    seed: number;
+    min: number;
+    max: number;
+}
+/**
+ * RNG outcomes for a single command, keyed by action ID
+ */
+export type RngOutcome = {
+    [actionId: string]: RngOutcomeRecord;
+};
+/**
+ * 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.
+ */
+export declare class RngService {
+    private readonly rngClient;
+    private rngOutcomes;
+    constructor(rngClient: IRngClient);
+    /**
+     * Register a command for RNG tracking.
+     * Call this at the start of command processing.
+     */
+    registerCommand(commandId: string): void;
+    /**
+     * Remove a command's RNG outcomes.
+     * Call this after command processing to clean up.
+     */
+    removeCommand(commandId: string): void;
+    /**
+     * Check if a command has RNG outcomes
+     */
+    hasCommandRngOutcome(commandId: string): boolean;
+    /**
+     * Get the count of RNG outcomes for a command
+     */
+    getRngOutcomeCountForCommand(commandId: string): number;
+    /**
+     * Store an RNG outcome for audit trail
+     */
+    private storeSeedForCommand;
+    /**
+     * Get cached seed for a command/action (for replay scenarios)
+     */
+    getSeedForCommand(commandId: string, actionId: string): number | undefined;
+    /**
+     * Get all RNG outcomes for a command
+     */
+    getRngOutcomeForCommand(commandId: string): RngOutcome;
+    /**
+     * Get all RNG outcomes across all commands
+     */
+    getAllRngOutcome(): {
+        [commandId: string]: RngOutcome;
+    };
+    /**
+     * Generate a single random integer in range [min, max]
+     * Tracks the outcome for audit trail
+     */
+    getSingleNumber(min: number, max: number, commandId: string, actionId: string): Promise<{
+        value: number;
+        seed: number;
+    }>;
+    /**
+     * Generate multiple random integers in range [min, max]
+     * Each number is tracked individually with incrementing action IDs
+     */
+    getBatchNumbers(min: number, max: number, count: number, commandId: string, actionId: string): Promise<{
+        value: number;
+        seed: number;
+    }[]>;
+    /**
+     * Generate a weighted random selection
+     * Returns the index selected based on weights
+     */
+    getWeightedRandomIndex(weights: number[], commandId: string, actionId: string): Promise<number>;
+}
+//# sourceMappingURL=rng-service.d.ts.map

package/dist/rng/rng-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng-service.d.ts","sourceRoot":"","sources":["../../src/rng/rng-service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAElE;;;;;;GAMG;AACH,qBAAa,UAAU;IAGT,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,WAAW,CAA2C;gBAEjC,SAAS,EAAE,UAAU;IAElD;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAMxC;;;OAGG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAItC;;OAEG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIhD;;OAEG;IACH,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAKvD;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;OAEG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI1E;;OAEG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU;IAItD;;OAEG;IACH,gBAAgB,IAAI;QAAE,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE;IAIvD;;;OAGG;IACG,eAAe,CACnB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAwB3C;;;OAGG;IACG,eAAe,CACnB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAgB7C;;;OAGG;IACG,sBAAsB,CAC1B,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC;CAmBnB"}

package/dist/rng/spin-generator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Spin Generator with Symbol Limitation System
+ *
+ * Generates 3x3 grids with weighted symbol distribution and limitation constraints.
+ * Each symbol type has a randomly selected maximum count (2, 4, 7, or 9).
+ */
+import { Symbol, SpinType } from '../config/happy-panda.config';
+import { Grid, GameDirection, RngProvider } from '../domain/types';
+/**
+ * Generate a grid with weighted symbols and limitation constraints.
+ *
+ * IMPORTANT: C++ logic requires limitations to be selected FIRST, then
+ * 3x3 check only happens if a symbol has limit=9 (max symbols).
+ *
+ * @param spinType Type of spin
+ * @param gameDirection Game direction
+ * @param rng RNG provider
+ * @param centerSymbol Optional fixed center symbol (for respin)
+ * @returns Generated 3x3 grid
+ */
+export declare function generateGrid(spinType: SpinType, gameDirection: GameDirection, rng: RngProvider, centerSymbol?: Symbol): Promise<Grid>;
+/**
+ * Generate cherry piece grid for jackpot bonus.
+ * Each position gets the appropriate piece symbol.
+ */
+export declare function generateCherryPieceGrid(): Grid;
+/**
+ * Check if grid is a complete cherry piece (jackpot).
+ */
+export declare function isCompleteCherryPiece(grid: Grid): boolean;
+//# sourceMappingURL=spin-generator.d.ts.map

package/dist/rng/spin-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spin-generator.d.ts","sourceRoot":"","sources":["../../src/rng/spin-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,MAAM,EACN,QAAQ,EA+BT,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAqHnE;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,aAAa,EAC5B,GAAG,EAAE,WAAW,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAgJf;AA8ED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAM9C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAiBzD"}

package/dist/rng/weighted-random.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Weighted Random Selection Utilities
+ *
+ * Helper functions for weighted random selection using the RNG provider.
+ */
+import { RngProvider } from '../domain/types';
+/**
+ * Select an index from an array of weights.
+ * @param weights Array of weights (must be positive integers)
+ * @param rng RNG provider
+ * @returns Selected index
+ */
+export declare function selectWeightedIndex(weights: readonly number[], rng: RngProvider): Promise<number>;
+/**
+ * Check if a weighted random selection succeeds.
+ * @param yesWeight Weight for "yes" outcome
+ * @param noWeight Weight for "no" outcome
+ * @param rng RNG provider
+ * @returns true if "yes" was selected
+ */
+export declare function weightedBoolean(yesWeight: number, noWeight: number, rng: RngProvider): Promise<boolean>;
+/**
+ * Select multiple weighted indices (with replacement).
+ * @param weights Array of weights
+ * @param count Number of selections
+ * @param rng RNG provider
+ * @returns Array of selected indices
+ */
+export declare function selectMultipleWeighted(weights: readonly number[], count: number, rng: RngProvider): Promise<number[]>;
+//# sourceMappingURL=weighted-random.d.ts.map

package/dist/rng/weighted-random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weighted-random.d.ts","sourceRoot":"","sources":["../../src/rng/weighted-random.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAMnB"}

package/package.json

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