/**
 * SeededRandom — deterministic PRNG for games and procedural generation.
 *
 * Algorithm: xoshiro128** (Blackman & Vigna, 2018)
 *   Period:  2^128 − 1
 *   Quality: passes PractRand, BigCrush; excellent for game use
 *   State:   4 × uint32 — compact, fast, fully serialisable
 *
 * Seeding: SplitMix32 is used to expand any integer or string seed into
 * the four-word initial state, avoiding the all-zero trap.
 *
 * Usage:
 *   const rng = new SeededRandom('world-seed');
 *   const roomRng = rng.clone();          // independent sub-stream
 *   const x = roomRng.randInt(0, 100);
 *   const saved = rng.getState();         // snapshot
 *   rng.setState(saved);                  // restore
 */

import { stringHash } from "./utils";

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/** Four-word xoshiro128** state. Serialisable to / from JSON. */
export type RNGState = [number, number, number, number];

// ---------------------------------------------------------------------------
// Helpers (module-private)
// ---------------------------------------------------------------------------

/** Left-rotate a uint32. */
function rotl(x: number, k: number): number {
  return ((x << k) | (x >>> (32 - k))) >>> 0;
}

/**
 * SplitMix32 — used only during seeding to expand a single uint32 into the
 * four independent state words required by xoshiro128**.
 */
function splitMix32Step(h: number): [number, number] {
  h = (h + 0x9e3779b9) >>> 0;
  let v = Math.imul(h ^ (h >>> 16), 0x85ebca6b) >>> 0;
  v     = Math.imul(v ^ (v >>> 13), 0xc2b2ae35) >>> 0;
  return [(v ^ (v >>> 16)) >>> 0, h];
}

/** Expand a single integer (or hashed string) into a valid xoshiro128 state. */
function buildState(seed: number | string): RNGState {
  let h = typeof seed === 'string' ? stringHash(seed) : seed >>> 0;
  let s0: number, s1: number, s2: number, s3: number;
  [s0, h] = splitMix32Step(h);
  [s1, h] = splitMix32Step(h);
  [s2, h] = splitMix32Step(h);
  [s3]    = splitMix32Step(h);
  // Guard: xoshiro128** must never start in the all-zero state.
  if ((s0 | s1 | s2 | s3) === 0) s0 = 1;
  return [s0, s1, s2, s3];
}

// ---------------------------------------------------------------------------
// Main class
// ---------------------------------------------------------------------------

export class SeededRandom {
  private s: RNGState;

  /**
   * @param seed  A number, string, or a previously saved RNGState array.
   *              Strings are hashed deterministically (same string → same sequence).
   */
  constructor(seed: number | string | RNGState = Date.now()) {
    this.s = Array.isArray(seed)
      ? ([...seed] as RNGState)
      : buildState(seed);
  }

  // -------------------------------------------------------------------------
  // Core generator
  // -------------------------------------------------------------------------

  /** xoshiro128** — advances state, returns a raw uint32. */
  private next(): number {
    const [s0, s1, s2, s3] = this.s;

    const result = Math.imul(rotl(Math.imul(s1, 5) >>> 0, 7), 9) >>> 0;

    const t = (s1 << 9) >>> 0;
    this.s[2] = (s2 ^ s0) >>> 0;
    this.s[3] = (s3 ^ s1) >>> 0;
    this.s[1] = (s1 ^ this.s[2]) >>> 0;
    this.s[0] = (s0 ^ this.s[3]) >>> 0;
    this.s[2] = (this.s[2] ^ t) >>> 0;
    this.s[3] = rotl(this.s[3], 11);

    return result;
  }

  // -------------------------------------------------------------------------
  // Public API
  // -------------------------------------------------------------------------

  /**
   * Uniform float in [0, 1).
   * Uses 32 bits of randomness → 2^32 distinct values spaced by ~2.3 × 10^−10.
   */
  nextFloat(): number {
    return this.next() / 0x1_0000_0000;
  }

