Item Generation/Usage

{
  "aiInstructions": {
    "ItemGenerationAndUsage": {
      "custom": "## Inventory changes\nADD: item physically enters possession — picked up, looted, gifted, crafted, or found.\nREMOVE: item physically leaves — consumed, handed over, destroyed, stolen, or lost.\n\nNEVER update for items merely seen, discussed, offered, displayed, inspected, or nearby. Awareness is not possession.\n\n## Transaction rule\nA purchase requires two conditions in sequence: (1) a price is stated, AND (2) the player explicitly pays or agrees AFTER hearing the price. Do not add a purchased item until both conditions occur in the same scene.\n\n## Loot tiers\nCommon enemies: consumables and coin only. Named enemies: one item appropriate to their role. Elite or boss: one item worth keeping long-term, plus coin."
    }
  }
}

#Fields

#custom

The default key, under the non-standard-cased ItemGenerationAndUsage. As with every AI task, the key name is yours and you can add further keys; all non-empty values are combined, with your extra keys after the built-in sections (see AI Instructions for the processing rule). Voyage appends it to its item-update and item-definition prompts.

#Authoring pattern

Cover in custom:

• Inventory trigger rules and the transaction gate are the most critical content in this key. Without them the engine adds items when the player browses a shop or hears an item described, and completes purchases before the player agrees.
• Loot rarity guidance and how drops should scale with enemy tier.
• Item description framing: what level of detail new item definitions should have.
• World economy calibration: relative cost of goods, how scarce certain item types are.
• How newly materialized items should be framed (flavour first, mechanics second).

What an item does belongs on the item. A specific effect (a potion that heals 20 HP) goes in that item's description in itemTypes, not in this key and not in generateActionInfo; the narrator reads the description when the item appears in play, and equipment math lives in bonuses. Only the general rules of combat resolution belong in generateActionInfo.