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! ❤️
@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.
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
yarn add @thi.ng/random-fxhashESM 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...
Note: @thi.ng/api is in most cases a type-only import (not used at runtime)
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]);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
}© 2022 - 2024 Karsten Schmidt // Apache License 2.0