@thi.ng/random compatible wrapper & utilities for fxhash's PRNG
npm install @thi.ng/random-fxhash
!npm downloads
> [!NOTE]
> This is one of 214 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
@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 otherIRandom
implementation as additional arg). See examples below.
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
ALPHA - bleeding edge / work-in-progress
Search or submit any issues for this package
- @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
``bash`
yarn add @thi.ng/random-fxhash
ESM import:
`ts`
import * as rfx from "@thi.ng/random-fxhash";
Browser ESM import:
`html`
For Node.js REPL:
`js`
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...
- @thi.ng/api
- @thi.ng/base-n
- @thi.ng/random
Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
TODO
`ts
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]);
`
If this project contributes to an academic publication, please cite it as:
`bibtex``
@misc{thing-random-fxhash,
title = "@thi.ng/random-fxhash",
author = "Karsten Schmidt",
note = "https://thi.ng/random-fxhash",
year = 2022
}
© 2022 - 2026 Karsten Schmidt // Apache License 2.0