FXHASH

Project creation

This section will provide you with a boilerplate for your project. The tools described are not mandatory and only offer an easy starting point to create your own generative artwork that can be published on fx(hash). If you are experienced with code, you might aswell bootstrap your own project setup based on the provided informations.

Table of Contents

Pre-requisitss

As mentioned, since Generative Tokens on fx(hash) are their own websites, they generally need to be composed out of HTML, CSS, and Javascript for a browser to be able to interpret them. The modern web now also supports other languages, like Typescript for instance, as well as Shaders, but we’ll cover that in more depth in another section.

While fx(hash) takes care of injecting the hash into your artwork, such that it produces different but deterministic iterations, and delivering it to your collectors’ wallets when they purchase an iteration - your task as an artist is to create the code that generates these outputs.

This sounds more complicated than it actually is; in this section we’ll provide a run-down of how this works.

How is a Generative Token structured

This section covers different aspect on the structure and specifications of Generative Tokens.

Project structure

All the files and folders needed by your project must be in the same directory, with an index.html file at its root.

Resources

When you link to a file in your index.html, paths must be relative.

  • src="./path/to/file.js" -> OK
  • src="/path/to/file.js" -> NOT OK

You can use as many sub-directories as you see fit.

@fxhash/project-sdk

It is required to include the latest version of the @fxhash/project-sdk into your project. The file should be called fxhash.js and must be included in the <head> section of the index.html.

You can find the latest version of the @fxhash/project-sdk here
You can read more about the @fxhash/project-sdk here

The fxhash boilerplate

We recommend using the fxhash boilerplate for the purpose of developing your generative token, as it is the simplest way to get started. Once you create a project based with the boilerplate there are no further requirements to publish your project on fx(hash) - you can actually zip your project as is and proceed through the minting interface.

More details about the boilerplate can be found in the README of the boilerplate’s github repo.

fxhash boilerplatefxhash official boilerplate, the most simple and recommended setup to publish a generative artwork on fxhash.

The fx(hash) command line interface (CLI)

We offer a CLI exposing several commands that will help you develop your generative artwork. Using the CLI has the advantage that you don't need to install software into your project. All tools come from one central place and your projects only contain the files that are relevant for your artwork.

For using the CLI there are two system requirements:

  • node >= 18.0.0
  • npm >= 9.0.0

Once you have met those requirements, you are ready to use the @fxhash/cli.

@fxhash/cliThe fx(hash) CLI exposes all toolkit features through a single CLI.

Installation

You can run all commands via npx.

npx fxhash <command> [args]

Alternatively you can install the package with -g flag to make it globally available in your terminal. This means you won't have to prefix the commands with npx.

npm install -g fxhash

Usage

We will provide you with a common usecase for a possible workflow for creating a generative artwork with the CLI. If you want to get a complete overview of the API that the CLI exposes you can check here:

fxhashAn alias for the @fxhash/cli, so that it can be called via npx fxhash

1. Create a new project

When you are using the CLI you can create a new project directly from the CLI. You don't need to clone the boilerplate from github. To create a new project you can use:

fxhash create 

The terminal will ask you to provide a name and choose a template for your project. If you are new to the platform and/or don't need any special customization, we highly recommend you to use the simple template.

2. Starting the development environment

After you have created your new project you should find a folder that has the name you provided when creating the project. You are ready to start the development of your generative artwork. The following command will start your project within the fx(lens) environment, which will provide you with the necessary tools to test all the functionalities the @fxhash/project-sdk provides for the creating of generative art.

fxhash dev

The command should open a browser window, where you can see your project within the fx(lens) environment.

You can find more information about the development environment fx(lens) in the section below.

3. Building your project

When you are done with your artwork and tested it with the fx(lens) environment. You are ready to publish your project on the fxhash platform. The platform requires you to upload a .zip of the contents of your project. You an create this .zip file by running the following command:

fxhash build

Will create an upload.zip file in your project folder. This file can be uploaded and published on the fxhash platform as it is.

You can find more information about the publishing process in this section.

Guidelines

