Essentials
Getting Started
Artist Guides
Parameter Definition Specifications
An overview of the parameter definition specifications and the different types of parameters that are currently available.
When calling $fx.params(definition), a definition array of parameter definitions must be passed to the function. This array must be constant, which means that the same value must be passed every time the code is executed. There cannot be any source of randomness in the definition.
A parameter definition is an object following strict guidelines. Example:
$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",
},
{
id: "color_id",
name: "A color",
type: "color",
},
])The TypeScript type for a parameter definition is:
// a parameter definition
type ParameterDefinitionType = {
id: string // required
name?: string // optional, if not defined name == id
type: "number" | "string" | "boolean" | "color" | "select" | "bigint" // required
default?: string | number | bigint | boolean // optional
update?: "page-reload" | "sync" | "code-driven" // optional
options?: TYPE_SPECIFIC_OPTIONS // (optional) different options per type (see below)
}Definition Specifications
Each property's role is outlined as follows:
id required
A string identifier, which will be used to get the parameter value later in the code. This is also used to populate an object of the different parameter [id; value] when the bytes are deserialized into values when $fx.params() is called.
Each id must be unique! Two parameters cannot have the same id.
name optional
A string which will be used as a display name on the minting interface. If not set, the parameter name will be its id. We recommend setting a name for every parameter so that collectors can see a nice text displayed next to the controller. We also recommend sticking with short names to keep the minting UI clean.
type required
The type of the parameter, must be one of the available types (number, string, boolean, color, select, bigint). See below for each type specification.
default optional
A default value for the parameter. If defined, when the minting interface with the controllers is loaded, the corresponding value of the controller will be set to this one. If not set, the controller value will be set to a random one within the constraints defined in the parameter options.
update optional
Specifies the update mode of the parameter. There are 3 update modes available:
page-reload: (default) the parameter can only be updated from the fxhash UI, the whole project will be refreshed when any page-reload parameter is updatedsync: the parameter can only be updated from the fxhash UI, aparams:updateevent will be sent to the project when the parameter is update. The page is not refreshed, so you need to handle the update of the view yourselfcode-driven: the parameter can only be updated from your code, by emitting aparams.updateevent.
General overview of params update in the fx(params) section.
options optional
An object with type-specific options. Each type has specific options, described in the section below. Default values are used for each option if not defined. The default values are also described in the section below.
The different parameter types
Each type comes with specifications:
- a list of available options
- a format in which the bytes are deserialized and made available to your code
- a kind of controller which will be displayed to modulate the parameter (this will happen outside the context of the piece itself, most often in a parent context)
Let's go over each type:
number
Numbers are deserialised into javascript float64 numbers (default javascript number type).
Option Table
Property | Type | Default | Description |
min | number | The minimum value the number can take. Controllers will be bound to [min; max] | |
max | number | The maximum value the number can take. Controllers will be bound to [min; max] | |
step | number | undefined | If defined, specifies the granularity that the value must adhere to. Only values which are equal to the basis for stepping ( default if specified, min otherwise, eventually the random value generated if none are specified) are valid. If undefined, any number is accepted. |
Example:
$fx.params([
{
id: "a_number",
name: "A number",
type: "number",
default: 5,
options: {
min: -10,
max: 10,
step: 1,
},
},
])Corresponding controller: a slider and a text input
string
Strings are deserialised into a series of UTF-8 characters.
Option Table
Property | Type | Default | Description |
minLength | number | 0 | The minimum number of characters which has to be inputted |
maxLength | number | 64 | The maximum number of character which can be inputted. We recommend keeping this value as low as possible, because this will always be the number of bytes sent onchain, even if a smaller string is inputted. |
Example:
$fx.params([
{
id: "a_string",
name: "A string",
type: "string",
default: "Default value",
options: {
minLength: 5,
maxLength: 32,
},
},
])Corresponding controller: a text input
boolean
Booleans are deserialised into native javascript booleans.
There are no available options for the boolean type.
Example:
$fx.params([
{
id: "a_boolean",
name: "A boolean",
type: "boolean",
default: false,
},
])Corresponding controller: a checkbox
color
Colours are serialised with 4 bytes, each byte representing the value between 0 and 255 of one channel (red, green, blue, alpha). When a colour is deserialised, it is processed into an utility-object to facilitate their usage.
The object is constructed as follows:
{
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 },
}
}There are no available options for the color type.
Example:
$fx.params([
{
id: "a_color",
name: "A color",
type: "color",
default: "abababff",
},
])Corresponding controller: a color picker and a text input
bytes
Arbitrary data which can only be manipulated with code, not from the UI; the update mode must be code-driven. Allows to store bytes in an optimised way, the bytes are serialised to hexadecimal and deserialised to Uint8Array.
Property | Type | Default | Description |
length | number | 0 | (Required) The maximum number of bytes which can be stored by this bytes parameter buffer. |
Example:
$fx.params([
{
id: "some_bytes",
name: "Some bytes",
type: "bytes",
update: "code-driven", // required!!
options: {
length: 4,
},
// the default value must be an Uint8Array
default: new Uint8Array([0, 255, 48, 57]),
},
])select
A select is defined by a list of strings, where each string defines an option which can be selected. A select can take up to 256 entries. A select is stored as a single byte on-chain, which is the hexadecimal representation of a number between 0 and 255, corresponding to the index of the selected option in the array of options. When deserialised, the string of the option is extracted.
The options property of a select is required and must be an array of strings, corresponding to the available options.
Option Table:
Property | Required | Type | Default | Description |
options | Required | string[] | / | A list of strings, corresponding to available options in the select. |
Example:
$fx.params([
{
id: "a_select",
name: "A select",
type: "select",
default: "one",
options: {
options: ["one", "two", "three", "four"],
},
},
])// output example:
// "one"
console.log($fx.getParam("a_select"))Corresponding controller: a select with various options
bigint
A bigint is deserialized into an int64, which is the BigInt javascript type. Bigint can represent very big integer values which cannot be represented usually with javascript float numbers (between -9223372036854775808 and 9223372036854775807). If you need an integer value between -9007199254740991 and 9007199254740991, use the number type instead as integer values can be represented with 100% precision with float64.
Option Table:
Property | Type | Default | Description |
min | number | -9223372036854775808 | The minimum value the number can take. Controllers will be bound to [min; max] |
max | number | 9223372036854775807 | The maximum value the number can take. Controllers will be bound to [min; max] |
Example:
$fx.params([
{
id: "a_bigint",
name: "A BigInt",
type: "bigint",
default: 1458965n,
options: {
min: -1000000000000000n,
max: 1000000000000000n,
},
},
])Corresponding controller: a slider and a text input
← Previous