Inventory #

Players can obtain weapons and utility items via an Inventory system in Squad Alpha by Say Games.
Players can obtain weapons and utility items via an Inventory system in Squad Alpha by Say Games.

The Inventory meta-system in Hiro enables players to collect, upgrade, and consume items in your game. These in-game items can be anything from a piece of equipment like a sword or chestplate, to a cosmetic item like a flag or costume, to a power up like a spawner or boost.

Inventory items can be purchased from the virtual store, or earned through gameplay.

Customization parameters #

The following JSON represents the customization parameters you can use to configure the default user experience for the inventory system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

{
  "items": {
    "iron_sword": {
      "name": "Iron Sword",
      "description": "A sharp sword made of iron.",
      "category": "weapons",
      "item_sets": ["common_weapons"],
      "max_count": 99,
      "stackable": false,
      "consumable": false,
      "string_properties": {
        "equipment_slot": "right_hand"
      },
      "numeric_properties": {
        "rank": 1
      }
    },
    "health_potion": {
      "name": "Health Potion",
      "description": "A vial of red liquid used for healing.",
      "category": "potions",
      "max_count": 99,
      "stackable": true,
      "consumable": true,
      "consume_reward": {
        "guaranteed": {
          "energies": {
            "health": {
              "min": 100
            }
          }
        }
      }
    },
    "small_crafting_bag": {
      "name": "Small Crafting Bag",
      "description": "A small bag of miscellaneous crafting materials.",
      "category": "loot_bags",
      "max_count": 99,
      "stackable": false,
      "consumable": true,
      "consume_reward": {
        "max_rolls": 2,
        "weighted": [
          {
            "items": {
              "leather_scraps": {
                "min": 1,
                "max": 5
              }
            },
            "weight": 50
          },
          {
            "items": {
              "bronze_nails": {
                "min": 5,
                "max": 100,
                "multiple": 5
              }
            },
            "weight": 50
          }
        ]
      }
    }
  }
}

The JSON schema defines several objects which define the various items and item sets that will be available in your game. You can configure as few or as many of each as needed for your desired gameplay.

items #

The items object is structured as follows:

PropertyDescription
nameThe name for this item.
descriptionThe description for this item.
categoryThe category for this item.
item_setsAn array of string values that indicate which item sets this item belongs to.
max_countThe maximum number of this item a user can own.
stackableA bool value indicating whether this item can stack.
consumableA bool value indicating whether this item can be consumed.
consume_rewardA reward object that defines what rewards a user can or will receive for consuming the item.
string_propertiesA map of string values that define item specific metadata.
numeric_propertiesA map of number values that define item specific metadata.

Item definitions #

Item categories #

Every item definition has a category property. This is a simple string property that defines which broad collection the item belongs to and is useful for listing items. For example, you may wish to separate your items into categories such as weapons, armor, and potions.

Item sets #

Item definitions can optionally define an array of item_sets that they belong to. Item sets differ from categories in that an item can belong to multiple sets at once. These item sets can be used as tags for the items in your game such as rare and sword.

Item sets are used in the reward system to allow users to be rewarded with a random item that belongs to specific sets (see example below).

Item rewards #

A powerful feature of the Inventory system is the ability for game designers to add consume rewards to item definitions. When a user consumes the item, they will be granted the reward accordingly. Due to the power and flexibility of the Hiro reward system, this allows game designers the opportunity to create all manner of consumables.

Consider the following scenarios and associated item definitions:

A potion that restores 50 health

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "health_potion": {
    "name": "Health Potion",
    "description": "A vial of red liquid used for healing.",
    "category": "potions",
    "max_count": 99,
    "stackable": true,
    "consumable": true,
    "consume_reward": {
      "guaranteed": {
        "energies": {
          "health": {
            "min": 100
          }
        }
      }
    }
  }
}

A coin pouch that rewards between 100 and 500 gold coins in multiples of 10

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "coin_pouch": {
    "name": "Coin Pouch",
    "description": "A small pouch of gold coins.",
    "category": "bags",
    "max_count": 99,
    "stackable": true,
    "consumable": true,
    "consume_reward": {
      "guaranteed": {
        "currencies": {
          "coins": {
            "min": 100,
            "max": 500,
            "multiple": 10
          }
        }
      }
    }
  }
}

A loot chest that rewards a sword and a random rare weapon

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "loot_chest": {
    "name": "Loot Chest",
    "description": "A shiny chest full of treasure.",
    "category": "chests",
    "max_count": 99,
    "stackable": false,
    "consumable": true,
    "consume_reward": {
      "guaranteed": {
        "items": {
          "bronze_sword": {
            "min": 1
          }
        },
        "item_sets": [
          {
            "set": ["rare", "weapon"],
            "min": 1
          }
        ]
      }
    }
  }
}

A loot chest that rewards a weighted random currency

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "currency_chest": {
    "name": "Currency Chest",
    "description": "A shiny chest full of unknown currency.",
    "category": "chests",
    "max_count": 99,
    "stackable": false,
    "consumable": true,
    "consume_reward": {
      "max_rolls": 1,
      "weighted": [
        {
          "currencies": {
            "coins": {
              "min": 100
            }
          },
          "weight": 80
        },
        {
          "currencies": {
            "gems": {
              "min": 10,
              "max": 20,
              "multiple": 5
            }
          },
          "weight": 20
        }
      ]
    }
  }
}

Item instances #

When a user is granted an item, whether from a Store Purchase, as a Reward, or any other means, it is stored as an item instance inside their inventory. The inventory itself is stored inside the Storage Engine under a special collection/key for that user.

A user’s inventory has the following JSON schema.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "2cb9c733-a2c8-498f-aaed-8ba24a989c45": {
    "item_id": "iron_sword",
    "owned_time": 1674300933,
    "update_time": 1687347732,
    "count": 1,
    "string_properties": {
      "equipment_slot": "right_hand",
      "gem_slot_1": "strength_ruby",
      "gem_slot_2": "dexterity_emerald"
    },
    "numeric_properties": {
      "rank": 3,
      "monsters_defeated": 435
    }
  },
  "e264eaa7-6bc0-4a78-99ed-18fdadf3afea": {
    "item_id": "potion",
    "owned_time": 1654334562,
    "update_time": 1654338987,
    "count": 12,
    "string_properties": {},
    "numeric_properties": {}
  }
}

The inventory is a map of item instance IDs and the associated item instance data, where each item instance has the following structure.

PropertyDescription
item_idThe ID of the item definition this is an instance of.
owned_timeThe time that this item was acquired.
update_timeThe time that this item was last updated.
countHow many of this item the user currently has.
string_propertiesA map of string values that define item instance specific metadata.
numeric_propertiesA map of number values that define item instance specific metadata.

Item properties #

Item instances have their own metadata, stored within the string_properties and numeric_properties fields. This allows you to build systems where a user can customize, rank up, or modify the items they own. For example, you may have a weapon rank system that allows your players to “level up” their weapons, or a “gem slot” system that allows players to improve the stats of their items by socketing various gems to them, or perhaps you just want to keep track of how many monsters a user has defeated with a particular weapon as shown in the example above.

Default properties
Item definitions can define string_properties and numeric_properties which will be copied across to an item instance when it is retrieved. The values specified in the item definition will always override the value in the item instance. This allows you to update things like stats or XP curves for an item globally across all existing item instances.

Item stacking #

Where an item is granted that is defined as stackable, the inventory system will first check to see if the user currently has an item instance for that item ID. If they do, the count property of that particular instance will be increased accordingly. If they don’t, or if the item is not stackable, a new item instance will be generated instead and added to the user’s inventory.