Reference

Custom Inventory Guide

The full JSON format for replacing the default item catalog with your own homebrew system — items, loot tables, and everything the importer checks along the way.

File Structure

Your JSON file is a top-level array with two required indexes and one optional index, always in this order.

Index 0	Required	Array of inventory items
Index 1	Required	Array containing a single loot table object
Index 2	Optional	String with system notes or usage guidelines

JSON — top-level structure

[
  [ /* Index 0: Inventory Items     */ ],
  [ /* Index 1: Loot Tables         */ ],
  "/* Index 2: Instructions (opt) */"
]

Index 0 — Inventory Items

An array of every item available in your system. Each item is a JSON object with the fields below.

Required Fields

Field	Type	Description
id	Number	Unique identifier. ID 0 is reserved for your main currency item.
name	String	Item name. Must exactly match any loot table entry that references this item (case-sensitive).
quantity	Number	Starting amount. Use `0` for all items in template files.
cost	Object	Item value. Must be an object with a `quantity` property — not a plain number.
equipment_category	Object	Category for organization. Must be an object with a `name` property — not a plain string.

Important: cost and equipment_category must be objects, not plain values. The importer will attempt to normalize plain strings and numbers, but the correct format avoids unexpected results.

Recommended Fields

Field	Type	Description
desc	String	Item description shown in detail views. Not required by the validator but strongly recommended.
weight	Number	Item weight in your system's units.
rarity	Object	Rarity level. Must be an object with a `name` property — see valid values below.
recipe	Array	Crafting requirements listed as item names. Empty array if the item isn't craftable.

Rarity Values

Rarity must be an object with a name property, and the value must be capitalized exactly as shown. A plain string, or the wrong capitalization, is silently ignored by rarity-based filters in Shop Manager.

Correct format	Won't filter
{ "name": "Common" }	`"common"`
{ "name": "Uncommon" }	`"uncommon"`
{ "name": "Rare" }	`"rare"`
{ "name": "Very Rare" }	`"very rare"`
{ "name": "Legendary" }	`"legendary"`

Example Item

JSON — inventory item

{
  "id": 0,
  "name": "Gold (c)",
  "desc": "Standard gold coins used throughout the realm",
  "quantity": 0,
  "weight": 1,
  "cost": { "quantity": 1 },
  "equipment_category": { "name": "Currency" },
  "rarity": { "name": "Common" },
  "recipe": []
}

Index 1 — Loot Tables

An array containing a single object whose keys are category names. Each category holds one or more named tables. Each table's data object maps roll results (keys "1"–"100") to outcomes.

JSON — loot table structure

[
  {
    "CategoryName": {
      "category": "Human-readable description",
      "tables": [
        {
          "name": "Table Name",
          "data": {
            "1":   "Result for roll 1",
            "2":   "Result for roll 2",
            /* ... entries for every integer 1-100 */
            "100": "Result for roll 100"
          }
        }
      ]
    }
  }
]

Roll Coverage

The loot generator rolls a number from 1-100 and does a direct key lookup in data. A missing key produces a blank result with no error. Every integer from "1" to "100" must be present. Use repeated entries to control probability weighting:

JSON — weighted entries (Iron Sword 75%, Rare Chain 25%)

"data": {
  "1":   "Iron Sword",   /* rolls 1-75 all map to Iron Sword */
  "75":  "Iron Sword",
  "76":  "[chain] [Weapon:Rare Drops]", /* 76-100 chain to another table */
  "100": "[chain] [Weapon:Rare Drops]"
}

Table Type 1 — Item Tables

Reference an exact item name from your inventory. Capitalization and spacing must match.

JSON — item table entries

"data": {
  "1":   "Iron Sword",
  "50":  "Steel Dagger",
  "75":  "Leather Armor",
  "100": "Chain Mail"
}

Table Type 2 — Currency Tables

Use [coin] followed by a space and dice notation. The result is linked to your ID 0 currency item.

JSON — currency table entries

"data": {
  "1":   "[coin] 1d6 x 10",
  "50":  "[coin] 2d6 x 25",
  "100": "[coin] 3d6 x 50"
}

Dice notation format: [coin] XdY x Z — X number of dice, dY die type, x Z the multiplier.

Important: the x Z multiplier is required. [coin] 2d6 without a multiplier produces NaN — the parser always expects the full three-part format.

Table Type 3 — Chain References

Roll on a different table from within a result. Use the [chain] prefix followed by the target in [CategoryName:TableName] format — both parts must exactly match what's defined in your loot table object.

JSON — chain reference entries

"data": {
  "1":   "[chain] [Equipment:Basic Weapons]",
  "50":  "[chain] [Magic Items:Table A]",
  "100": "[chain] [Coins:Level 1]"
}

