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
- How is a Generative Token structured
- The fxhash boilerplate
- The fx(hash) command line interface (CLI)
- Guidelines
- Best practices and common mistakes
- What is fx(lens) ?
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"-> OKsrc="/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.
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.
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.0npm >= 9.0.0
Once you have met those requirements, you are ready to use the @fxhash/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:
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.
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.
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.
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.
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:
If you are running your own project of course you should see your own project running in the environment.