Essentials
Getting Started
Artist Guides
fx(params)
An introduction to the fx(params) module.
Traditionally, projects on fx(hash) generate random outputs for their collectors. This means that collectors have no prior knowledge as to what the iteration they will receive look like beforehand. This is because the hash that is used to seed the PRNG of the generative artwork, can not be known in advance. With fx(params) this paradigm changes.
From the collectors point of view, this changes a couple of things. Instead of directly collecting an iteration from a project, when a project that makes use of fx(params) is collected they obtain a mint ticket instead. This mint ticket is essentially a voucher that they can exchange for an iteration of the project.
This system is in place to give collectors the time to customise their iteration without having to worry about running out of time and the project completely minting out. Once a mint ticket is secured, the collector can then take their time crafting their own unique individual iteration. You can read more about this in the collector guides.
From the artist's point of view, to create an fx(params) piece, they will need to make use of the fx(params) module of the API. In this section we will give an overview of the module and explain how to use it. A detailed explanation of the different functions that this module provides can be found in the fx(params) API Reference.
Using the fx(params) Module of the API
Creating an fx(hash) project that makes use of fx(params) boils down to using the respective functions in the API such that certain variables in the code are exposed as collector tweakable parameters. The most important function in the API to this end is:
$fx.params(definitions) // API function that creates the parameters in the interface
Invoking the $fx.params()
function in your code informs fx(hash) that the project is intended to be an fx(params) piece. Equally important is that this function requires an input in form of an array that defines the desired parameters such that they can be created in the interface by fx(hash). During local development of your project these parameters will also appear in fx(lens).
For the purpose of an fx(params) piece, the definitions array needs to follow a specific structure:
definitions = [
{
id: "number_id",
name: "A number",
type: "number",
},
{
id: "boolean_id",
name: "A boolean",
type: "boolean",
},
{
id: "color_id",
name: "A color",
type: "color",
},
]
In essence this array is a list of objects, each of which represents an individual parameter. We'll talk more about the content of these objects in a second. Another effect of the $fx.params()
function is that it feeds the parameter values back into our generative artwork’s code, such that these values can be used for the purpose of shaping the rendered graphics.
Hence, if we were to copy the above snippet of code into the index.js
of a blank fx(hash) project and then boot up fx(lens) (via the CLI with fxhash dev
), we would see the following controllers show up in the interface:
To recap, the effect of $fx.params()
is twofold:
- It informs fx(hash) of the parameters that should be exposed in the minting interface. (during local development these parameters should appear in the fx(lens) interface)
- It exposes the value of these parameters in our code, such that the generative artwork’s characteristics can be based off of them.
Parameter Definitions
The objects contained in the definitions array that we pass as an input to the $fx.params()
function needs to follow a strict shape. In essence they are objects containing a number of key/value pairs that describe the controllers in the interface, such as the label next to the controller, the type of controller it is, the value it modulates, and the possible values that it can assume.
That is why we call these objects Parameter definitions, they essentially define (describe) the parameter controllers in the interface:
Parameter definitions also have optional properties, such as a name, that the artist can assign and will be displayed as a label in the controller interface. Another options
property can be appended depending on the type of the parameter.
Here's an example of such a parameter definition object:
{
id: "number_id", // required
name: "A number", // optional
type: "number", // required
options: { // optional
min: -10,
max: 10,
step: 0.1,
},
}
Some of the key/value pairs are optional, others are mandatory. The structure of these key/value pairs need to follow a strict set of specifications, you can find a detailed overview of these specifications in the Parameter Definition Specifications page.
How does fx(hash) inject Parameters?
Just like the iteration hash, parameters are passed into a generative token as a URL parameter, not individually, but under the form of a single serialised string that concatenates all of the parameters. The API then de-serializes this string splitting it into individual values and mapping them to their respective variables, such that they can be accessed throughout the code:
It would not be convenient at all to input this string manually, as such we recommend using fx(lens) to work on your fx(hash) projects. fx(lens) comes with built-in tools and hot-reloading to facilitate iterating on your project and manipulating the various parameters as you define those in your code.
Retrieving Parameter Values within the Artist’s Code
The snippet API exposes a set of utility functions which lets artists retrieve the active value of the parameters - these functions need to be called after the parameters have been defined with $fx.params()
:
$fx.getParam('parameter_id')
: gets the value of a single parameter by its id$fx.getParams()
: gets all the parameter values as an object$fx.getRawParam('parameter_id')
: gets the raw value of a single parameter as a hexadecimal string
The $fx.getParam()
function for example lets us fetch the active value of a parameter by its id (as a string value) - ‘active value’ here means the value that the parameter is set to by its respective controller in the interface (fx(lens) or minting interface):
const paramValue = $fx.getParam('number_id')
← Previous