Essentials
Getting Started
Artist Guides
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:
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:
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:
- API Overview: A run-down of all the API methods (functions)
- API Reference: A look at each one of the API methods in detail
- Using Randomness Correctly: notes on using the PRNG that the API provides
Why do we need to use the API?
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.
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.
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.
$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:
A complete run-down of all API functions can be found in the API Overview A detailed explanation of these functions can be found in the API Reference.
← Previous
Next →