API Reference

Overview and detailed explanations of the individual API functions

A reference for fx(params) related API functions can be found in the API Reference fx(params)

API Overview

Function	Function Signature	Purpose / Effect
$fx.hash	string	The hash string provided (or injected into) for each iteration.
$fx.rand()	() => number	Generates a pseudo-random number using the hash as the seed, ranging from 0 (inclusive) to just under 1 (exclusive).
$fx.rand.reset()	() => void	Reinitialises the $fx.rand() generator to its original state.
$fx.minter	string	The wallet address of the minter, provided (or injected into) for each iteration.
$fx.randminter()	() => number	Similar to rand(), but uses the minter's address as the seed, with the same output range.
$fx.randminter.reset()	() => void	Reinitialises the $fx.randminter() generator just like rand.reset().
$fx.context	string	Indicates where the code is running: standalone, during capture, or while minting.
$fx.iteration	number	The iteration number of the collected GENTK.
$fx.preview()	() => void	Triggers the image capture module at mint time to create the image preview for the collected iteration.
$fx.isPreview	boolean	Set to true when the code runs in the fxhash capture module. Useful for defining capture-specific properties.
$fx.features()	(object) => void	Function that specifies the features of the collected iteration.
$fx.getFeature()	(string) => any	Retrieves the value of a named feature as set by the features() function.
$fx.getFeatures()	() => object	Returns the entire features object as defined by features().
$fx.params()	(array) => void	Define collector-modifiable parameters for your piece by calling this with an array.
$fx.getParam()	(string) => any	Returns the value of a param via its ID.
$fx.getParams()	() => object	Returns a dictionary of all parameter key-value pairs, as currently set.
$fx.getRawParam()	(string) => string	Provides the raw parameter data (as a bytes string) as it was passed to the iteration.
$fx.on()	(string, function, function) => function	Registers an event listener and returns a function to deregister it.
$fx.emit()	(string, any) => void	Sends an event to the parent context, useful for dynamic parameter updates from within the code.

$fx.hash

The string hash injected into the iteration. Will be unique for every iteration of a project. Directly grabbed from the fxhash URL parameter when the iteration is loaded.

console.log($fx.hash) // output example: ooj2HmX8dgniNPuPRcapyXBn9vYpsNwgD1uwx98SLceF6iCZJZK

$fx.rand()