Important: a bare [TableName] without the [chain] prefix is not recognized as a reference — it's pushed to the generated list as a literal item named [TableName]. The full format [chain] [CategoryName:TableName] is required.

Index 2 — Instructions (optional)

A plain string at index 2 for any system-specific notes — currency conversion rates, level recommendations, custom rule clarifications, or version notes. Omitting this index entirely is fine.

JSON — instructions string

"Fantasy RPG System v1.0. Use Level 1 coin tables for characters level 1-3. All weights are in pounds."

Shop Manager & Naming

The Shop Manager screen (Manage Shop button) builds its toggle list entirely from the equipment_category.name and rarity.name values found across your inventory. There are no hardcoded categories — everything comes from your data.

A category named "weapons" and one named "Weapon" will appear as two separate toggles
Rarity toggles only appear for items with a correctly structured rarity object — a plain string produces no toggle
Shop type filtering uses exact string matching throughout

Note: use identical equipment_category.name and rarity.name values across every item. Inconsistent capitalization or spacing creates duplicate or orphaned toggles in Shop Manager.

Complete File Example

JSON — complete custom inventory file

[
  /* Index 0: Items */
  [
    {
      "id": 0, "name": "Gold (c)", "desc": "Standard gold currency",
      "quantity": 0, "weight": 1, "cost": { "quantity": 1 },
      "equipment_category": { "name": "Currency" }, "rarity": { "name": "Common" }, "recipe": []
    },
    {
      "id": 1, "name": "Iron Sword", "desc": "A basic iron sword",
      "quantity": 0, "weight": 3, "cost": { "quantity": 10 },
      "equipment_category": { "name": "Weapon" }, "rarity": { "name": "Common" }, "recipe": []
    },
    {
      "id": 2, "name": "Enchanted Blade", "desc": "A magically enhanced sword",
      "quantity": 0, "weight": 3, "cost": { "quantity": 500 },
      "equipment_category": { "name": "Weapon" }, "rarity": { "name": "Rare" }, "recipe": []
    }
  ],

  /* Index 1: Loot Tables */
  [
    {
      "Coins": {
        "category": "Currency",
        "tables": [
          { "name": "Level 1", "data": {
            "1": "[coin] 1d6 x 10", /* rolls 1-49 */
            "50": "[coin] 2d6 x 25", /* rolls 50-89 */
            "90": "[coin] 3d6 x 50", /* rolls 90-100 */
            "100": "[coin] 3d6 x 50"
          } }
        ]
      },
      "Weapon": {
        "category": "Weapons",
        "tables": [
          { "name": "Standard Drops", "data": {
            "1": "Iron Sword", /* rolls 1-74 */
            "75": "[chain] [Weapon:Rare Drops]", /* rolls 75-100 */
            "100": "[chain] [Weapon:Rare Drops]"
          } },
          { "name": "Rare Drops", "data": {
            "1": "Enchanted Blade",
            "100": "Enchanted Blade"
          } }
        ]
      }
    }
  ],

  /* Index 2: Instructions (optional) */
  "Fantasy RPG System v1.0. Use Level 1 coin tables for characters level 1-3. Weights are in pounds."
]

Validation

When you upload a file, the importer runs the checks below. Skipped items are counted in the post-import summary alert.

Errors — item skipped or file rejected

Invalid JSON syntax — entire file rejected
Incorrect top-level structure — must be an array
Item missing id, name, or equipment_category

Automatic normalizations

equipment_category as a plain string → converted to { "name": "..." }
cost as a plain number → converted to { "quantity": ... }

Not currently checked — verify manually: duplicate item IDs, a missing currency item at ID 0, invalid dice notation in coin entries, item names in tables that don't exist in inventory, and gaps in roll key coverage (1-100).

Best Practices

Validate your JSON with an online linter before importing
Cover all 100 roll keys in every table — use repeated entries to control probability weighting
Keep equipment_category.name and rarity.name consistent across every item
Always include a currency item at ID 0
Test chain references end-to-end by generating loot in the app and checking results
Document currency conversion rates and custom rules in the Index 2 string

Common Mistakes

Mistake	Consequence
`rarity` as a plain string	Rarity filters silently ignored; item never appears under rarity toggles in Shop Manager
Table reference as `[TableName]` without `[chain]`	Pushed as a literal item named `[TableName]` — no chain roll occurs
Missing `x Z` multiplier in coin notation	Currency result is `NaN`
Gaps in roll keys 1-100	Missing rolls produce blank results with no error message
Inconsistent category capitalization	Duplicate or missing toggles in Shop Manager
No currency item at ID 0	Coin table results generate a blank item
Item name in table doesn't match inventory exactly	Item not found — not added to generated loot

Building a custom set and stuck on something not covered here?