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:

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:

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 Number.MIN_VALUE The minimum value the number can take. Controllers will be bound to [min; max]
max number Number.MAX_VALUE 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

Untitled


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

Untitled


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

Untitled


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

Untitled


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

Untitled


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:

| --- | --- | --- | --- |

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

Untitled