  /**
   * Uniform integer in [min, max).
   * Uses rejection sampling to eliminate modulo bias.
   *
   * @param min  Inclusive lower bound (default 0).
   * @param max  Exclusive upper bound (required).
   */
  nextInt(min: number, max: number): number;
  nextInt(max: number): number;
  nextInt(minOrMax: number, max?: number): number {
    const [min, hi] = max === undefined ? [0, minOrMax] : [minOrMax, max];

    if (!Number.isInteger(min) || !Number.isInteger(hi)) {
      throw new RangeError(`randInt: bounds must be integers, got (${min}, ${hi})`);
    }
    if (min >= hi) {
      return hi;
    }

    const range = hi - min;
    // Rejection threshold that makes every output equally likely.
    // threshold = (2^32 mod range), computed without overflow as:
    const threshold = (0x1_0000_0000 - range) % range >>> 0;

    let v: number;
    do { v = this.next(); } while (v < threshold);
    return min + (v % range);
  }

  /** Uniform boolean — exactly 50 % probability. */
  nextBool(): boolean {
    return (this.next() & 1) === 1;
  }

  /**
   * Uniform random element from any iterable.
   * Arrays are read in O(1); other iterables are materialised first.
   *
   * @param iterable  Source collection.
   * @param k         When provided, returns k distinct elements sampled
   *                  **without replacement** using a partial Fisher-Yates
   *                  sweep — O(k) time, O(n) space for the working copy.
   *
   * @throws RangeError if the collection is empty, k < 1, or k > collection size.
   */
  choice<T>(iterable: Iterable<T>): T;
  choice<T>(iterable: Iterable<T>, k: number): T[];
  choice<T>(iterable: Iterable<T>, k?: number): T | T[] {
    const arr = [...iterable];
    if (arr.length === 0) return [];

    if (k === undefined) {
      return arr[this.nextInt(0, arr.length)];
    }

    if (k === 0) {
        return [];
    }

    if (!Number.isInteger(k) || k < 0) {
      throw new RangeError(`choice: k must be a positive integer, got ${k}`);
    }
    if (k > arr.length) {
      throw new RangeError(`choice: k (${k}) exceeds collection size (${arr.length})`);
    }

    // Partial Fisher-Yates — only iterate the first k swaps.
    // The selected items accumulate at the front of the working copy.
    for (let i = 0; i < k; i++) {
      const j = this.nextInt(i, arr.length);
      const tmp = arr[i]; arr[i] = arr[j]; arr[j] = tmp;
    }
    return arr.slice(0, k);
  }

  /**
   * Weighted random choice — weights need not be normalised.
   *
   * Runs in O(n) per draw. For hot paths with a large, static item list
   * consider building an alias table (Vose's method) instead.
   *
   * @param items    Source array.
   * @param weights  Parallel weight array; must be non-negative with total > 0.
   * @param k        When provided, returns k elements sampled independently
   *                 **with replacement** — each draw is an independent weighted
   *                 roll, so the same item can appear multiple times.
   *
   * @throws RangeError if arrays have different lengths, contain negative
   *         weights, the total weight is zero, or k < 1.
   */
  weightedChoice<T>(items: readonly T[], weights: readonly number[]): T;
  weightedChoice<T>(items: readonly T[], weights: readonly number[], k: number): T[];
  weightedChoice<T>(items: readonly T[], weights: readonly number[], k?: number): T | T[] {
    if (items.length === 0) {
      throw new RangeError('weightedChoice: items is empty');
    }
    if (items.length !== weights.length) {
      throw new RangeError(
        `weightedChoice: items.length (${items.length}) !== weights.length (${weights.length})`,
      );
    }
    if (k === 0) {
        return [];
    }
    if (k !== undefined && (!Number.isInteger(k) || k < 1)) {
      throw new RangeError(`weightedChoice: k must be a positive integer, got ${k}`);
    }

    let total = 0;
    for (let i = 0; i < weights.length; i++) {
      if (weights[i] < 0) throw new RangeError(`weightedChoice: negative weight at index ${i}`);
      total += weights[i];
    }
    if (total <= 0) throw new RangeError('weightedChoice: total weight must be > 0');

    const drawOne = (): T => {
      let r = this.nextFloat() * total;
      for (let i = 0; i < items.length; i++) {
        r -= weights[i];
        if (r < 0) return items[i];
      }
      // Float rounding safety net — return last item with non-zero weight.
      for (let i = items.length - 1; i >= 0; i--) {
        if (weights[i] > 0) return items[i];
      }
      return items[items.length - 1];
    };

    if (k === undefined) return drawOne();

    const result: T[] = new Array(k);
    for (let i = 0; i < k; i++) result[i] = drawOne();
    return result;
  }

