Random

Deterministic random number generation for Helios

random

Generates a deterministic random number between 0 (inclusive) and 1 (exclusive) based on a seed.

This function is stateless: passing the same seed always returns the same value. To generate a sequence of random numbers, vary the seed (e.g., random(seed + index)).

function random(seed: number | string): number

seed · number | string · required

A number or string to seed the random number generator. The same seed always produces the same result.

return · number

A deterministic pseudo-random number between 0 (inclusive) and 1 (exclusive)

Example

import { random } from '@helios-project/core';

// Generate a single random number
const value = random(42);
console.log(value); // Always the same for seed 42

// Generate a sequence by varying the seed
const sequence = Array.from({ length: 10 }, (_, i) => random(42 + i));
console.log(sequence);

// Use string seeds for named randomization
const position = random('particle-1-x');
const velocity = random('particle-1-velocity');

// Use with frame number for animation
function MyComponent() {
  const helios = useHelios();
  const frame = helios.getState().currentFrame;
  
  // Different random value each frame
  const noise = random(frame);
  
  return <div style={{ opacity: noise }} />;
}

Implementation details

The function uses:

• DJB2 hash for converting strings to 32-bit integers
• Mulberry32 PRNG for high-quality pseudo-random number generation with a period of approximately 4 billion

This ensures deterministic, reproducible randomness suitable for video rendering where the same seed must always produce identical output.