Essentials
Getting Started
Artist Guides
Project Setup and Artist Tools
The fx(hash) API
Generative Art with fx(params)
Browser Based Generative Art
Releasing your Project
Detailed explanations of the individual API functions related to fx(params).
<aside> <img src="https://prod-files-secure.s3.us-west-2.amazonaws.com/f9d1e984-50ed-4650-a543-95d2b6c0ba90/fd24109f-c766-4137-88d5-f3a39c682da2/fx_doc-icon_info_001.png" alt="https://prod-files-secure.s3.us-west-2.amazonaws.com/f9d1e984-50ed-4650-a543-95d2b6c0ba90/fd24109f-c766-4137-88d5-f3a39c682da2/fx_doc-icon_info_001.png" width="40px" /> An overview and explanation of how the fx(params) module of the API works can be found here:
</aside>
<aside> <img src="https://prod-files-secure.s3.us-west-2.amazonaws.com/f9d1e984-50ed-4650-a543-95d2b6c0ba90/791bdb41-947a-475b-ad5f-88bdc444a606/fx_doc-icon_info_001.png" alt="https://prod-files-secure.s3.us-west-2.amazonaws.com/f9d1e984-50ed-4650-a543-95d2b6c0ba90/791bdb41-947a-475b-ad5f-88bdc444a606/fx_doc-icon_info_001.png" width="40px" /> A reference for the general API functions can be found here:
</aside>
| Function | Function Signature | Purpose Effect |
|---|---|---|
params() |
(array) => void | Define collector-modifiable parameters for your piece by calling this with an array. |
getParam() |
(string) => any | Returns the value of a param via its ID. |
getParams() |
() => object | Returns a dictionary of all parameter key-value pairs, as currently set. |
getRawParam() |
(string) => string | Provides the raw parameter data (as a bytes string) as it was passed to the iteration. |
on() |
(string, function, function) => function | Registers an event listener and returns a function to deregister it. |
emit() |
(string, any) => void | Sends an event to the parent context, useful for dynamic parameter updates from within the code. |
$fx.params(definition)The $fx.params(definition) function is necessary to create an fx(params) piece, it takes as input a list of parameters definitions that collectors can modulate and tweak to create their own custom iterations. Parameter definitions are object that contain a number of key/value pairs that describe the parameters.
<aside> <img src="https://prod-files-secure.s3.us-west-2.amazonaws.com/f9d1e984-50ed-4650-a543-95d2b6c0ba90/ce3264a0-16a3-4ac2-a9c2-63ce9213e993/fx_doc-icon_info_001.png" alt="https://prod-files-secure.s3.us-west-2.amazonaws.com/f9d1e984-50ed-4650-a543-95d2b6c0ba90/ce3264a0-16a3-4ac2-a9c2-63ce9213e993/fx_doc-icon_info_001.png" width="40px" /> You can learn more about the speficications for the these parameter definitions here:
Parameter Definition Specifications
</aside>
Here is an example of this definition array:
// this is how params are defined
$fx.params([
{
id: "number_id",
name: "A number",
type: "number",
options: {
min: -10,
max: 10,
step: 0.1,
},
},
{
id: "boolean_id",
name: "A boolean",
type: "boolean",
//default: true,
},
{
id: "color_id",
name: "A color",
type: "color",
},
])
Invoking the $fx.params() function has a number of important effects:
code-driven)fxparams URL parameter, processes the bytes and converts it into values based on the provided definitions and maps them to their respective variables to generate the corresponding artwork.<aside>
<img src="https://prod-files-secure.s3.us-west-2.amazonaws.com/f9d1e984-50ed-4650-a543-95d2b6c0ba90/4af410c9-812e-4d07-8a96-e00a81f0a28a/fx_doc-icon_notes_001.png" alt="https://prod-files-secure.s3.us-west-2.amazonaws.com/f9d1e984-50ed-4650-a543-95d2b6c0ba90/4af410c9-812e-4d07-8a96-e00a81f0a28a/fx_doc-icon_notes_001.png" width="40px" /> $fx.params() must be called before trying to access any parameter value with the parameter fetching functions that follow.
</aside>
$fx.getParam(id)Returns the value of a parameter based on the params definition provided to $fx.params(definition) and the input bytes passed to the code via URL parameters (&fxparams={byte_sequence_here}), the bytes sequence will be processed by $fx.params() when it is called.
The $fx.getParam(id) will fetch and return the value of parameter through its id as defined in your params definition:
// define the params
$fx.params([
{
id: "a_param_id", // this property will be used for $fx.getParam(id)
name: "A random name",
type: "boolean",
},
{
id: "another_param",
name: "Super param!",
type: "color",
},
])
// depending on the sequence of bytes injected into the code when it's executed,
// the values will be different
// get the value of parameter "A random name"
// output example:
// true
console.log($fx.getParam("a_param_id"))
// get the value of parameter "Super param!"
// output example:
// {
// arr: {
// rgb: [25, 6, 158],
// rgba: [25, 6, 158, 104],
// },
// hex: {
// rgb: "#19069e",
// rgba: "#19069e68",
// },
// obj: {
// rgb: { r: 25, g: 6, b: 158 },
// rgba: { r: 25, g: 6, b: 158, a: 104 },
// }
// }
console.log($fx.getParam("another_param"))
Depending on the type of the parameter, the fxhash snippet may apply extra processing to facilitate their usage in your code. For instance, in the case of color parameter, it will be returned in different forms. See the parameter definition specifications section for more details on each parameter type.
$fx.getParams()Returns an object containing all parameters, where the keys in this object are the individual parameter ids:
// define the params
$fx.params([
{
id: "a_param_id", // this property will be used for $fx.getParam(id)
name: "A random name",
type: "boolean",
},
{
id: "another_param",
name: "Super param!",
type: "color",
},
])
console.log($fx.getParams())
// output example:
// {
// a_param_id: false,
// another_param: {
// arr: {
// rgb: [25, 6, 158],
// rgba: [25, 6, 158, 104],
// },
// hex: {
// rgb: "#19069e",
// rgba: "#19069e68",
// },
// obj: {
// rgb: { r: 25, g: 6, b: 158 },
// rgba: { r: 25, g: 6, b: 158, a: 104 },
// }
// }
// }
// the byte sequence injected determines the value of the parameters
$fx.getRawParam(id)Given a parameter id, $fx.getRawParam(id) returns the hexadecimal string byte sequence corresponding to that parameter, before processing and converting it into a value:
// define the params
$fx.params([
{
id: "a_param_id", // this property will be used for $fx.getParam(id)
name: "A random name",
type: "boolean",
},
{
id: "another_param",
name: "Super param!",
type: "color",
},
])
// depending on the sequence of bytes injected into the code when it's executed,
// the values will be different
// get the value of parameter "A random name"
// output example:
// "01"
console.log($fx.getRawParam("a_param_id"))
// get the value of parameter "Super param!"
// output example:
// "19069e68"
console.log($fx.getParam("another_param"))
$fx.emit(eventId, data)This function is mainly used for the purpose of updating parameters that have their update mode set to code-driven. As its name suggests, $fx.emit(eventId, data) allows you to emit events (think of it like a signal), to an fxhash specific pipeline of events, which can then be listened to by the $fx.on() function. Currently there is only one type of event that is supported, namely the param:update signal.
Additionally, this event can also carry a payload which can be specified with the second input parameter of the $fx.emit function, the data variable. The data variable should be an object where the key/value pairs are the parameter ids and the updated associated values respectively. This is still subject to the constraints of the parameter (as set by its parameter definition), so for instance if a number between 0 and 10 is expected and you pass a value of 12, it will clamp to 10. You are not required to pass all the parameters in the data, only those which need to be updated.
Here’s an example, let’s first set up a couple of parameters:
// define your parameters
$fx.params([
{
id: "mouse_x",
type: "number",
// a code-driven parameter
update: "code-driven",
},
{
id: "number_2",
type: "number",
// a code-driven parameter
update: "code-driven",
},
{
id: "number_3",
type: "number",
// a normal parameter, cannot update with params:update
update: "page-reload",
},
])
And then send out an event whenever we move the mouse:
// example: when the mouse moves, we update the first parameter
window.addEventListener("mousemove", evt => {
const X = evt.clientX / window.innerWidth // normalized X position of mouse
// we request the update of a parameter
$fx.emit("params:update", {
mouse_x: X,
})
})
Here we used a native Javascript eventlistener to detect whenever the mouse is moved, making it in turn trigger the $fx.emit() function to update the mouse_x parameter.
Following is the typescript definition of the $fx.emit function:
type FxEmitFunction = (
eventId: string
data: any
) => void
$fx.on(eventId, handler, onDone)The $fx.on() function listens to events in the fxhash pipeline that are emitted by $fx.emit(). Currently there is only one type of event that is supported, namely the param:update event. $fx.on() can then trigger functions when this event is registered and certain conditions are met. Note that the eventId must match an existing eventId that you can subscribe to.
The handler is the function that is called when the event is triggered. Additionally you can opt-out of the default behaviour of an event handler by returning false from the handler. The onDone function is called as the last thing of any event, e.g. after the default behaviour of the event was applied.
// define your parameters
$fx.params([
{
id: "number_id",
type: "number",
update: "sync",
},
])
function main() {
// render artwork
}
$fx.on(
"params:update", // subscribe to the params update event
newValues => {
// opt-out param update when number_id is 5
if (newValues.number_id === 5) return false
// opt-in any other param value update
return true
},
() => main() // render artwork when event was handled
)
Following is the typescript definition of the $fx.on function:
type FxOnFunction = (
eventId: string
handler: (...args) => boolean | Promise<boolean>
onDone: (optInDefault: boolean, ...args) => void
) => () => void
The function returned by the $fx.on function can be called to remove the registered event listener.
const removeListener = $fx.on("params:update", newValues => {
// do something
})
removeListener() // <-- Will remove the event listener
Note: there are 2 ways to apply changes to the UI when you emit a parameter from the code:
// FIRST WAY
// Emit the update, and update the view only when receiving the params:update
// back. This ensures a proper flow of data, and a proper sync of the minting
// UI and your project
window.addEventListener("mousemove", evt => {
const X = evt.clientX / window.innerWidth
$fx.emit("params:update", {
mouse_x: X,
})
})
$fx.on("params:update",
() => {}, // do nothing to check the params received
() => { // once the update is fully registered, update the view
draw()
// in this case draw() can rely on $fx.getParam("mouse_x") to be synced with
// the up-to-date value
}
)
// SECOND WAY
// Custom draw logic where the params effects are applied right after emitting
// the update
window.addEventListener("mousemove", evt => {
const X = evt.clientX / window.innerWidth
$fx.emit("params:update", {
mouse_x: X,
})
// here trigger a draw, but you need to handle the change in value manually,
// as $fx.getParam("mouse_x) will point to the old value
draw(X)
})
← Previous
Update Modes and Code Driven Parameters
Next →