  /**
   * Fisher-Yates shuffle — mutates the array in place.
   * Returns the same array for chaining.
   */
  shuffle<T>(arr: T[]): T[] {
    for (let i = arr.length - 1; i > 0; i--) {
      const j = this.nextInt(0, i + 1);
      const tmp = arr[i];
      arr[i] = arr[j];
      arr[j] = tmp;
    }
    return arr;
  }

  /**
   * Returns a new shuffled copy of the input.
   * The original is not modified.
   */
  toShuffled<T>(arr: readonly T[]): T[] {
    return this.shuffle([...arr]);
  }

  // -------------------------------------------------------------------------
  // State management
  // -------------------------------------------------------------------------

  /**
   * Snapshot the current generator state.
   * The returned value is a plain array — safe to JSON.stringify / store.
   */
  getState(): RNGState {
    return [...this.s] as RNGState;
  }

  /**
   * Restore the generator to a previously snapshotted state.
   * After this call, the sequence is identical to what it was at the snapshot.
   */
  setState(state: RNGState): void {
    if (!Array.isArray(state) || state.length !== 4) {
      throw new TypeError('setState: expected an array of 4 uint32s');
    }
    this.s = [...state] as RNGState;
  }

  /**
   * Create an independent child RNG for a sub-resource (room, NPC, particle
   * system, …).
   *
   * The child starts from the *current* state. The parent then advances by
   * one step so parent and child immediately diverge — neither will reproduce
   * the other's sequence.
   *
   * Typical pattern:
   *   const worldRng   = new SeededRandom('seed-42');
   *   const dungeonRng = worldRng.clone();   // independent dungeon stream
   *   const npcRng     = worldRng.clone();   // independent NPC stream
   */
  clone(): SeededRandom {
    const child = new SeededRandom(this.getState());
    this.jump(); // diverge parent so the two streams never overlap
    return child;
  }

  /**
   * Advance the state by 2^64 steps (equivalent to 2^64 calls to next()).
   * Use this to generate 2^64 non-overlapping subsequences for parallel work.
   */
  jump(): void {
    const JUMP = [0x8764000b, 0xf542d2d3, 0x6fa035c3, 0x77f2db5b];
    let s0 = 0, s1 = 0, s2 = 0, s3 = 0;
    for (const j of JUMP) {
      for (let b = 0; b < 32; b++) {
        if ((j >>> b) & 1) {
          s0 ^= this.s[0];
          s1 ^= this.s[1];
          s2 ^= this.s[2];
          s3 ^= this.s[3];
        }
        this.next();
      }
    }
    this.s[0] = s0 >>> 0;
    this.s[1] = s1 >>> 0;
    this.s[2] = s2 >>> 0;
    this.s[3] = s3 >>> 0;
  }

  /**
   * Advance the state by 2^96 steps (equivalent to 2^96 calls to next()).
   * Generates 2^32 starting points; each jump() from those gives 2^32
   * non-overlapping subsequences — useful for distributed computation.
   */
  longJump(): void {
    const LONG_JUMP = [0xb523952e, 0x0b6f099f, 0xccf5a0ef, 0x1c580662];
    let s0 = 0, s1 = 0, s2 = 0, s3 = 0;
    for (const j of LONG_JUMP) {
      for (let b = 0; b < 32; b++) {
        if ((j >>> b) & 1) {
          s0 ^= this.s[0];
          s1 ^= this.s[1];
          s2 ^= this.s[2];
          s3 ^= this.s[3];
        }
        this.next();
      }
    }
    this.s[0] = s0 >>> 0;
    this.s[1] = s1 >>> 0;
    this.s[2] = s2 >>> 0;
    this.s[3] = s3 >>> 0;
  }

  // -------------------------------------------------------------------------
  // Serialisation
  // -------------------------------------------------------------------------

  toJSON(): { state: RNGState } {
    return { state: this.getState() };
  }

  static fromJSON(json: { state: RNGState }): SeededRandom {
    return new SeededRandom(json.state);
  }
}
