Project SDK & API: Integration and Use

Project SDK & API: Integration and Use


Welcome to fxhash
Web3 Fundamentals
The fxhash Ecosystem

Getting Started

Initial Setup
Product Overview

Artist Guides

Project Setup and Artist Tools
The fx(hash) API
Generative Art with fx(params)
Browser Based Generative Art
Releasing your Project

Project SDK & API: Integration and Use

An overview of the fxhash project SDK and API

In the previous sections we've had a look at the structure of an fxhash project, introduced the boilerplate as a minimal starting point for new projects and also had a first look at the CLI as an alternative method to setting up blank projects. Both the boilerplate and the CLI are a part of the fxhash Project SDK - a toolbox that facilitates the development of fxhash projects:

What is an SDK? SDK is an abbreviation for the term Software Development Kit, an SDK usually represents a bundle of code, tools, and documentation provided by the creators of a platform for third party developers, and is aimed at aiding them in creating software that is compatible with the platform.

In this manner the fxhash SDK is a number of resources that fxhash provides for artists to aid them in creating their projects, this encompasses this documentation, the artist tools, and most importantly the fxhash.min.js script.

This script file is also referred to as an API:

What is an API? The abbreviation API stands for Application Programming Interface, and refers to the code part of an SDK. It's a software-to-software interface that allows developers to build platform specific software. APIs usually provide numerous functionalities that are useful and sometimes necessary for the purpose of compatibility.

In other words, the fxhash API is simply a fancy term to refer to the functions that the fxhash.min.js script exposes inside the scope of an fxhash project. Artists need to make use of these functions to create their generative artworks, besides providing useful functionality to build deterministic generative artworks it also required for projects to work properly once uploaded to fx(hash).

How does this API work? Why do we need to use it? And moreover, how do we use it? All of these questions should be answered by the end of this page. We'll learn:

  • Why we need to use the API for developing generative artworks
  • What the included fxhash.min.js script file does inside our project
  • How to make use of the API functions

If you’re more experience, know what an API is, and simply want to have an overview of the different functions it provides you can consult these pages of the docs for an overview, reference and usage guide:

Why do we need to use the API?

Projects on fxhash are deterministic generative artworks that can reliably re-generate the same output when the same input hash is used injected into their code.

The fxhash API is a code library designed for developing deterministic generative systems. It provides a pseudo random number generator (PRNG) that can be used as the primary source of randomness throughout a generative token's code. Moreover, it automatically seeds this pseudo random number generator with the hash that is injected into the code.

Furthermore, depending on what kind of token you want to develop, and depending on how the randomness should behave, the SDK provides a couple of options for that as well. It provides a number of functions to generate different kinds of random numbers and/or make random decisions throughout the code.

Technically, the PRNG provided by the API isn't mandatory - as an artist you can also equivalently implement your own PRNG function, under the condition that it is seeded correctly with the hash that the API script injects into your code. The hash is therefore the only part of the API that is required. We strongly recommended to use the API however, in this manner you can focus on building your generative artwork rather than spending time on programming a PRNG.

What does the fxhash.min.js script file do?

When we had a look at the structure of an fx(hash) project and introduced the boilerplate, we’ve seen that the index.html should reference the fxhash.min.js script within it’s head tag. By doing so the fxhash.min.js script is run when the webpage is viewed in a browser. Although there is a lot of code inside of the fx(hash) script file, the main purpose of it is the creation an $fx object and attaching it to the window object as a property.

What is the window Object? In JavaScript, the window object represents the global context for a web page or a browser environment. It is the top-level object that contains global variables and functions accessible throughout the entire JavaScript runtime in a web page. Attaching new properties/variables makes them accessible throughout the scope of all scripts, which is why the $fx API object is attached as such a property.

This $fx object is essentially a container for the functions of the fxhash project API, making them available for usage in the artist script, namely the index.js file.

What is this $fx object?

If you’ve already installed the CLI and created a new blank fxhash project, we can see for ourselves what this $fx object is. While keeping all of the files unchanged, we’ll only delete the contents of the index.js file, and replace it with a single line of code that logs this $fx object to the console:

console.log($fx) // logging the $fx object to the console

If we now open the index.html in our browser, we'll get a blank, white browser window (because we deleted the previous code), but if we check the console however, we'll see that something has been logged:


The $fx object that is instantiated by the fxhash.min.js script

This is the content of the $fx object created by the fxhash.min.js script. There's a bunch of stuff inside of it: a number of properties, functions, and other objects. All of these are now accessible in the artist script and available for our convenience to build a generative artwork with.

What is an Object in programming? Objects in programming are usually containers for variables and functions. The contained variables and functions are referred to as member variables and methods respectively. They can be accessed and invoked using the dot notation, for example $fx.rand() invokes the rand() function contained inside the $fx object.

One last note here, it is not recommended to change the code inside of the fxhash.min.js script for your generative token to work properly:

You should not change or edit the code inside of fxhash.min.js for your GENTK to function properly.

A complete run-down of all API functions can be found in the API OverviewAPI Overview A detailed explanation of these functions can be found in the API ReferenceAPI Reference.

← Previous


Next →

API Overview