vesuna
v3.1.0
Published
Generate and use memorable random seeds.
Downloads
38
Maintainers
Readme
Vesuna
Vesuna is a small utility library, to generate and use memorable random seeds.
Demo
Note that the result is always the same for a given seed, despite being pseudorandomly generated.
Demo made with three.js and lil-gui.
What it's for
Use a string as seed
Because it is easier to remember, share and differentiate than a numerical seed.
Ex: skywolf/spacetuna vs 2030949/1879546.
Generate easy to remember strings
Use vesuna.autoseed() to generate a codename, a dish, some gibberish, or a hash.
Generate a wide variety of numbers
Use vesuna.random() to generate pseudorandom 32-bit floats between 0 and 1. You can generate as many as you need, and also can use some built-in helper methods to generate uints, booleans etc.
Reproduce specific results
Once setup with a seed, vesuna.random() will produce floats in sequences that will always be the same with that exact seed. It is intended as a Math.random() replacement for generative applications using many randomized settings, allowing to easily save and restore an exact outcome.
IMPORTANT:
Made for creative/generative applications.
Seeded pseudorandomness is predictable by nature, which makes it unsafe for security-sensitive applications.
Installation
Via npm.
npm install vesuna --save
import {Vesuna} from 'vesuna';
const vesuna = new Vesuna();
Basic usage
// Manually set a seed (case sensitive)
vesuna.seed = 'a random seed';
// Generate a random float between 0 and 1, similar to Math.random()
vesuna.random(); // Will always return 0.6696700062602758
vesuna.random(); // Will always return 0.7957393529359251
vesuna.random(); // Will always return 0.49764455226249993
vesuna.reset(); // Reset the sequence
vesuna.random(); // Will always return 0.6696700062602758
vesuna.random(); // Will always return 0.7957393529359251
vesuna.random(); // Will always return 0.49764455226249993
vesuna.seed = 'another random seed'; // Change the seed for another sequence
vesuna.random(); // Will always return 0.18839840171858668
vesuna.random(); // Will always return 0.3372709883842617
vesuna.random(); // Will always return 0.737179079791531
Random helpers
In addition to vesuna.random(), you can use the following, for convenience:
// Numbers
vesuna.number(-2, 2); // Float between -2 and 2
vesuna.number(-2, 2, true); // -2, -1, 0, 1, 2 (rounded)
vesuna.integer(-3, 3); // -3, -2, -1, 0, 1, 2, 3
vesuna.unsignedInteger(4); // 0, 1, 2, 3, 4
// Booleans
vesuna.boolean(); // true or false
vesuna.chance(1/4); // 1/4 chance to be true, 3/4 to be false
// Numbers (advanced)
vesuna.noise() // Float between -1 and 1
vesuna.sign(); // -1 or 1
vesuna.numberFrom({min:-3, max:3}); // Float between -3 and 3
vesuna.integerFrom({min:2, max 4}); // 2, 3, 4
// Objects
vesuna.entry({foo:0, bar:1}); // ['foo', 0] or ['bar', 1]
vesuna.key({foo:0, bar:1}); // 'foo' or 'bar'
vesuna.value({foo:0, bar:1}); // 0 or 1
vesuna.item([foo, bar]); // foo or bar
vesuna.character('abc'); // 'a', 'b' or 'c'
// Aliases / Shorthands
vesuna.amount(); // vesuna.random()
vesuna.num(); // vesuna.number()
vesuna.int(); // vesuna.integer()
vesuna.uint(); // vesuna.unsignedInteger()
vesuna.bool(); // vesuna.boolean()
vesuna.numFrom(); // vesuna.numberFrom()
vesuna.intFrom(); // vesuna.integerFrom()
vesuna.char(); // vesuna.character()
Autoseed
You can seed a Vesuna instance with any string, but it also includes a string generator, designed to create easy to memorize seeds.
Note: Vesuna instances autoseed by default.
let vesuna = new Vesuna('foobar');
console.log(vesuna.seed); // foobar
vesuna = new Vesuna();
console.log(vesuna.seed); // Ex: skywolf
vesuna.autoseed();
console.log(vesuna.seed); // Ex: spacetuna
Settings
There are a few settings to customize the random seeds you can get.
// Set vesuna.verbose to true for more complex seeds
vesuna.verbose = true;
vesuna.autoseed(); // skywolfspacetuna
// Different modes for different possible outcomes
vesuna.mode = Vesuna.modes.CODENAME;
vesuna.autoseed(); // skywolf, skywolfspacetuna
vesuna.mode = Vesuna.modes.DISH;
vesuna.autoseed(); // spicybeef, spicybeefavocadosalad
vesuna.mode = Vesuna.modes.GIBBERISH;
vesuna.autoseed(); // wopeko, wopekosakina
vesuna.mode = Vesuna.modes.HASH;
vesuna.autoseed(); // 2af7as, 2af7asks3gqh
// Separate words using a symbol
vesuna.separator = Vesuna.separators.NONE; // skywolf
vesuna.separator = Vesuna.separators.DASH; // sky-wolf
vesuna.separator = Vesuna.separators.DOT; // sky.wolf
vesuna.separator = Vesuna.separators.SLASH; // sky/wolf
vesuna.separator = Vesuna.separators.SPACE; // sky wolf
vesuna.separator = Vesuna.separators.TILDE; // sky~wolf
vesuna.separator = Vesuna.separators.UNDERSCORE; // sky_wolf
// Can be any string
vesuna.separator = '+'; // sky+wolf
// Constructor options (with default values)
const vesuna = new Vesuna({
seed: '',
mode: Vesuna.modes.CODENAME,
separator: Vesuna.separators.NONE,
verbose: false,
});
Possible outcomes
This autoseeder provides a limited number of possible seeds, depending on the current mode and verbose settings. For example, using the defaults (Vesuna.modes.CODENAME & verbose=false) results in about 60,000 possible outcomes.
Codename
61,863 / ~3,700,000,000
Dish
22,524 / 67,731,456
Gibberish
524,288 / ~160,000,000,000
Hash
2,176,782,336 / 2,176,782,336²
Lite version
If you don't need the fancy autoseed function, you can use the lite version instead.
import {VesunaLite} from 'vesuna';
const vesuna = new VesunaLite();
vesuna.autoseed(); // 2af7as
// Mode, verbose and separator have no effect,
// but all the random helpers still work.
vesuna.uint();
vesuna.noise();
vesuna.item(array);
It's basically Alea with a basic hash autoseed, plus the random helpers.
If you don't need those either, you can simply use Alea on its own.
import {Alea} from 'vesuna';
const alea = new Alea('mySeed');
alea.random(); // 0-1 float
Credits
This library is based on Johannes Baagøe's PRNG algorithm.
Kedan - 2022