Some guidelines must be followed to ensure your Generative Token works properly.

Network requests

You cannot make any network request. If you need an external library/font/image, you must put it in your project folder. I know, this isn't an ideal workflow, but the point is to create self-contained tokens which can execute properly regardless of external conditions.

Respond to window size

Your web page must be responsive (ie adapt itself to any screen size). Moreover, we advise that your application should respond to the "resize" event of the "window". It may eventually happen in the lifetime of the tokens that the viewport size changes during its execution. If you want to keep a fixed size canvas, you can do so, and maybe center the canvas in the viewport.

Random numbers generation

Your program must use pseudorandom number generation with a seed, where the seed is the fxhash variable. You can use the $fx.rand() function for that matter.

Other

  • the ZIP file must be <= 30 MB. Please try to optimize your projects as much as possible.

Best practices and common mistakes

A list of best practices and common mistakes (and how to fix them) to ensure that your token has as long a life as possible.

Test often

This section comes first as it's the most important in ensuring that your token is as good as you can make it. Remember that once you release, you can't edit the token, so make sure to test as often as you can when developing.

Testing often will also allow you to catch problems early that would become big issues later on. Nobody likes to get to the minting stage - or worse, selling out - only to discover that their token doesn't work properly.

Resolutions and DPRs

Ensure your token looks the same in all resolutions and DPRs.

It is ideal if your token produces the same artwork at different sizes. Make sure to test your token often at different resolutions and DPRs. One of the most common pitfalls that artists fall into is not doing so and having their tokens look different at different sizes - as well as different to the preview - as a result.

There are a number of different ways of getting your token to work in a resolution independent manor. Jump into the creator-support channel if you'd like to ask any questions.

WebGL

WebGL is a big subject and there are a number of items worth talking about in relation to it.

Power of two textures and framebuffers

Some GPUs allow you to specify non power of two textures and framebuffers, however using non power of two textures and framebuffers will break the preview system.

WebGL on different silicone

WebGL is an emulation layer on top of different graphics APIs which talk to hardware, as such implementation of basic things like sine calculation and float precision can vary.

One important thing to remember about WebGL is that you should be doing as muchof your calculation up-front, in javascript, and providing those values to WebGL as uniforms.

WebGL and previews

As of right now the preview system doesn't have a GPU. As such, rendering your scene falls to the CPU, which will render WebGL but at an extremely low framerate.

If your token is WebGL then you want to make sure that you're rendering an accepable preview in the first couple of frames.

Computational complexity and previews

If your token is computationally expensive, then it's possible that the preview system will stumble over it and the signer will not be able to sign mints! Please be aware that there exist ways to generate less complex previews for your tokens, but the implementation of this necessarily needs to fall on you, the artist. Jump into the creator-support channel if you'd like to ask any questions.

Test often

This is such an important point that it bears mentioning twice.

  • Test often
  • Test in many different environments
  • Test using the same hash at different resolutions
  • Test in the sandbox as well as standalone

What is fx(lens) ?

fx(lens) is a web page which can be executed locally, designed to load and interact with fxhash projects in your local environment. It provides various tools which can be accessed via a minimalistic UI, facilitating the exploration of fxhash projects as they are being developped.

screenshot of fxlens

How to use

If you already have the CLI installed there is nothing else you need to do. The CLI already comes with fx(lens) included. You only need to run fxhash dev and it will start the fx(lens) development environment and run your project within the environment. If you haven't installed the fxhash CLI you should read about in the section above.

Using fx(lens) as a standalone

fx(lens) can also work as a standalone, and you can point it to any URL where a project is running. You can read the readme in the github repository for more details.

fx(lens)fx(lens) is an interactive environment to view, tweak and develop generative tokens for the fx(hash) platform

How does it work?

Running fxhash dev will start 2 servers, one for fx(lens) and one for your project, and will open fx(lens) pointing to the project in your browser (http://localhost:3000/?target=http://localhost:3301/).

If everything went well, you should see the following page:

fx(lens) capture after first opening

If you are running your own project of course you should see your own project running in the environment.