​
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

PropertyTypeDescription
idStringThe unique identifier for the item instance.
itemIdStringThe ID of the template the instance is based on.
attributesObjectKey-value pairs of attribute names and values.
createdAtStringThe timestamp when the instance was created.
updatedAtStringThe 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

PropertyValue
itemIdswordTemplate
attributes{damage: 20, durability: 100}

​
Instance

PropertyValue
idswordInstance123
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:

{
  "itemId": "swordTemplate",
  "attributes": {
    "damage": 45,
    "durability": 90
  },
  "userId": "player123"
}

Response:

{
  "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:

[
  {
    "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!

Access ControlRolling