NFT Collection Generator

About

This is a simple Node.js project that uses a list of pre-configured traits and image layers to generate a unique set of images and metadata files for a collection of NFTs. You would be able to create your own collection by updating the traits configuration and the image layers.

Getting Started

Prerequisites

• Download and install Node.js and npm

Installation

1. Clone the repo

   git clone https://github.com/manuelpires/nft-collection-generator.git

2. Inside the repo directory install NPM packages

   npm install

Usage

There's an example configuration in the config.js file, and there's also some pre-defined image layers in the traits folder. You can test and run this project with that pre-existing configuration to see first how everything works and to see the results.

Test the configuration

Test the current configuration in the config.js file

npm test

This will only test if the current configuration is correct or not.

Run the project

Run the project with the current configuration

npm run build

This will execute the main script. If successful, it will:

• Print logs with statistics about the results in the console
• Generate a folder with all the tokens images
• Generate a folder with all the tokens metadata files

Other scripts

Update images base URI

After running the project, you can update the images base URI inside all generated metadata files by running:

npm run update-base-uri

This will take the current value of IMAGES_BASE_URI inside config.js and use it to update all metadata files.

Create GIF with images

After running the project, you can create a GIF using the generated images:

npm run create-gif

Calculate hash of images and provenance hash

After running the project, you can launch the following script to calculate the SHA-256 of every image generated, and also a provenance hash of the combination of all hashes:

npm run calculate-hash

Create Your Own Collection

To create your own collection of unique tokens, you'd have to edit only the config.js file and update the image layers in the traits folder.

The metadata generated by running this project should be compatible with OpenSea's Metadata Standards. If you are not familiarized with those standards, you should give that page a read as it would help a lot to understand how to update the config.js file. Also, make sure to first run the project with the example configuration and check out the generated metadata files for more clarification about the process.

Modify constants

These are the constants that you'd need to update in the config.js file:

config.GIF_FRAMES = 10; // only if you want to generate a GIF
config.IMAGES_BASE_URI = "https://base-uri-to-my-nft-images.com/";
config.IMAGES_HEIGHT = 350;
config.IMAGES_WIDTH = 350;
config.TOKEN_NAME_PREFIX = "My NFT #";
config.TOKEN_DESCRIPTION = "My NFT description.";
config.TOTAL_TOKENS = 100;

Modify traits list

You'd also have to modify the last variable called ORDERED_TRAITS_LIST that contains the array of all available traits for the tokens. Each trait has the following structure:

{
  display?: string;
  ignore?: boolean;
  type?: string;
  options: {
    allowed?: string[];
    forbidden?: string[];
    image?: string;
    value?: string | number;
    weight: number;
  }[]
}

Before modifying the traits list, please go through the next important instructions:

• For every trait in the list, each generated token will get one randomly selected option (value & image) from the options list. Except if the randomly selected option turns out to have a non-existent value, in which case the token won't get anything from that specific trait.
• The order of the list is important! It will define the order in which the images should be merged on top of each other to create the final token image. Tipically, the background trait should be the first in the array.
• The random selection of the option is based on its weight and its optional allowed/forbidden conditions. The weight of an option is relative to the weights of the other items in the same options array, and it should be an integer of at least 1. So if you put a weight of 10 in an option, it should have 10 more times chances to be selected that an option in the same array that has a weight equal to 1.
• If a trait is marked with ignore, then that trait won't be taken into account when defining token uniqueness. For instance, if you don't want the background of your tokens to affect their uniqueness, then you can mark that background trait with ignore: true.
• The optional allowed/forbidden arrays should include one or more strings that match option values of previous traits. When used, it will make this option only allowed/forbidden for tokens that have at least one of those string values previously selected. For reference, look at the allowed and forbidden arrays used as example in the config.js file. In this case an "Orchid" triangle would only be available for tokens with "Coral" or "Mint" backgrounds; and also a "Teal" triangle will not be available for tokens with "Robin" background.
• Each defined type inside a trait should be unique.
• If you leave a specific trait without a type field, it will be considered a "generic" trait. It's important that these kind of traits don't have any values in common with other traits inside their options array.
• Each image string should have the relative path to a specific PNG image.
• If you don't put an image field in every option with a defined value, some of your tokens (even with unique metadata) could turn out with the same generated image.
• The display field is only meant to be used with number values. Read more at the OpenSea's Metadata Standards.
• Depending on the amount of traits that you have and their amount of options, you will have a maximum amount of unique tokens that could be generated. It isn't recommended generating the exact maximum possible amount of unique tokens, because the script will keep searching no matter the odds until it finds each one of the combinations, leaving the weighting factors useless. As a recommendation, I would say that if you want to generate N tokens, then create a list of traits that can give you at least 2N tokens. The process will let you know if the value of TOTAL_TOKENS is too big when you try to run it.

Running the command npm test will verify that these set of rules are taken into account within your current configuration, and that the generated metadata would follow the standards. Use it!

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Manuel Pires - [email protected]

Project Link: https://github.com/manuelpires/nft-collection-generator