​
Defining an Item

To define an item in Forge, you’ll need to provide the following details:
  • Name: A unique name for the item.
  • Thumbnail (optional): A visual representation of the item, used for displaying the item in a space or within your game.
  • Roll Numerator: A numerical value that determines the item’s likelihood of being rolled.
  • Classifier Options: Each item can have multiple classifier options that categorize it based on various characteristics.
The roll denominator is determined automatically by summing up all of the roll numerators. We recommend leaving the roll numerator for an item at 100, and modifying the classifier options to determine the chance of drops. There may of course be times where you want to make specific items more unique later on and this should give you a good baseline.
Here’s an example of defining an item: 
{
  "name": "Mystic Sword",
  "thumbnail": "https://example.com/images/mystic-sword.png",
  "rollNumerator": 10,
  "classifiers": {
    "rarity": "legendary",
    "type": "weapon",
    "element": "fire"
  }
}

​
Attributes and Roll Mechanics

Items are not just static components; they possess attributes that can be rolled to introduce variability and uniqueness. These attributes can influence the item’s effectiveness, appearance, and behavior in the game.
  • Attributes: Define specific characteristics of an item that can vary (e.g., damage, durability, magical properties).
  • Rolling Attributes: When an item is instantiated, its attributes are rolled based on predefined ranges or probabilities.

​
Classifiers

Classifiers are used to categorize and group items, making it easier to manage and utilize them within the game. Each classifier represents a characteristic by which items can be grouped or filtered. For example:
  • Rarity: Common, Uncommon, Rare, Epic, Legendary
  • Type: Weapon, Armor, Potion, Tool
  • Element: Fire, Water, Earth, Air
By defining classifier options for each item, you can create a structured and organized inventory system.

​
Item Instances

Once an item is defined, instances of the item can be created for users using the API Reference for Item Instances. These instances are the actual in-game objects that players interact with, trade, and use. Example API Call to Create an Item Instance: 
POST /items
{
  "itemId": "mystic_sword",
  "userId": "user123",
  "userSpaceId": "space456"
}
Response: 
{
  "itemInstanceId": "itemInstance789",
  "itemId": "mystic_sword",
  "userId": "user123",
  "userSpaceId": "space456",
  "attributes": {
    "damage": 50,
    "durability": 100
  },
  "createdAt": "2024-07-09T12:34:56Z"
}

​
Summary

Items in Forge are powerful and flexible components that form the backbone of your game’s item management system. By defining items with specific attributes, classifiers, and optional thumbnails, you can create a rich and engaging game environment. The ability to roll item attributes and classify items ensures a dynamic and organized gameplay experience. Item instances can be easily created and managed using the provided API, facilitating seamless integration into your game world. For more details on how to interact with item instances, refer to the API Reference for Item Instances.