Items

Equippable item (weapon — has slot and bonuses):

A readable item (a book, letter, or scroll) can carry mediaContent, and has 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."
  }
}

#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. No engine math backs it: the AI makes every judgment call.

⚠️

Warning: bonus.variable values are cross-checked against the relevant collection. The validator flags an attribute bonus with "variable": "strenght" (typo).

#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 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.

#Keys and name

The outer key is the entry's id, and the engine resolves references by key. It must be identical to the inner name, character for character, and Voyage rejects a world where the two differ. Among the keyed sections that carry a name, quests is the exception: its key is free.

#Items in triggers

Triggers count, give and take item types: player-item compares how many of an item type is held, and item-add and item-remove give and take one. All three name the item type by its key, never its name; see the trigger reference for a shop purchase.

#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.

Pre-defining items matters most for starting gear and any item with specific mechanical bonuses you need to be precise about; items the AI creates in play get bonuses it judges fit the situation.

#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

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 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.

#Impact

Every attack carries an impact value (100 = normal) that the AI assigns per attack from how the action is described, following the impact guidance in generateActionInfo (a 50-200 scale by default); the attack's damage is multiplied by impact / 100. It applies to both player and NPC attacks, so a vividly described heavy blow lands harder than a glancing one.

#Evasion (defend action)

A character that takes a defend / evade action on a turn reduces the incoming damage of attacks against them that turn. The reduction scales with how well the defend roll succeeds; a reduction of 1.0 or higher fully nullifies the hit (it lands but deals 0). This is an active, per-turn choice driven by the defend roll, not a passive stat — and a successful player defend also degrades the attacking NPC's success roll, which is otherwise a fixed random draw of basic success or better.

#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.