add-item
Create D&D 5e physical items (weapons, armor, consumables, containers). Supply only the fields you need; defaults fill the rest. Target an actor or create reusable world items.
Instructions
[D&D 5e only] Create a structured physical item (loot/gear) on an actor or in the world Items sidebar. Pick itemType, then supply only the fields you need — sensible defaults fill the rest:
• weapon — to-hit weapon. damage (base die), weaponClass, attackType, reach/range, magicalBonus, properties. Builds a rollable attack activity by default (withAttack).
• armor / shield — armorValue, dex, strength; magicalBonus = +N AC. Pass wireAc (BODY ARMOR only) to make the actor derive AC from the worn armor; a shield needs no wireAc (its +2 applies under any AC calc).
• wondrous — rings/cloaks/etc. (equipmentType); use magical:true + attunement (a wondrous item has no numeric +N field — model a bonus with manage-effect).
• consumable — potion/scroll/ammo/wand. consumableType, uses {max, recovery, autoDestroy}. Ammo can carry damage + ammoReplace + magicalBonus.
• tool — toolType, ability, proficient, toolBonus.
• loot — gems/art/trade goods (lootType, price). NOT equippable/attunable.
• container — bag/chest with capacity and an inner currency pile. Place items inside any container with the container param (id or name).
Cross-cutting: price, weight, quantity, rarity, identified, equipped, attunement (""/required/optional) + attuned, magicalBonus (the +N), properties (incl. "mgc"). Setting magicalBonus/magical adds the mgc flag; the numeric +N is stored for weapons, body armor, and magic ammo (wondrous/potion have no +N field). Unlike add-feature, add-item does NOT reject a duplicate name — intentional, so you can author stacks/copies; de-dupe yourself if you need uniqueness.
Target: actorIdentifier embeds on that actor; omit it to create a reusable world Item (optionally in folder). This authors documents — it does NOT roll, equip-in-combat, or spend charges. For features/attacks-as-abilities use add-feature; for free-form system data use create-item / add-feature. To COPY a real item from a compendium (keeps art + stats), prefer import-item.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dex | No | [armor] Max Dex bonus to AC (omit = unlimited/light; 2 = medium; 0 = heavy). | |
| img | No | Icon path (e.g. "icons/weapons/swords/sword-runed.webp"). A path that does NOT resolve on the server is auto-replaced with a real icon (rule 8) and reported as a warning — omit img to auto-fill, or copy a verified path from a compendium item rather than guessing. | |
| name | Yes | Item name. | |
| uses | No | [consumable] Limited uses / charges. | |
| price | No | Item price. | |
| damage | No | [weapon] Base damage die. [consumable ammo] Added damage. | |
| folder | No | When creating a world Item (no actorIdentifier), place it in this folder (created if absent). | |
| rarity | No | Magic-item rarity ("" = mundane). | |
| weight | No | Item weight. | |
| wireAc | No | [body armor, actor target only] Also switch the actor to default (armor-derived) AC so worn armor changes AC. Ignored for shields (their +2 always applies) and for world items. | |
| ability | No | [tool] Default ability for the tool check. | |
| attuned | No | Whether this item is currently attuned by its owner. | |
| magical | No | Flag the item as magical (adds the "mgc" property). Implied when magicalBonus is set. | |
| rangeFt | No | [weapon, ranged] Normal range in feet. | |
| reachFt | No | [weapon, melee] Reach in feet. Default 5. | |
| subtype | No | [consumable/loot] Finer subtype (e.g. ammo "arrow"). | |
| baseItem | No | [weapon/armor/tool] Specific base-item key (e.g. "longsword", "plate", "smith"). | |
| capacity | No | [container] Carrying capacity. | |
| currency | No | [container] Coins stored inside the container. | |
| equipped | No | Whether worn/wielded (default true for an NPC). Set false for stowed loot. | |
| itemType | Yes | Kind of physical item. weapon; armor/shield/wondrous (all dnd5e "equipment"); consumable (potion/scroll/ammo/…); tool; loot (gems/trade goods/junk); container (bag/chest). | |
| lootCopy | No | [actor target] Also mint a matching WORLD Item (same stats + icon) so the party can loot this gear after the fight. DEFAULT ON for magic items (rarity set, "mgc", or a +N); pass false to suppress, or true to force a loot copy of a mundane item too. Ignored for a world-item target. | |
| lootType | No | [loot] Loot category. Default "gear". | |
| quantity | No | Stack count (e.g. 20 arrows). Default 1. | |
| strength | No | [armor] Min Strength to wear without a speed penalty. | |
| toolType | No | [tool] Category key (art/game/music/…). | |
| armorType | No | [armor] Armor weight class. Default "medium". | |
| container | No | Id or name of an EXISTING container item on the same target to place this item inside. | |
| toolBonus | No | [tool] Flat bonus formula added to the check. | |
| versatile | No | [weapon] Two-handed (versatile) damage (needs the "ver" property). | |
| armorValue | No | [armor] Base AC (shield = AC bonus, default 2). | |
| attackType | No | [weapon] Attack kind. Default "melee". | |
| attunement | No | Attunement requirement: "" none, required, or optional. | |
| identified | No | Whether the item is identified (default true). Set false for mystery loot. | |
| proficient | No | [weapon/armor/tool] Proficiency (weapon/armor 0|1; tool 0|0.5|1|2). Omit to infer. | |
| properties | No | Property codes Set (e.g. ["fin","lgt"]). Weapon codes: ada,amm,fin,fir,foc,hvy,lgt,lod,mgc,rch,rel,ret,sil,spc,thr,two,ver. "mgc" marks magical. | |
| withAttack | No | [weapon] Attach a rollable attack activity built from damage + attackType (default: true when damage is given). Set false for a weapon that is pure loot with no attack. | |
| ammoReplace | No | [consumable ammo] If true, ammo damage replaces the weapon base instead of adding. | |
| attackBonus | No | [weapon] Flat bonus to the attack roll only (separate from magicalBonus). | |
| description | No | HTML description. | |
| longRangeFt | No | [weapon, ranged] Long (disadvantage) range. | |
| sourceRules | No | [weapon] Rules edition for the attack activity. Default "2024" (pass "2014" for legacy). | 2024 |
| weaponClass | No | [weapon] Category. "natural" for monster attacks. Default "natural". | |
| magicalBonus | No | Numeric +N magic bonus (to attack & damage for weapons, to AC for armor). | |
| equipmentType | No | [wondrous] Equipment subtype (clothing/trinket/ring/rod/wand/…). Default "trinket". | |
| consumableType | No | [consumable] Category. Default "potion". | |
| lootCopyFolder | No | Folder for the loot copy (created if absent). Default "Loot". | |
| abilityModifier | No | [weapon, 2024] Attack/damage ability override. | |
| actorIdentifier | No | Target actor (name or id) to attach the item to (partial match). Omit to create a reusable world Item in the Items sidebar instead. |