chaos 0.1.1

Fast and high quality pseudo-random number generators (PRNGs) with cloneable state.

Chaos

Fast and high quality pseudo-random number generators (PRNGs) with cloneable state.

Usage

Chaos provides a common interface for pseudo-random number generators (PRNGs) beyond the built-in Random class, including high-quality PRNGs with saveable and cloneable state, and deterministic sequences for testing:

import 'package:chaos/chaos.dart';

void main() {
  // Use a high-quality PRNG with inspectable and cloneable state*
  //
  // * This is useful for save-states, replays, and debugging!
  //
  // Xoshiro128+ is a fast, high-quality PRNG with a 128-bit state.
  // https://prng.di.unimi.it/xoshiro128plus.c for the reference implementation.
  final random = Xoshiro128P();

  // "Roll" 10 d20s, and print the results!
  for (var i = 0; i < 10; i++) {
    print('d20: ${random.nextInt(20) + 1}');
  }

  // Clone and resume the PRNG from the saved state.
  final clone = random.clone();

  // "Roll" 10 d6s, and print the results!
  for (var i = 0; i < 10; i++) {
    print('d6: ${clone.nextInt(6) + 1}');
  }

  // Want very controlled artificial randomness for unit tests?
  // Use a pre-generated sequence of random numbers: SequenceRandom.
  final sequence = SequenceRandom([1, 2, 3, 4, 5], max: 6);

  // "Roll" 5 d6s, and print the results!
  // (TIP: This is going to be 1, 2, 3, 4, 5)
  for (var i = 0; i < 5; i++) {
    print('d6: ${sequence.nextInt(6) + 1}');
  }
}

Features

For many usages, the default dart:math Random class is sufficient; however, Chaos provides additional features for more advanced use-cases, such as game development, simulations, and testing:

• High-quality Xoshiro128+ and Xoshiro128++ PRNGs: Fast and high-quality PRNGs with 128-bit state, and clonable state for save-states, replays, and debugging, carefully tested against the reference implementations using Dart FFI.
• Deterministic SequenceRandom: A PRNG that generates numbers from a pre-defined sequence, useful for unit tests and debugging with tightly controlled randomness. Answer that age-old question: "What happens if the player rolls a 20 every time?".
• Common SeedableGenerator interface: A common interface for PRNGs that can can be created with a seed. Want your own PRNG? Implement this interface and swap PRNGs with ease.

Contributing

To run the tests, run:

dart test

To check code coverage locally, run:

./chore coverage

To preview dartdoc output locally, run:

./chore dartodc