Items

Schema

{
  "items": {
    "<key>": {
      "name": "string",
      "category": "string",
      "description": "string",
      "bonuses": [
        {
          "type": "resource | stat | attribute | skill",
          "variable": "string",
          "value": "number"
        }
      ],
      "slot": "string",
      "mediaContent": "string"
    }
  }
}

Example

Equippable item (weapon — has slot and bonuses):

{
  "Iron Longsword": {
    "name": "Iron Longsword",
    "category": "Weapon",
    "description": "A well-balanced military sword of standard construction. Reliable and unadorned.",
    "bonuses": [
      { "type": "stat",  "variable": "damage",    "value": 3 },
      { "type": "skill", "variable": "athletics", "value": 5 }
    ],
    "slot": "Weapon"
  }
}

Readable item (book — has mediaContent, no slot or bonuses):

{
  "Petitioner's Ledger": {
    "name": "Petitioner's Ledger",
    "category": "Readable",
    "description": "A clothbound journal showing wear at the spine and corners. The ink on the visible pages has faded unevenly, as if the book has been opened to the same passages many times.",
    "bonuses": [],
    "mediaContent": "Entry, third week of the rains. Two more petitions today, both refused at the gate before they reached the council. The clerks now sort them by district before forwarding -- meaning Lower District grievances never leave the antechamber. I have begun keeping copies. If anyone asks, I am compiling a clerical reference."
  }
}

Fields

Bonus types

📋

Note: "armor" and "damage" are the only valid stat values.

📋

Note: Custom stats (dodge, crit rate, block, initiative, etc.) have no native schema field. If you want a dodge or parry mechanic, document the rule in the item’s description and reinforce it in aiInstructions.generateActionInfo. The narrator will honor it in play. The difference from native stat bonuses is that no engine math backs it - the narrator is making all the judgment calls.

⚠️

Warning: bonus.variable values are cross-checked against the relevant collection. An attribute bonus with "variable": "strenght" (typo) will fail validation.

category

Must match a value in itemSettings.itemCategories.

slot

Optional. Must match a slot in itemSettings.itemSlots when present. For most items, slot and category match. Exception: armor uses category: "Armor" with a body-region slot. The conventional 7-slot armor vocabulary is "head", "chest", "shoulders", "hands", "waist", "legs", "feet" (lowercase). Not engine-enforced — slot strings remain world-defined — but it is the layout authoring tooling assumes and the inventory UI groups cleanly when used consistently.

mediaContent

Conditional string. Required for Readable items (books, letters, scrolls). Contains the full text the player sees when they read or inspect the item. Leave absent for all other item categories. Item names on Readable items must be precise so the engine can match them at read time.

Item stacking

Currency items (whose name matches itemSettings.currencyName) stack by name and category only - the engine ignores bonus values when merging currency stacks. Non-currency items must match all properties (name, category, bonuses, effects) to stack. Two swords with different bonus values are separate inventory entries even if both are named “Iron Sword.” Items do not need to be equipped to be used, but only equipped items grant mechanical bonuses.

Key/name match

Item outer keys must be the exact display name string, identical to the inner name field. "Iron Longsword" not "iron_longsword". Using snake_case or slug keys causes “Key/name mismatch” errors for every affected item. When building items programmatically, always use {item["name"]: item} to key the dict — never generate slugs. A mismatch does not break JSON validity but causes the editor to reject the import.

All outer keys in every keyed map must exactly equal the inner name display string. This applies to items, npcs, quests, traits, traitCategories, factions, locations, regions, and npcTypes.

Size limit

The entire items section (pretty-printed with indent=2) must be under 100,000 characters. Stay within budget by:

• Keeping description fields under 150 characters for common items; unique or special items can run 250-350 characters
• Measure before import: len(json.dumps(d["items"], indent=2)) must be < 100,000

Authoring tips

Description prose

The description is what the AI uses when the item appears in play — it should read like a narrator would say it, not like a tooltip. “A well-balanced military sword, standard issue for the city guard” gives the AI setting context and narrative flavor. “Deals 1d8 piercing damage” does nothing useful because the AI already knows how swords work. Keep descriptions short and evocative; the mechanics live in bonuses.

Items that aren’t in startingItems anywhere still exist and can appear organically in AI narration. The difference is you can’t guarantee players will find them. Pre-defining items matters most for starting gear and any item with specific mechanical bonuses you need to be precise about.

Equippable item rules

Equippable items must have a slot field. Non-equippable items (consumables, currency, miscellaneous) omit it.

Skill and attribute bonuses on equippable items are common — cloaks, boots, and gloves granting +1 to stealth or perception are standard practice. Not all equippable items need to use the armor stat type.

Armor formula and tier values

Common armor values by tier: light (leather, cloth) 5-15, medium (chain, scale) 20-50, heavy (full plate) 60-100+. The formula reduces incoming damage by armor / 1000 per point — a value of 100 means 10% reduction. Values above 900 are wasted.

Level-difference damage reduction

When attacker and defender are at different level values, the engine grants additional damage reduction to the higher-level side on top of armor. The per-level step diminishes (5% at +1, 4.5% at +2, …, 0.5% at +10) and is clamped at +11; cumulative cap is 27.5% at a 10-level gap.

Practical consequence: a high-level NPC shrugs off attacks from lower-level players (and vice versa) by up to 27.5%, but the bonus stops growing once the gap reaches 10 levels — so a level-30 NPC takes the same level-based reduction from a level-20 attacker as from a level-1 attacker.

Hidden damage variance

On top of armor and level-difference reduction, the engine applies a hidden variance step to each hit — not a literal dice roll, but functionally the same — that can shave off up to 40 from the incoming damage. The result is that two otherwise-identical hits can land for noticeably different amounts of damage even when no other modifiers change. Plan damage values with this swing in mind; a weapon that needs to one-shot something at full bonus probably won’t reliably do so once the variance subtracts from it.

Damage values

+1-3 for common weapons, +5-10 for named/enchanted weapons, +15-25 for legendary items. These are flat bonuses to damage output percentage (each point = +10%).

Starting items

• Give each character-creation trait (whatever your world calls them — Race, Class, Background, Profession, Origin, Faction, etc.) its own startingItems. Players should feel their choices materialize in inventory immediately.
• Match the items to the trait’s identity. In a D&D-style fantasy world that might mean a sword and shield for a fighter, a spellbook for a wizard, lockpicks for a rogue. In a modern scenario it might be a smartphone and press pass for a journalist, a toolbox for a mechanic, a sidearm and badge for a cop. The pattern is “items signal role at first sight” — the genre vocabulary is whatever fits your world.
• Avoid giving the same item across multiple traits — redundant items waste inventory space.