# Create Attribute Source: https://docs.forgegames.org/api-reference/attributes/create-attribute swagger.json post /attributes Creates a new attribute for the specified team with name and optional min/max values. # Delete Attribute Source: https://docs.forgegames.org/api-reference/attributes/delete-attribute swagger.json delete /attributes/{id} Deletes an attribute from the team. Note: Will fail if attribute is attached to items. # List Attributes Source: https://docs.forgegames.org/api-reference/attributes/list-attributes swagger.json get /attributes Lists all attributes associated with the specified team. Attributes define properties that can be assigned to items or instances within the team context. # Update Attribute Source: https://docs.forgegames.org/api-reference/attributes/update-attribute swagger.json put /attributes/{id} Updates an existing attribute's properties including name, min, and max values. # Create Classifier Source: https://docs.forgegames.org/api-reference/classifiers/create-classifier swagger.json post /classifiers Creates a new classifier with associated options for a team # Delete Classifier Source: https://docs.forgegames.org/api-reference/classifiers/delete-classifier swagger.json delete /classifiers/{id} Deletes a classifier and its associated options # List Classifiers Source: https://docs.forgegames.org/api-reference/classifiers/list-classifiers swagger.json get /classifiers Lists the classifiers defined for a specific team. Classifiers group items and manage item-related properties. # Update Classifier Source: https://docs.forgegames.org/api-reference/classifiers/update-classifier swagger.json put /classifiers/{id} Updates an existing classifier's properties # List Item Instance Spaces Source: https://docs.forgegames.org/api-reference/item-instance-spaces/list-item-instance-spaces swagger.json get /item-instance-spaces Lists all spaces where item instances are currently stored within a team. Item instance spaces map items to specific user-defined locations. # Create an Item Instance Source: https://docs.forgegames.org/api-reference/item-instances/create-an-item-instance swagger.json post /item-instances Creates an instance of an item within the specified team. Instances are generated from item templates and can have custom attributes and configurations. # Delete an Item Instance Source: https://docs.forgegames.org/api-reference/item-instances/delete-an-item-instance swagger.json delete /item-instances/{id} # List Item Instances Source: https://docs.forgegames.org/api-reference/item-instances/list-item-instances swagger.json get /item-instances Lists all item instances within the specified team. Item instances represent individual occurrences of items with specific attributes and configurations. # Move an Item Instance Source: https://docs.forgegames.org/api-reference/item-instances/move-an-item-instance swagger.json post /item-instances/{id}/move Moves a specified item instance to a new location within the user's space grid. # Create Item Source: https://docs.forgegames.org/api-reference/items/create-item swagger.json post /items Creates a new item blueprint with specified attributes and classifiers. # Delete Item Source: https://docs.forgegames.org/api-reference/items/delete-item swagger.json delete /items/{id} Deletes an item and its associated attributes and classifiers. # List Items Source: https://docs.forgegames.org/api-reference/items/list-items swagger.json get /items Lists all items associated with the specified team. Items are blueprints that can be rolled, modified, or assigned attributes. # Roll an item Source: https://docs.forgegames.org/api-reference/items/roll-an-item swagger.json post /items/roll Generates a randomized variation of an item. This endpoint is commonly used for loot drops or creating unique instances in games. # Update Item Source: https://docs.forgegames.org/api-reference/items/update-item swagger.json put /items/{id} Updates an existing item's properties, attributes, and classifiers. # Get Aggregated Roll Statistics Source: https://docs.forgegames.org/api-reference/roll-events/get-aggregated-roll-statistics swagger.json get /roll-events/stats Returns team-level roll statistics including total rolls, unique items, and time-series data. Privacy-first: no individual roll exposure. # Get Item Drop Rates Source: https://docs.forgegames.org/api-reference/roll-events/get-item-drop-rates swagger.json get /roll-events/drop-rates Returns actual drop rates for items based on roll history. Useful for comparing expected vs actual drop rates. # Track Roll Event Source: https://docs.forgegames.org/api-reference/roll-events/track-roll-event swagger.json post /roll-events Records a roll event for telemetry. Stores team-level data only, no user-identifying information. # Create Space Source: https://docs.forgegames.org/api-reference/spaces/create-space swagger.json post /spaces Creates a new space for the specified team. # Delete Space Source: https://docs.forgegames.org/api-reference/spaces/delete-space swagger.json delete /spaces/{id} Deletes a space from the team. # List Spaces Source: https://docs.forgegames.org/api-reference/spaces/list-spaces swagger.json get /spaces Lists the spaces defined within a specific team. Spaces represent areas or containers where item instances can be stored. # Update Space Source: https://docs.forgegames.org/api-reference/spaces/update-space swagger.json put /spaces/{id} Updates an existing space's properties. # Create Template Source: https://docs.forgegames.org/api-reference/templates/create-template swagger.json post /templates Creates a new template with specified type and configuration for gacha, roguelike, idle, or card pack systems. # Delete Template Source: https://docs.forgegames.org/api-reference/templates/delete-template swagger.json delete /templates/{id} Deletes a template by ID. # Get Template by ID Source: https://docs.forgegames.org/api-reference/templates/get-template-by-id swagger.json get /templates/{id} Retrieves a single template by its unique identifier. # Get Templates by Type Source: https://docs.forgegames.org/api-reference/templates/get-templates-by-type swagger.json get /templates/type/{type} Retrieves all templates of a specific type (gacha, roguelike, idle, card_pack). # List Templates Source: https://docs.forgegames.org/api-reference/templates/list-templates swagger.json get /templates Lists all templates associated with the specified team. Templates define game system configurations like gacha, roguelike, idle, or card pack mechanics. # Update Template Source: https://docs.forgegames.org/api-reference/templates/update-template swagger.json put /templates/{id} Updates an existing template's name, type, or configuration. # Create a user space Source: https://docs.forgegames.org/api-reference/user-spaces/create-a-user-space swagger.json post /users/{userId}/spaces Creating a user space, allows the user to receive and store item instances. # Delete a user space Source: https://docs.forgegames.org/api-reference/user-spaces/delete-a-user-space swagger.json delete /users/{userId}/spaces/{id} # List user spaces Source: https://docs.forgegames.org/api-reference/user-spaces/list-user-spaces swagger.json get /users/{userId}/spaces # Create a user Source: https://docs.forgegames.org/api-reference/users/create-a-user swagger.json post /users Creates a new user within the specified team, associating the user with the team and enabling them to interact with its resources and systems. This endpoint can be used to add players, administrators, or other roles to a team, linking them with unique identifiers for tracking and management. # Delete a user Source: https://docs.forgegames.org/api-reference/users/delete-a-user swagger.json delete /users # List Users Source: https://docs.forgegames.org/api-reference/users/list-users swagger.json get /users Lists all users belonging to the specified team. Users can own item instances or interact with spaces. # Build Your Game's Inventory System Source: https://docs.forgegames.org/build-inventory-systems Learn how to set up a basic inventory system using Forge. You'll define items, create spaces to store them, and assign them to users. ### **Step 1: Define Items** Define the items in your game. Items can be as simple or complex as your game requires. #### **Optional: Add Classifiers** Classifiers categorize items for easier filtering and organization: * **Rarity** (e.g., "Common", "Rare", "Legendary") * **Type** (e.g., "Weapon", "Armor", "Consumable") Skip classifiers if your items don’t need categorization. #### **Optional: Add Attributes** Attributes define item properties or stats: * **Attack Power** (e.g., "+10") * **Health Restoration** (e.g., "Restore 50 HP") If your game doesn’t require detailed item properties, you can leave attributes out. *** ### **Step 2: Define Spaces** Spaces are areas where items are stored. Create spaces for player inventories, stashes, or other storage systems. **Examples:** * `Inventory`: A general storage space for all collected items. * `Stash`: A special storage space for rare or extra items. *** ### **Step 3: Create the Forge Client** Connect your game to Forge using your credentials. The client securely interacts with Forge’s API. ```ts theme={null} // Initialize the Forge client with your credentials const client = new Forge({ username: process.env['FORGE_CLIENT_ID'], // Your client ID password: process.env['FORGE_CLIENT_SECRET'], // Your client secret }); ``` *** ### **Step 4: Add a User** Players in your game are represented as users in Forge. When a player logs in or selects a character, create a user. ```ts theme={null} // Create a new user in Forge const user = await client.users.create(); ``` * **What does this do?**\ Creates a user profile in Forge, which can be linked to items and spaces. *** ### **Step 5: Create a Space for the User** Assign the user a storage space for their collected items, such as an inventory or stash. ```ts theme={null} // Create a user space for the player's stash const userSpace = await client.users.spaces.create(user.id, { spaceId: process.env['FORGE_STASH_SPACE_ID'], // ID of the defined space externalId: user.id, // Optional: Link to your game’s user ID }); ``` * **What does this do?**\ Creates a unique storage space for the user, enabling item collection and organization. *** ### **Step 6: Create an Item Instance** Add an item instance to the user’s space. For example, if a player defeats a monster and collects a legendary sword, you can add it to their stash. ```ts theme={null} // Add an item instance to the user's stash await client.itemInstances.create({ userSpaceId: userSpace.id, // The user's stash space itemId: <>, // The item the user collects }); ``` * **What does this do?**\ Creates a unique instance of the item (e.g., a specific sword) and places it in the user’s space. # Attributes Source: https://docs.forgegames.org/essentials/attributes Define and manage item properties and statistics ## Defining an Attribute Attributes are essential for defining the characteristics and statistics of items within your game. They enable customization and progression by allowing items to have unique properties that impact gameplay mechanics. Suppose you have a game where items can have varying levels of strength, speed, or durability. You might set up your attributes as follows: ### Health | Attribute Name | Min | Max | | -------------- | --- | --- | | `health` | 1 | 100 | ### Damage | Attribute Name | Min | Max | | -------------- | --- | --- | | `damage` | 10 | 50 | ### Speed | Attribute Name | Min | Max | | -------------- | --- | --- | | `speed` | 1 | 10 | Setting the `min` and `max` values for attributes ensures that randomized values remain within the defined boundaries. This is especially useful for rolling loot or defining item templates. With this configuration in place, attributes can dynamically affect gameplay. For example: * A weapon with higher `damage` might give players an advantage in combat. * An armor item with increased `health` can enhance survivability. * `Speed` can influence how fast a character moves or attacks. By defining attributes and using the [Item Instance API](/api-reference/item-instances), you can create a robust and flexible system for customizing gameplay elements. ## Advanced Usage Attributes can also be combined with other Forge features, such as random rolls or event triggers, to add complexity and depth to your game mechanics. For example: * Roll a weapon’s `damage` within a range of 20–40 to provide variability in loot drops. * Scale an attribute like `health` as a player progresses to higher levels. By leveraging attributes effectively, you can build a dynamic and engaging item system that adapts to your game’s design needs. # Classifiers Source: https://docs.forgegames.org/essentials/classifiers Group items based on characteristics and usage restrictions ## Defining a Classifier Classifiers are essential for organizing and managing various item types, characteristics, and traits within your game. They allow you to categorize items into specific groups, making it easier to implement game mechanics and restrictions. Suppose you have a game where players can find items of various types and rarities. You might set up your classifiers as follows: ### Type | Classifier Option | Roll Numerator | | ----------------- | -------------- | | `gear` | 1 | | `enhancements` | 1 | | `currency` | 1 | ### Rarity | Classifier Option | Roll Numerator | | ----------------- | -------------- | | `common` | 70 | | `rare` | 20 | | `epic` | 10 | The roll numerator allows you to specify weight to each classifier option. This allows you to give higher probabilities to different options within a classifier With this configuration in tact we now have the capability to filter, and affect outcomes of rolls via the [Roll API](/api-reference/roll). If you want the roll to return only gear items, you would filter your roll to include the `gear` option from the `type` classifier. This ensures that the only gear items with the specified rarity distribution will be returned. By defining classifiers and using the [Roll API](/api-reference/roll) effectively, you can create a more dynamic and rewarding item distribution system in your game. # Items Source: https://docs.forgegames.org/essentials/items Items are the core components in Forge that drive the dynamics of your game world. Each item can be defined with specific attributes, classifiers, and optional visual representations. This document explains how to define an item, the role of classifiers, and how items interact with the game's mechanics. ## 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](/essentials/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: ```json theme={null} { "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](/api-reference/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: ```json theme={null} POST /items { "itemId": "mystic_sword", "userId": "user123", "userSpaceId": "space456" } ``` **Response:** ```json theme={null} { "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](/api-reference/item-instances). # Spaces Source: https://docs.forgegames.org/essentials/spaces Spaces in Forge serve as structured storage areas where item instances are stored and managed within your game. Each space defines a specific area designated for organizing items based on their usage or category. This document outlines how spaces function as storage compartments and their role in facilitating item management. ## Defining Spaces Spaces are defined during the setup of a user's account, providing dedicated areas for storing item instances. Game designers can customize spaces to suit various game needs, such as character inventories, stash compartments, or mailboxes for item deliveries. ## Example of Defining Spaces When a user account is created, spaces can be configured with specific dimensions, typically represented by rows and columns. Here’s an example of defining spaces: ```json theme={null} POST /spaces { "userId": "user123", "spaces": [ { "name": "Character Inventory", "rows": 2, "columns": 5 }, { "name": "Stash", "rows": 3, "columns": 5 }, { "name": "Mailbox", "rows": 1, "columns": 5 } ] } ``` ## Using Spaces Once spaces are defined, item instances can be stored within them. Users can interact with their spaces through various operations, such as adding new items, moving items between spaces, or retrieving items from specific locations within a space. #### Example of Storing an Item Instance ```json theme={null} POST /item-instances { "itemId": "sword_of_power", "userId": "user123", "spaceId": "spaceCharacterInventory456", "position": { "row": 0, "column": 1 } } ``` ## Summary Spaces in Forge provide structured compartments for organizing and managing item instances within your game. By defining spaces with specific dimensions, game designers can tailor storage areas to fit different game mechanics and user interactions. For more details on how to interact with spaces and manage item instances, refer to the [API documentation](/api-docs/spaces) for each relevant API call. # Inventory Systems Source: https://docs.forgegames.org/guides/inventory-systems Organize and manage player items to enhance gameplay engagement and strategy ## Defining an Inventory System An inventory system is essential for organizing and managing the items that players collect during gameplay. It serves as a bridge between game mechanics and user interaction, allowing players to view, equip, or use items strategically. Suppose you have a game where players can collect gear, potions, and crafting materials. You might configure your inventory system as follows: ### Inventory Spaces | Slot Type | Grid Size | Description | | ------------- | --------- | ----------------------------------------------------------- | | `gear` | 5x2 | Slots dedicated to equippable items like armor and weapons. | | `consumables` | 5x4 | Slots for potions, food, and other usable items. | | `crafting` | 5x6 | Storage for materials used in crafting. | ### Item Classification | Category | Description | | ------------- | --------------------------------------------------------- | | `equipment` | Items that can be equipped to enhance stats or abilities. | | `consumables` | Items that provide temporary effects or boosts. | | `materials` | Items used for crafting or upgrades. | Defining inventory spaces and classifications allows for efficient organization and ensures that players can easily interact with their items. With this configuration in place, your inventory system can: * **Enhance Strategy**: Let players decide which items to keep, equip, or discard based on their gameplay goals. * **Limit Space**: Introduce constraints to encourage resource management and decision-making. * **Streamline User Experience**: Provide intuitive interfaces for item navigation and interaction. ## Advanced Usage ### Space Management Inventory systems often come with space limitations to add challenge and strategy. For example: * Allow players to expand their inventory by purchasing additional slots or upgrading their gear. * Categorize items to avoid clutter and improve usability. ### Interaction Features * **Equip**: Let players equip items directly from their inventory, applying effects to their characters or stats. * **Use**: Allow consumables like health potions to be used instantly. * **Trade**: Enable item trading between players or NPCs to encourage social and economic dynamics. ### Integration with Forge Features Forge’s inventory system works seamlessly with: * **Spaces**: Assign items to spaces for further categorization or gameplay mechanics. * **Item Instances**: Track individual occurrences of items, including attributes and modifiers. * **User Management**: Link inventories to specific players or user roles. ## Best Practices 1. **Keep it Intuitive**: Use clear categories and interfaces to make item management effortless for players. 2. **Introduce Progression**: Allow players to expand their inventory or unlock new features as they progress. 3. **Balance Constraints**: Set reasonable limitations to inventory space to maintain challenge without causing frustration. By implementing an inventory system effectively, you can enhance player engagement, encourage strategic decision-making, and create memorable gameplay experiences. # Access Control Source: https://docs.forgegames.org/integration/access-control Securely authenticate API requests and protect your team's data ## What is Access Control? Access Control in Forge ensures that only authorized applications can interact with your team's entities. This is achieved through **Basic Authentication**, where you use a secret key to authenticate your API requests. Proper implementation of access control is essential to protect your team's data and prevent unauthorized modifications. *** ## Creating Secrets for API Access To authenticate with Forge, you need to create a **secret key** and use it in your server-side application. Follow these steps to set up your secret: 1. **Navigate to the Secrets Page**: * Go to the API Keys page in Forge. * Generate a new secret for your team. This secret acts as the password for API requests. 2. **Store the Secret Securely**: * Save the generated secret in a secure environment variable, such as `process.env.FORGE_SECRET`. * Avoid storing secrets in your source code to prevent accidental exposure. 3. **Obtain Your Team ID**: * Your `teamId` (used as the username in authentication) is available in your team's settings. *** ## Implementing Access Control in Your Application ### Example Integration Use your `teamId` and secret in a server-side application to authenticate API requests: #### Environment Variables Store your credentials securely in environment variables: ```env theme={null} FORGE_TEAM_ID=your_team_id FORGE_SECRET=your_secret_key ``` #### Authentication Header Generate the `Authorization` header by combining the `teamId` and secret as `teamId:secret`, then base64 encode it. Example in Node.js: ```javascript theme={null} const teamId = process.env.FORGE_TEAM_ID; const secret = process.env.FORGE_SECRET; const authHeader = `Basic ${Buffer.from(`${teamId}:${secret}`).toString("base64")}`; // Example API request using Axios const axios = require("axios"); axios .get("https://api.forgegames.org/teams/team123/items", { headers: { Authorization: authHeader, }, }) .then((response) => { console.log(response.data); }) .catch((error) => { console.error(error); }); ``` *** ## Important Security Considerations 1. **Always Use Server-Side Applications**: * Secrets must never be exposed in client-side code (e.g., in a browser or mobile app). If exposed, anyone could use them to access your team's data and modify its entities. 2. **Restrict Access**: * Store secrets in a secure location, such as environment variables or a secret management system (e.g., AWS Secrets Manager, HashiCorp Vault). 3. **Rotate Secrets Regularly**: * Update your secrets periodically or when you suspect they may have been exposed. Use the [Secrets page](/secrets) to rotate keys. 4. **Use HTTPS**: * Always send API requests over HTTPS to encrypt the credentials during transmission. By keeping secrets secure and using them exclusively in server-side applications, you protect your team’s entities from unauthorized access or modification. *** ## Why Access Control Matters Implementing proper access control ensures that: * Your team’s data is secure from unauthorized access. * Only trusted server-side applications can make changes to your entities. * You maintain full control over who can interact with your game resources. # Item Instances Source: https://docs.forgegames.org/integration/item-instances Create and manage individual occurrences of items with unique properties ## What are Item Instances? Item Instances are unique occurrences of items that inherit their properties from item templates. They allow you to give each item specific attributes, modifiers, or states that distinguish it from others. For example: * A "Sword" template might define base damage and durability. * An instance of that sword can have rolled attributes, such as **damage: 45** and **durability: 90**, making it unique. ### Item Instance Properties | Property | Type | Description | | ------------ | ------ | ------------------------------------------------- | | `id` | String | The unique identifier for the item instance. | | `itemId` | String | The ID of the template the instance is based on. | | `attributes` | Object | Key-value pairs of attribute names and values. | | `createdAt` | String | The timestamp when the instance was created. | | `updatedAt` | String | The timestamp of the last update (if applicable). | Use item instances to track the unique properties and states of items owned by players. ## Example Configuration ### Template | Property | Value | | ------------ | ------------------------------- | | `itemId` | swordTemplate | | `attributes` | `{damage: 20, durability: 100}` | ### Instance | Property | Value | | ------------ | ------------------------------ | | `id` | swordInstance123 | | `attributes` | `{damage: 45, durability: 90}` | In this example, the instance has rolled higher damage and durability values than the template, creating a unique and powerful weapon. *** ## API Reference ### Create an Item Instance **Endpoint**:\ `POST /teams/{teamId}/item-instances` **Description**:\ Creates a new item instance based on a template and applies custom attributes or modifiers. **Request Body**: ```json theme={null} { "itemId": "swordTemplate", "attributes": { "damage": 45, "durability": 90 }, "userId": "player123" } ``` **Response**: ```json theme={null} { "id": "swordInstance123", "itemId": "swordTemplate", "attributes": { "damage": 45, "durability": 90 }, "createdAt": "2024-01-01T12:00:00Z" } ``` ### List Item Instances **Endpoint**:\ `GET /teams/{teamId}/item-instances` **Description**:\ Lists all item instances within a team, with optional filters for users, items, or attributes. **Response**: ```json theme={null} [ { "id": "swordInstance123", "itemId": "swordTemplate", "attributes": { "damage": 45, "durability": 90 }, "createdAt": "2024-01-01T12:00:00Z" } ] ``` By leveraging item instances, you can create unique, dynamic items that enhance gameplay and player engagement. *** ### Key Elements: 1. **Rolling**: * Explains probabilities and mechanics. * Ties classifiers and attributes together to show how they work in practice. * Includes an API reference for performing rolls. 2. **Item Instances**: * Focuses on creating and managing unique items. * Highlights the relationship between templates and instances. * Includes API references for creation and listing. Let me know if you'd like further refinements! ``` ``` # Rolling Source: https://docs.forgegames.org/integration/rolling Randomize item generation using roll numerators for scalable probabilities ## What is Rolling? Rolling is the process of generating randomized items or loot based on their defined properties. In Forge, rolling uses a **roll numerator** system, which ensures scalable and dynamic probabilities as you add or adjust items or classifications in your game. ### How Roll Numerators Work Each item or classifier option is assigned a **roll numerator**, representing its weight in the roll. The system calculates the **roll denominator** as the sum of all numerators for the available options. An item's or group's probability is calculated as: Probability = (Roll Numerator) / (Roll Denominator) This system ensures that probabilities scale dynamically when you add or modify items or classifier options, maintaining balance without recalibration. ## Classifier Options and Group-Level Control In addition to assigning numerators to individual items, you can also assign numerators to **classifier options**. This allows you to manage probabilities at a group level. For example, you can control how often items of a particular **rarity** drop without defining individual item probabilities. ### Example Configuration #### Classifier: Rarity | Classifier Option | Roll Numerator | Probability | | ----------------- | -------------- | ----------------- | | `Common` | 70 | 70 / 120 = 58.33% | | `Uncommon` | 30 | 30 / 120 = 25.00% | | `Rare` | 15 | 15 / 120 = 12.50% | | `Legendary` | 5 | 5 / 120 = 4.17% | **Roll Denominator**: ( 70 + 30 + 15 + 5 = 120 )\ This configuration controls how often items from each rarity classification are rolled. #### Combining Classifier Options and Items You can assign numerators to both classifier options and individual items for more granular control. **Example: Rarity with Items** | Rarity | Item | Roll Numerator | Probability | | ---------- | -------- | -------------- | ----------------- | | `Common` | `Sword` | 50 | 50 / 100 = 50.00% | | | `Shield` | 50 | 50 / 100 = 50.00% | | `Uncommon` | `Potion` | 30 | 30 / 30 = 100.00% | **Roll Denominator for Rarity**: ( 70 + 30 = 100 )\ **Roll Denominator for Common Items**: ( 50 + 50 = 100 ) If a Common rarity is rolled, there’s an equal 50% chance of getting a Sword or a Shield. Using classifier options and item-level numerators together allows you to define probabilities at both the group and item level, providing maximum flexibility for your loot system. *** ## Practical Applications * **Group-Level Control**: Use classifier options like **rarity** to control probabilities across a category of items. * **Granular Probabilities**: Assign numerators to individual items for precise control within a group. * **Dynamic Scaling**: Easily add new classifier options or items without recalibrating the entire loot system. *** ## Best Practices 1. **Combine Group and Item Control**: Use classifier options for high-level probability control and item numerators for fine-tuning within groups. 2. **Test for Balance**: Ensure your roll numerators reflect desired rarity distributions and are balanced for gameplay. 3. **Use Intuitive Values**: Keep numerators simple and consistent (e.g., 10, 50, 100) to make scaling straightforward. *** ## Example Use Case: Treasure Chest Drops Imagine a treasure chest with the following configuration: #### Classifier: Rarity | Classifier Option | Roll Numerator | Probability | | ----------------- | -------------- | ----------------- | | `Common` | 70 | 70 / 170 = 41.18% | | `Uncommon` | 50 | 50 / 170 = 29.41% | | `Rare` | 30 | 30 / 170 = 17.65% | | `Legendary` | 20 | 20 / 170 = 11.76% | #### Items within Rarities | Rarity | Item | Roll Numerator | Probability | | ----------- | ------------ | -------------- | ------------------- | | `Common` | `Gold Coins` | 50 | 50 / 100 = 50.00% | | | `Shield` | 50 | 50 / 100 = 50.00% | | `Legendary` | `Excalibur` | 100 | 100 / 100 = 100.00% | **Roll Denominator for Rarity**: ( 70 + 50 + 30 + 20 = 170 )\ **Roll Denominator for Common Items**: ( 50 + 50 = 100 ) This configuration ensures balanced probabilities for both rarities and items within each rarity. *** By using roll numerators for classifier options and items, Forge enables dynamic, scalable, and flexible probability systems that adapt to your game’s evolving needs. # User Management Source: https://docs.forgegames.org/integration/user-management Link your game's users with Forge for persistence and state management ## Defining User Management User Management in Forge provides a way to link the users in your game to Forge, enabling persistence and state management. This connection allows you to associate users with spaces and their item inventories, ensuring all data remains tied to the user. ### User Fields | Field | Description | | ------------ | ---------------------------------------------------------------------------- | | `id` | The unique identifier for the user. | | `externalId` | Optional. An identifier linking the user to an external system or your game. | | `createdAt` | The timestamp when the user was created. | | `updatedAt` | The timestamp when the user was last updated. | | `teamId` | The unique identifier of the team (game) the user belongs to. | *** ## Purpose of Managing Users * **User Linkage**: Create a persistent connection between your game's user and Forge. * **State Management**: Associate spaces and item inventories with the user for seamless gameplay data management. A user in Forge represents the same player in your game, ensuring their state and inventory are always synchronized. *** ## Example Use Case * **Inventory Management**: Store item inventories in spaces tied to the user for persistent access across sessions. *** By linking your users with Forge, you can ensure persistence, manage their state effectively, and provide a seamless experience for players. # Introduction Source: https://docs.forgegames.org/introduction Get started with Forge and learn how to build and integrate your game systems Hero Light Hero Dark ## Setting up Design the components of your game. Group items based on characteristics and usage restrictions. Add stats to your items, such as damage, health, or rarity. Items are the loot players will find in your game Define virtual boxes for items to live in. This is your inventory, stash, etc... ## Utilize your creations Bring your forge components into your game. Secure your API requests and manage your team’s secrets. Use rolling to dynamically determine drops and outcomes in your game. Manage individual items, track ownership, and move them between spaces. Create users and assign spaces to them