@thi.ng/random-fxhash

[!NOTE] This is one of 199 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

About
- Further functionality
Status
Related packages
Installation
Dependencies
API
Authors
License

About

@thi.ng/random compatible wrapper & utilities for fxhash's PRNG.

fxhash is a platform for publishing generative art projects on the Tezos blockchain, where each individual project edition is driven by an unique transaction hash, incl. the platform's provided PRNG which is meant to be used by each project to ensure deterministic behavior and reproducibility. The fxhash PRNG is an implementation of the SFC32 (Simple Fast Counter) algorithm, which is also provided by the @thi.ng/random parent package.

This support package provides a singleton implementation (RND) of that PRNG, pre-seeded with the global $fx.hash (formerly fxhash) var injected by the platform SDK. Of course pre-seeding with a transaction hash is only possible when using this package in the browser and in conjunction with a fxhash HTML template. If the global $fx.hash or fxhash var is not defined, the RND instance will be seeded with a default seed (but can also be re-seeded later on). This also allows this package to be used outside the browser env, where the fxhash provided code snippet isn't available...

Additionally, the package also provides various wrappers for other commonly used utilities from the @thi.ng/random package. These are wrapped in such a way that they're using the RND singleton by default (but optionally accept any other IRandom implementation as additional arg). See examples below.

Further functionality

All thi.ng/umbrella packages dealing with randomness in any shape or form are supporting the above mentioned IRandom interface. That means the RND instance can be passed to any of the functions/classes to provide more advanced functionality, e.g.:

@thi.ng/arrays: Array shuffling
@thi.ng/color: Generate procedural/stochastic colors/themes/ranges, analog colors
@thi.ng/colored-noise: Various 1D noise generators
@thi.ng/gp: Genetic programming toolkit
@thi.ng/k-means: nD k-Means clustering
@thi.ng/lowdisc: nD low-discrepancy sequence generators/iterators
@thi.ng/lsys: Highly customizable L-System interpreter
@thi.ng/poisson: nD poisson disc sampling
@thi.ng/vectors: 800+ vector functions, incl. random nD vector creation

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Related packages

@thi.ng/base-n - Arbitrary base-n conversions w/ presets for base8/16/32/36/58/62/64/83/85, support for bigints and encoding/decoding of byte arrays

Installation

yarn add @thi.ng/random-fxhash

ESM import:

import * as rfx from "@thi.ng/random-fxhash";

For Node.js REPL:

const rfx = await import("@thi.ng/random-fxhash");

Package sizes (brotli'd, pre-treeshake): ESM: 493 bytes

IMPORTANT: When using this package (or any other packages from this monorepo) for fxhash, you MUST use a bundler (e.g. Vite, Parcel or Webpack), since the platform does not support ES module imports from external sources/CDNs. A related boilerplate project template will be published soon. Follow @thing_umbrella on Twitter for updates...

Dependencies

Note: @thi.ng/api is in most cases a type-only import (not used at runtime)

API

Generated API docs

TODO

import {
    RND,
    probability,
    pick, pickKey,
    weighted, weightedKey,
    seedFromHash,
} from "@thi.ng/random-fxhash";

const themes = {
    bw: ["#000", "#fff"],
    gray: ["#666", "#ccc"],
    red: ["#f00", "#000"],
    yellow: ["#ff0", "#00f"],
};

// (uniformly) pick a random value
const thickness = pick([0.5, 1, 2, 3]);

// (uniformly) pick random key from `themes`
const themeID = pickKey(themes);
// "gray"

// pick a key from given object of weights
// i.e. "bw" is 8x more likely to be picked than "yellow"
const themeID = weightedKey({ bw: 8, gray: 4, red: 2, yellow: 1 })
// "bw"

// same, but using individual arrays of choices/weights
const themeID = weighted(["bw", "gray", "red", "yellow"], [8, 4, 2, 1]);

// 20% chance for slow mode
const isSlow = probability(0.2);

// the IRandom interface also provides these methods:

// return a 32bit unsigned int
RND.int()

// return a float in [0..n) interval (default n = 1)
RND.float(n)

// return a float in [-n..n) interval (default n = 1)
RND.norm(n)

// return a float in [min..max) interval
RND.minmax(0.5, 1)

// return a int in [min..max) interval
RND.minmaxInt(0, 100)

// (re)seed from transaction hash
RND.seed(seedFromHash("ookorwLedQrCTPesBcUPrR2oRbPHgsAxe9xgCSNq4XAuZSaCvaB"));

// or reseed from uint's
RND.seed([1, 2, 3, 4]);

Authors

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-random-fxhash,
  title = "@thi.ng/random-fxhash",
  author = "Karsten Schmidt",
  note = "https://thi.ng/random-fxhash",
  year = 2022
}