What is Token Grouping?

Token Grouping is a powerful feature on the Enjin Blockchain, accessible via NFT.io, designed to help you better organize your NFT collections. It allows you to create sub-categories, or "groups" within a single collection. Think of it as adding another layer of organization between your overall collection (e.g. "My Awesome RPG Game") and the individual tokens (e.g. "Sword of Slaying #001" "Health Potion #056").

For example, in a collection for an RPG game, you might have hundreds of different NFTs. Token Grouping lets you categorize these into logical sets like "Weapons", "Armor", "Potions", "Special Quest Items", or "Crafting Ingredients". This not only helps users navigate your collection but also allows app and game developers to easily reference these categories within their game's logic – for instance, an in-game enhancement system might be designed to require an item from the 'Weapons' group and several from the 'Crafting Ingredients' group.

Why Should You Use Token Grouping?

Utilizing Token Grouping offers several key benefits for NFT creators, game developers, and collection owners:

1. Improved User Navigation:
   • Easier Discovery: Helps users Browse your collection on NFT.io to quickly find the types of items they're interested in. Instead of scrolling through a massive list, they can navigate or filter by specific groups.
2. Facilitate On-Chain Game Mechanics & Utility:
   • Simplified Logic for App Systems: Token groups act as clear on-chain identifiers. This makes it easier for apps to check for specific types of items. For example:
     • A game could be designed to verify a player holds "any token from the 'Weapons' group" and "3 tokens from the 'Crafting Ingredients' group" as prerequisites for an in-game action like item enhancement or ability unlocking.
     • Implement game mechanics where owning multiple items from a specific, developer-defined group provides in-game advantages (e.g., set bonuses).
     • Gate certain game features or areas based on ownership of tokens from a particular group.
   • Note: Token Grouping provides the organizational framework. The actual game mechanics (like crafting, bonuses, etc.) are implemented by the apps developers, which can then reference these groups.
3. Efficient Collection Management:
   • Streamlined Organization: Makes it easier for you to manage large and diverse sets of NFTs within a single collection.
   • Metadata Inheritance: Simplify metadata management. If individual tokens are missing certain metadata (like a description or image), they can inherit it from the group they belong to (details on specific inheritance rules in the Metadata Inheritance section below).

Key Features & How-To Guides

Here’s how you can manage Token Grouping for your collections on NFT.io:

1. Creating a New Group

You can create groups either when minting a new item or directly from your collection's page.

• When Creating a New Item:
  1. In the "Create New Item" form, look for the "Groups" field under advanced options.
  2. Click "Select or create new Group" and choose "Create a Group."
  3. You'll see options for "Simple" or "Advanced" group creation.
     • Simple: Quickly set up a group with a name, media (image/video), and description.
     • Advanced: Offers more control, allowing you to import metadata from an existing NFT or input all metadata manually. [Screenshot: "Create a New Group" modal with Simple and Advanced options]
  4. Follow the prompts to define your group's details and then select the items you want to include. [Screenshot: "Choose Items" page for adding tokens to a new group]
  5. You may be asked to set the group order if selected tokens are already in other groups.
  6. Confirm the transaction(s) to create the group and add tokens. (Note: Grouping a large number of tokens might require multiple transactions.)
• From Your Collection Page:
  1. Navigate to your collection page.
  2. Look for a "Create Group" button or an option within the collection settings menu.
  3. This will open the "Create a New Group" modal, which also includes an "Automatic Creation" option (see section on Automatic Token Grouping below).

2. Adding Existing Tokens to an Existing Group

1. Find the token you want to add to a group (either in your collection view or token page).
2. If you are the collection owner, you'll see an "Add to group" option (often in the token card's 3-dots menu).
3. A modal will appear, with the current token pre-selected. [Screenshot: "Add to group" modal showing selected item and group list]
4. You can select an existing group to add the token(s) to, or create a new one from this modal.
5. If you need to add more tokens than the one you started with, click "Edit" to go to the "Choose Items" page.
6. Confirm the transaction(s) to add the tokens to the selected group.

3. Managing Your Groups (Editing & Removing)

• Editing a Group:
  1. You can usually find an "Edit Group" option on the Group Page (if you're the collection owner) or from the "Groups" tab in your Collection Overview.
  2. The "Edit Group Form" allows you to:
     • Modify the group's metadata (name, description, media).
     • Change which tokens are included in the group (add or remove items). [Screenshot: Edit Group form showing metadata fields and "Choose Items" section]
  3. Save your changes and confirm any necessary transactions.
• Removing a Group:
  1. The option to "Remove Group" is typically found within the "Edit Group Form."
  2. You'll be asked to confirm this action.
  3. Removing a group involves transactions to remove all tokens from the group and then destroy the group itself. This might require multiple transactions if many tokens or attributes are involved.

4. Automatic Token Grouping

This feature helps you quickly organize your collection by automatically identifying potential groups based on shared characteristics.

1. How to Start: You can find an "Automatic Token Grouping" option on your collection page (e.g., in the 3-dots menu or as a CTA) or when initiating group creation from the collection page.
2. How it Works:
   • The system analyzes tokens in your collection that aren't already grouped.
   • It looks for similarities based on:
     • Metadata URI: Tokens sharing the same metadata link (excluding URIs with {id}).
     • Token Name: Tokens with identical names (after removing numerical identifiers).
     • Media Attributes: Tokens sharing identical media files.
   • It requires at least three tokens with a shared property to suggest a group.
3. Review and Create:
   • You'll be shown a modal with the suggested groups, their proposed names, and the tokens within them. [Screenshot: Automatic Token Grouping modal showing a list of suggested groups]
   • You can:
     • Rename suggested groups.
     • Remove individual tokens from a suggested group.
     • Remove an entire suggested group. [Screenshot: Expanded view of a suggested group in the Automatic Grouping modal, showing individual tokens that can be removed]
   • Once you're happy, click "Create Groups" and confirm the transactions.

5. How Groups Appear in the NFT.io Interface

• Group Stack Cards: In collection and profile views, groups containing two or more tokens will be displayed as a "Group Stack Card." This card shows the group's media, name (with a folder icon), and the number of unique tokens it holds. [Screenshot: Example of a Group Stack Card in a collection view]
• Group Pages: Clicking on a Group Stack Card takes you to the Group Page. This page displays the group's details (image, name, description) and lists all the tokens belonging to that specific group. You can apply further filters here. [Screenshot: A Group Page showing group information and filtered tokens]
• Token Pages: On an individual token's page, any groups it belongs to will be listed (usually near the collection link). If a token is in multiple groups, the first group is shown, with a "+" icon to expand and see the others. Clicking a group name navigates to that Group Page. [Screenshot: Token page displaying a link to its group(s)]
• Collection Overview - Groups Tab: If your collection has at least one group, a "Groups" tab will appear on your collection overview page. This tab lists all groups within the collection, allowing for easy management. [Screenshot: The "Groups" tab in the Collection Overview, listing all groups]

Metadata Inheritance

A key benefit of grouping is metadata inheritance. If an individual NFT within a group is missing certain metadata properties (like a specific trait or description), it can automatically inherit these from the group's defined metadata. This means you can set common properties at the group level, saving you from having to define them for every single token.

[Provide the exact rules for how this inheritance works here (Brad is probably the go to person for this)]