|
| 1 | +/** |
| 2 | + * Seedable PRNG for Spindle — Mulberry32 algorithm. |
| 3 | + * |
| 4 | + * Provides deterministic random number generation that survives save/load |
| 5 | + * cycles via a pull-counter approach: recreate from seed, fast-forward N pulls. |
| 6 | + */ |
| 7 | + |
| 8 | +// --------------------------------------------------------------------------- |
| 9 | +// Core algorithm |
| 10 | +// --------------------------------------------------------------------------- |
| 11 | + |
| 12 | +/** Mulberry32: fast, high-quality 32-bit PRNG. */ |
| 13 | +function mulberry32(seed: number): () => number { |
| 14 | + let t = seed | 0; |
| 15 | + return () => { |
| 16 | + t = (t + 0x6d2b79f5) | 0; |
| 17 | + let r = Math.imul(t ^ (t >>> 15), t | 1); |
| 18 | + r ^= r + Math.imul(r ^ (r >>> 7), r | 61); |
| 19 | + return ((r ^ (r >>> 14)) >>> 0) / 0x100000000; |
| 20 | + }; |
| 21 | +} |
| 22 | + |
| 23 | +/** FNV-1a hash — converts a string seed to a 32-bit integer. */ |
| 24 | +function hashSeed(seed: string): number { |
| 25 | + let h = 0x811c9dc5; |
| 26 | + for (let i = 0; i < seed.length; i++) { |
| 27 | + h ^= seed.charCodeAt(i); |
| 28 | + h = Math.imul(h, 0x01000193); |
| 29 | + } |
| 30 | + return h; |
| 31 | +} |
| 32 | + |
| 33 | +// --------------------------------------------------------------------------- |
| 34 | +// Module state |
| 35 | +// --------------------------------------------------------------------------- |
| 36 | + |
| 37 | +let enabled = false; |
| 38 | +let currentSeed = ''; |
| 39 | +let currentPull = 0; |
| 40 | +let generator: (() => number) | null = null; |
| 41 | + |
| 42 | +// --------------------------------------------------------------------------- |
| 43 | +// Public API |
| 44 | +// --------------------------------------------------------------------------- |
| 45 | + |
| 46 | +export interface PRNGSnapshot { |
| 47 | + readonly seed: string; |
| 48 | + readonly pull: number; |
| 49 | +} |
| 50 | + |
| 51 | +/** |
| 52 | + * Initialize the PRNG. |
| 53 | + * @param seed Optional seed string. If omitted, a random seed is generated. |
| 54 | + * @param useEntropy If true (default), mix `Date.now()` and `Math.random()` |
| 55 | + * into the seed for uniqueness across playthroughs. |
| 56 | + * Set to false for fully deterministic sequences. |
| 57 | + */ |
| 58 | +export function initPRNG(seed?: string, useEntropy = true): void { |
| 59 | + let resolvedSeed: string; |
| 60 | + if (seed === undefined) { |
| 61 | + resolvedSeed = String(Date.now()) + String(Math.random()); |
| 62 | + } else if (useEntropy) { |
| 63 | + resolvedSeed = seed + '|' + Date.now() + '|' + Math.random(); |
| 64 | + } else { |
| 65 | + resolvedSeed = seed; |
| 66 | + } |
| 67 | + |
| 68 | + currentSeed = resolvedSeed; |
| 69 | + currentPull = 0; |
| 70 | + generator = mulberry32(hashSeed(resolvedSeed)); |
| 71 | + enabled = true; |
| 72 | +} |
| 73 | + |
| 74 | +/** |
| 75 | + * Restore PRNG state from a snapshot (used on save/load). |
| 76 | + * Recreates the generator from the seed and fast-forwards to the saved pull count. |
| 77 | + */ |
| 78 | +export function restorePRNG(seed: string, pull: number): void { |
| 79 | + currentSeed = seed; |
| 80 | + currentPull = 0; |
| 81 | + generator = mulberry32(hashSeed(seed)); |
| 82 | + enabled = true; |
| 83 | + |
| 84 | + // Fast-forward |
| 85 | + for (let i = 0; i < pull; i++) { |
| 86 | + generator(); |
| 87 | + } |
| 88 | + currentPull = pull; |
| 89 | +} |
| 90 | + |
| 91 | +/** Disable the PRNG (used on restart before StoryInit re-enables it). */ |
| 92 | +export function resetPRNG(): void { |
| 93 | + enabled = false; |
| 94 | + currentSeed = ''; |
| 95 | + currentPull = 0; |
| 96 | + generator = null; |
| 97 | +} |
| 98 | + |
| 99 | +/** Returns the current PRNG state for snapshotting, or null if disabled. */ |
| 100 | +export function snapshotPRNG(): PRNGSnapshot | null { |
| 101 | + if (!enabled) return null; |
| 102 | + return { seed: currentSeed, pull: currentPull }; |
| 103 | +} |
| 104 | + |
| 105 | +/** Returns a seeded random number [0, 1), or falls back to Math.random(). */ |
| 106 | +export function random(): number { |
| 107 | + if (!enabled || !generator) return Math.random(); |
| 108 | + currentPull++; |
| 109 | + return generator(); |
| 110 | +} |
| 111 | + |
| 112 | +/** Returns a random integer between min and max (inclusive). */ |
| 113 | +export function randomInt(min: number, max: number): number { |
| 114 | + if (min > max) [min, max] = [max, min]; |
| 115 | + return Math.floor(random() * (max - min + 1)) + min; |
| 116 | +} |
| 117 | + |
| 118 | +export function isPRNGEnabled(): boolean { |
| 119 | + return enabled; |
| 120 | +} |
| 121 | + |
| 122 | +export function getPRNGSeed(): string { |
| 123 | + return currentSeed; |
| 124 | +} |
| 125 | + |
| 126 | +export function getPRNGPull(): number { |
| 127 | + return currentPull; |
| 128 | +} |
0 commit comments