The $fx.rand() function is a Pseudorandom Number Generator which outputs a number between 0 and 1 ([0; 1[). It uses the unique hash injected into the code as a seed, and will always output the same sequence of numbers.

const randomNumber = $fx.rand() // number [0; 1[
const otherRandomNumber = fxrand() // same effect as above

The fx(hash) API provides an implementation of SFC32 (Standard Fast Counter 32) as the PRNG. The $fx.rand() function also points to the equivalent fxrand() function, although they can be used interchangeably, we recommend using the syntax that prepends the $fx object for consistency across your code.

It is not mandatory to use the $fx.rand() function as your source of randomness, you can implement the PRNG of your choice instead, as long as it uses the hash as the seed.

$fx.rand.reset()

You can reset $fx.rand() PRNG to its initial state by calling $fx.rand.reset():

$fx.rand() // 0.25
$fx.rand() // 0.88
$fx.rand() // 0.124

// reset fxrand
$fx.rand.reset()

// calling fxrand again will yield the same outputs as the first calls
$fx.rand() // 0.25
$fx.rand() // 0.88
$fx.rand() // 0.124

$fx.minter

The string wallet address of the minter injected into the iteration. Directly grabbed from the fxminter URL parameter when the iteration is loaded.

console.log($fx.minter) // output example: tz18jgjtEDRtkvNoV9LToradSmVNYFS9aXEe

$fx.randminter()

Similarly to the $fx.rand() function, the $fx.randminter() function is another Pseudorandom Number Generator that derives its randomness from the minter address injected into the code as a seed, and will always output the same sequence of numbers. It outputs a number between 0 and 1 ([0; 1[).

const rand01 = $fx.randminter() // number [0; 1[
const r2 = fxrandminter() // same effect as above

The fxhash snippet provides an implementation of SFC32 (Standard Fast Counter 32) as the PRNG. The $fx.randminter() function also points to the fxrandminter() function. You can use the two of them interchangeably, but we recommend using the $fx syntax for consistency accross your code.

It is not mandatory to use the $fx.randminter() function as your source of randomness, you can implement the PRNG of your choice instead, as long as it uses the minter address as the seed.

$fx.randminter.reset()

Similarly to $fx.rand.reset() you can also reset the $fx.randminter() PRNG to its initial state by calling $fx.randminter.reset().

$fx.randminter() // 0.25
$fx.randminter() // 0.88
$fx.randminter() // 0.124

// reset fxrandminter
$fx.randminter.reset()

// calling fxrandminter again will yield the same outputs as the first calls
$fx.randminter() // 0.25
$fx.randminter() // 0.88
$fx.randminter() // 0.124

$fx.context

The $fx.context property is a flag that indicates the context in which the code is executed. There are 3 possible values for this flag:

• standalone: (default) when the final output should be displayed, on the main project page for instance

• capture: when the code is executed in the capture environment, to get an image preview of an iteration

• minting: when the code is executed during the minting flow of the collector

if ($fx.context === "minting") {
// run code for the minting UI
} else {
// otherwise display the final output
}

This flag is passed in by fx(hash) via the fxcontext URL parameter.

$fx.iteration

The $fx.iteration property indicates the iteration number of the collected GENTK, it can be used for experimental purposes to base certain aspects of the artwork off of it:

console.log($fx.iteration) // output example: 42

The iteration number is passed in by fx(hash) via the fxiteration URL parameter.

$fx.preview()

The $fx.preview() function triggers the capture module when the code is run in the capture context, which creates the image previews that will be displayed by fxhash and other websites to show the collected iterations.

function draw() {
	
	// ...
	// code that generates the graphics
	// ...
	
	// trigger the capture module when all graphics have been generated
	$fx.preview()

}

For projects where an animation is rendered, this function can be particularly useful to trigger a capture for a particular frame:

let counter = 0
function draw() {
	

	// ...
	// code that generates the graphics
	// ...
	
	// increment frame counter
	counter++
	
	// when reaching frame 6000, trigger the capture
	if (counter === 6000) {
		$fx.preview()
	}

	requestAnimationFrame(draw)
}

requestAnimationFrame(draw)

Also make sure to properly configure the capture settings when minting your project on fxhash, you can read more about this in Minting Interface Walkthrough

$fx.isPreview

The $fx.isPreview is a boolean which will be set to true if your code is being run in the capture context. It can be useful when you want to run a certain snippet of code only during when the artwork is being captured.

if ($fx.isPreview) {
	// will be executed only when preview is taken by fxhash
} else {
	// usual execution
}

When a capture of an iteration is taken by fxhash capture module, an url parameter preview=1 is added. The fxhash snippet detects if this parameter is set to 1 and sets $fx.isPreview to true or false based on that.

$fx.features(features)

Artists have the option to expose certain characteristics in an explicit manner via fx(hash) ‘features’. Features are essentially attributes that describe certain aspects of the artwork once it is collected. For instance, the artist can choose to explicitely indicate the rarity of a certain output with a feature, or can also describe the randomly chosen color palette that is used for the coloration of the artwork by exposing the name of this color palette with another feature.

In other words, features are tags that describe the randomly chosen qualities of the collected artwork. They are entirely optional.

If you would like to set them in your project, you can do so via the $fx.features() function. This function expects as input an object with key:value pairs, where these values can have the following types string, number or boolean. Here’s an example:

// call this function before performing computations
$fx.features({
	'A feature of type string': $fx.rand() > 0.5 ? 'Super cool' : 'Not cool !',
	'Feature number': Math.floor($fx.rand() * 100),
	'A boolean feature': $fx.rand() > 0.8 > true : false,
	'A constant feature': 'constant value',
})

What’s important is that features should not be hardcoded, but rather be randomly generated with the PRNG, and they should always match the visual characteristics of the Token (ie reflect the settings behind the generative process of the token).

$fx.features() should only be called once, as multiple calls of $fx.features() will erase features set by a previous function call. For the fx(hash) module to pick up the artist set features, the $fx.features() function must be called once the page is loaded. For instance, the following code might result in features not getting picked up by our module:

// WILL NOT WORK CONSISTENTLY
setTimeout(() => {
$fx.features({
	// here define the token features
})
}, 1000)

Fxhash automatically computes the rarity of a particular feature by counting the number of occurences among all the tokens of the collection. Two feature values are considered the same if a strict equality between those returns true. If you want the rarity of a feature to be meaningful, you must define its values in a way that ensures multiple occurrences to appear.

For instance, this will not work well with the rarity module:

$fx.features({
// each token will have a different "Intensity" feature value between 0 and 1
Intensity: fxrand(),
})

If defined in such a way, each token will have a different Intensity feature value and thus they will all have the same rarity in regard to that feature. What you can do instead, is to assign a string to a range of values:

function getFeatureString(value) {
	if (value < 0.5) return "low"
	if (value < 0.9) return "medium"
	else return "high"
}

$fx.features({
	// feature can only be "low", "medium" or "high"
	Intensity: getFeatureString(fxrand()),
})

With this implementation, the value of the feature will only be low, medium or high. This ensures that the rarity module will correctly assign the Intensity feature rarity when a Token is minted. Of course, this is a very naïve implementation, you may want to adapt it to fit your needs in a better way.

$fx.getFeature(name)

This function outputs the value of a feature, given its name. Must be called after $fx.features(). The name parameter should match a key defined of the object passed to $fx.features():

// defining the features
$fx.features({
	"First feature": 0.5,
	"Another feature": true,
})

// outputs "0.5"
console.log($fx.getFeature("First feature"))

// outputs "true"
console.log($fx.getFeature("Another feature"))

Since this function requires the name of the feature to be passed to it, it can become quite verbose and redundant to call it every time you need to access the value of a feature, especially if you need this value a lot. In such a case, we recommend storing the feature value in a variable instead:

const feat1 = "feature value here"
$fx.features({
	"A very long feature name, not practical": feat1,
})

// same outputs
console.log($fx.getFeature("A very long feature name, not practical"))
console.log(feat1)

$fx.getFeatures()

Returns the whole object passed to the $fx.features(object) function. Must be called after $fx.features().

// first define the features
$fx.features({
	"feat 1": 0.8,
	"feat 2": true,
})

// outputs:
// {
//   "feat 1": 0.8,
//   "feat 2": true
// }
console.log($fx.getFeatures())