5e Item Importer

Stop manually typing items.

For GMs who want D&D 5e items imported from text instead of typed by hand.

Features · Quick Start · Preview · Installation · Compatibility · Templates · Common Issues · Community · Contributing · AI Use · Support · License

Overview

5e Item Importer turns item text into Foundry Items. Paste a normal stat block for a quick import, or use one of the strict YAML templates when you want exact control.

Quick Start

Install and enable 5e Item Importer in your world.
Open the Items Directory in Foundry.
Click Import Item.
Paste the item text and click Parse.
Review the result, choose a destination, and click Import.

Preview

See it in Action on YouTube

What You Get

Natural Language Parser

Paste a familiar D&D 5e item stat block from a PDF, website, or your own notes. The importer looks for the Item type, price, weight, damage, properties, and description, then shows you the result before anything is created.

Strict Format Parser

Use the supplied YAML templates when you want predictable fields and clearer validation. This is the better choice for complicated homebrew, repeatable formats, and imports you expect to revise later. Best when paired with Large Language AI models like chatGPT, Gemini, or Claude.

Batch Imports

Strict Format can import a mixed collection in one block. For several Items of the same type, separate YAML documents with ---. Supported top-level keys are SPELL, WEAPON, EQUIPMENT, CONSUMABLE, TOOL, LOOT, and CONTAINER.

Lightweight Key/Value Drafts

View a lightweight draft example and supported fields

For a quick single-Item draft, the same seven Item types can also be written as a flat key/value list. At minimum, provide name and type; the router supplies conservative valid defaults and then validates the generated document through the strict parser.

name: Quick Spark
type: spell
level: 2
school: evocation
activation: bonus action
components: V, S
range: 60 feet
duration: 1 minute
description: A brief arc of blue-white light.

Type-specific lightweight fields include weaponType/baseWeapon, equipmentType/baseEquipment/armorClass, consumableType/ammunitionType/poisonType, toolType/baseTool, lootType, container capacity fields, and spell level/school/activation/component/range/duration fields.

Readable aliases such as armor/armour, potion, scroll, martial melee, thieves tools, trade goods, and full spell-school names are accepted. Mismatched fields, conflicting representations, malformed values, and unknown properties are reported instead of being silently replaced. Use the full strict templates when you need advanced configuration.

Natural Language Parser

Best for: Quick imports from books, PDFs, or websites.

This feature is still under active development

The module attempts to read standard D&D 5e statblock formatting. It automatically detects item types, costs, weights, and damage formulas.

How to use:

Copy the item text from your source.
Open the Items Directory in Foundry.
Click Import Item.
Paste the text and click Import.
Parse and then Import. You can choose a file to put it into.

📄 View Natural Language Template & Examples

Best Practice Patterns

For best results, try to match the standard D&D 5e Statblock format:

[Item Name]
[Type], [Rarity] (requires attunement [by Class/Race])
Cost: [Value] [gp/sp/cp], Weight: [Value] [lb]
Damage: [Formula] [Type]
Properties: [Prop1], [Prop2], [Versatile (1d10)]
AC: [Number] (max Dex [Number])

[Description Paragraphs...]

BEST PRACTICE PATTERNS

Based on parser logic in naturalItemParser.js

1. Naming & Header

The parser uses 3 strategies. The safest is Title Case on the first line.

Good: Flame Tongue
Better: Name: Flame Tongue (Guarantees 100% confidence)

2. Type Detection

Include specific keywords in the first 3 lines to trigger type detection:

Weapon: "Weapon", "Melee Weapon", "Ranged Weapon", "Attack Roll"
Armor: "Armor", "Shield", "Plate", "Leather", "AC"
Consumable: "Potion", "Scroll", "Wand", "Rod", "Food", "Drink", "Poison", "Ammunition", "Trinket"
Tool: "Tool", "Kit", "Instrument", "Gaming Set"
Container: "Bag", "Backpack", "Box", "Holds", "Capacity"
Loot: "Gem", "Art Object", "Treasure", "Material"

3. Weapons

To ensure correct parsing of damage and properties:

Type: Use full terms like "Martial Melee Weapon" or "Simple Ranged Weapon".
Damage: Format as 1d8 slashing or Damage: 2d6 fire.
Properties: Use an explicit label, such as Properties: Finesse, Light, Thrown.
Versatile: Use the specific format Versatile (1d10).
Magic weapon damage: Known base weapons retain their normal base damage unless an explicit Damage: field overrides it. Additional damage in description prose remains additional damage and does not replace the base roll.

4. Armor & Equipment

AC: Use AC 18 or Armor Class: 14.
Stealth: Use the phrase Disadvantage on Stealth checks.
Strength: Use Requires Strength 13 or Str 15.
Wondrous items: A declared Wondrous Item type imports as dnd5e wondrous equipment rather than loot.

5. Consumables

The header/name determines potion, scroll, wand, rod, ammunition, poison, food, or trinket subtype before description keywords are considered.
Phrases such as has 7 charges populate the maximum uses and start with zero uses spent. Prefer Uses Spent in strict YAML; legacy Uses Current means remaining uses and is converted with a warning.
Quantity suffixes preserve exact non-negative integers, including zero (Arrows (0)). Fractional or unsafe quantities and charge counts are ignored with a warning rather than truncated.

6. Containers

The parser looks for specific capacity phrases:

Weight: "Holds 500 pounds" or "Capacity: 500 lbs".
Volume: "64 cubic feet".
Currency: "Contains 50 gp" or "Holds 10 platinum".

EXAMPLE: WEAPON (Best Result)

Input

Stormglass Rapier
Weapon (rapier), rare (requires attunement)
Cost: 2500 gp, Weight: 2 lb.
Damage: 1d8 piercing
Properties: Finesse

This slender blade is forged from blue crystal that hums before a storm. The wielder has a +1 bonus to attack and damage rolls made with this magic weapon. When the wielder hits a creature with it, the target takes an extra 1d6 lightning damage. Once per turn, the wielder can force the target to make a DC 14 Constitution saving throw or be deafened until the end of its next turn.

EXAMPLE: ARMOR (Best Result)

Input

Emberguard Half Plate
Armor (half plate), rare (requires attunement)
Cost: 3500 gp, Weight: 40 lb.
Armor Class: 15 (max Dex 2)

This blackened half plate is warm to the touch and etched with lines like cooling lava. While wearing this armor, the wearer has a +1 bonus to AC and resistance to fire damage. When a creature within 5 feet hits the wearer with a melee attack, sparks leap from the plates and scorch the attacker.

EXAMPLE: CONTAINER (Best Result)

Input

Moonwell Bag
Container, uncommon
Weight: 2 lb.

This silver-threaded bag feels cool even in direct sunlight. The bag can hold up to 120 pounds, not exceeding a volume of 12 cubic feet, and its contents do not add to the carrier's encumbrance. The carrier can whisper the name of a stored item to retrieve it without searching. The bag currently contains 3 moonstones, 20 gp, and 12 sp.

EXAMPLE: TOOL (Best Result)

Input

Cartographer's Quillcase
Tool, uncommon
Cost: 75 gp, Weight: 1 lb.

This lacquered case contains enchanted inks, folding rulers, waxed vellum, and a silver nib that points toward true north. Proficiency with these tools lets the user add their proficiency bonus to ability checks they make to draw maps, mark safe routes, or decode old survey notes. Once per day, the user can mark one safe route they can see; checks to follow that route have advantage for 24 hours.

HOW IT WORKS (Internal Logic)

Extraction: The parser scans the text using Regex to find Stats (Name, Type, Cost, Weight, Damage, Properties, AC, etc.).
Stripping: It removes lines that look like Stats to isolate the Description.
Conversion: It builds a YAML document matching the strict template format.
Final Pass: It runs the generated YAML through the YamlItemParser for validation and item creation.

Strict Format Parser

Best for: Complex homebrew and bulk generation.

Strict Format uses a documented YAML shape instead of guessing from prose. Start with the template for the Item type you need, fill in the relevant fields, and parse it in the same importer window. Validation messages call out fields that need attention before import.

Validated Custom YAML Examples

These examples have been checked against the current parser and dnd5e Item schema. They use optional sections such as uses, recovery, chat flavor, unidentified descriptions, enrichers, and dynamic name lookups while remaining usable with 5e Item Importer alone.

⚔️ Stormglass Rapier (`WEAPON`)

SCHEMA_VERSION: 1
WEAPON:
  ITEM:
    Name: "Stormglass Rapier"
    Rarity: rare
    Weapon Type: martialM
    Base Weapon: rapier

  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false

  COST_AND_WEIGHT:
    Price Value: 2500
    Price Denomination: gp
    Weight Value: 2
    Weight Units: lb

  PROPERTIES:
    Adamantine: false
    Ammunition: false
    Magical: true
    Finesse: true
    Firearm: false
    Focus: false
    Heavy: false
    Light: false
    Loading: false
    Reach: false
    Reload: false
    Returning: false
    Silvered: false
    Special: true
    Thrown: false
    Two-Handed: false
    Versatile: false

  ATTUNEMENT:
    Attunement: required
    Attunement By: n/a
    Magic Bonus: 1

  RANGE:
    Reach: 5
    Range Normal: n/a
    Range Long: n/a
    Range Units: ft

  DAMAGE:
    Damage Formula: "1d8[piercing] + 1d6[lightning]"
    Damage Type: piercing

  MASTERY:
    Mastery: vex

  PROFICIENCY:
    Proficient: Automatic

  USAGE:
    Uses Spent: 0
    Uses Max: 3

  RECOVERY:
    - Period: dawn
      Type: formula
      Formula: "1d3"

  DESCRIPTION:
    Description: |
      <p>This slender blade is forged from blue crystal that hums before a storm.</p>
      <p>You have a +1 bonus to attack and damage rolls made with this magic weapon.</p>
      <p><strong>Stormglass Edge.</strong> When [[lookup @name]]{the creature} hits with this weapon, the target takes an extra [[/damage 1d6 lightning average]].</p>
      <p><strong>Thunderhead Lunge.</strong> [[lookup @name]]{The creature} can expend 1 charge to force the target to make a [[/save con 14 format=long]] or be &Reference[deafened] until the end of its next turn.</p>

  UNIDENTIFIED_DESCRIPTION:
    Unidentified Name: "Blue Crystal Rapier"
    Unidentified Description: |
      <p>A finely balanced rapier with a translucent blue blade and a faint static hum.</p>

  CHAT_FLAVOR:
    Chat Description: |
      [[lookup @name]]{The creature} thrusts with a storm-bright blade.

🛡️ Emberguard Half Plate (`EQUIPMENT`)

SCHEMA_VERSION: 1
EQUIPMENT:
  ITEM:
    Name: "Emberguard Half Plate"
    Rarity: rare
    Equipment Type: medium
    Base Equipment: halfplate

  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false

  COST_AND_WEIGHT:
    Price Value: 3500
    Price Denomination: gp
    Weight Value: 40
    Weight Units: lb

  PROPERTIES:
    Magical: true
    Adamantine: false
    Focus: false
    Stealth Disadvantage: true

  ATTUNEMENT:
    Attunement: required
    Attunement By: n/a
    Magic Bonus: 1

  ARMOR:
    Armor Class: 15
    Max Dex Modifier: 2
    Strength Requirement: n/a

  PROFICIENCY:
    Proficient: Automatic

  USAGE:
    Uses Spent: 0
    Uses Max: 2

  RECOVERY:
    - Period: dawn
      Type: recoverAll
      Formula: n/a

  DESCRIPTION:
    Description: |
      <p>This blackened half plate is warm to the touch and etched with lines like cooling lava.</p>
      <p>While [[lookup @name]]{the creature} wears this armor, they have a +1 bonus to AC and resistance to &Reference[fire] damage.</p>
      <p><strong>Cinder Flare.</strong> When a creature within 5 feet hits [[lookup @name]]{the creature} with a melee attack, they can expend 1 charge to deal [[/damage 2d6 fire average]] to the attacker.</p>

  UNIDENTIFIED_DESCRIPTION:
    Unidentified Name: "Blackened Half Plate"
    Unidentified Description: |
      <p>Blackened half plate with dull red seams and a faint smell of smoke.</p>

  CHAT_FLAVOR:
    Chat Description: |
      Sparks crawl across [[lookup @name]]{the creature}'s armor.

🧪 Potion of Sunlit Breath (`CONSUMABLE`)

SCHEMA_VERSION: 1
CONSUMABLE:
  ITEM:
    Name: "Potion of Sunlit Breath"
    Rarity: uncommon
    Consumable Type: potion

  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false

  COST_AND_WEIGHT:
    Price Value: 125
    Price Denomination: gp
    Weight Value: 0.5
    Weight Units: lb

  PROPERTIES:
    Magical: true

  ATTUNEMENT:
    Attunement: none
    Attunement By: n/a

  USAGE:
    Uses Spent: 0
    Uses Max: 1
    Destroy on Empty: true

  RECOVERY: []

  DESCRIPTION:
    Description: |
      <p>This golden potion fizzes with tiny motes of warm light.</p>
      <p>When [[lookup @name]]{the creature} drinks it, they regain [[/heal 2d4 + 2 average]] hit points and can breathe underwater and in smoke-filled air for 1 hour.</p>
      <p>During that hour, [[lookup @name]]{the creature} sheds dim sunlight in a 5-foot radius.</p>

  UNIDENTIFIED_DESCRIPTION:
    Unidentified Name: "Golden Fizzing Potion"
    Unidentified Description: |
      <p>A sealed vial of golden liquid with bubbles that rise like sparks.</p>

  CHAT_FLAVOR:
    Chat Description: |
      [[lookup @name]]{The creature} drinks a potion bright as sunrise.

🎒 Moonwell Bag (`CONTAINER`)

SCHEMA_VERSION: 1
CONTAINER:
  ITEM:
    Name: "Moonwell Bag"
    Rarity: uncommon

  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false

  COST_AND_WEIGHT:
    Price Value: 300
    Price Denomination: gp
    Weight Value: 2
    Weight Units: lb

  PROPERTIES:
    Magical: true
    Weightless Contents: true

  ATTUNEMENT:
    Attunement: none
    Attunement By: n/a

  CAPACITY:
    Item Count: 12
    Weight Capacity Value: 120
    Weight Capacity Units: lb
    Volume Capacity Value: 12
    Volume Capacity Units: cubicFoot

  CURRENCY_CONTENTS:
    Platinum: 0
    Gold: 20
    Electrum: 0
    Silver: 12
    Copper: 0

  DESCRIPTION:
    Description: |
      <p>This silver-threaded bag feels cool even in direct sunlight.</p>
      <p>The bag can hold up to 120 pounds, not exceeding a volume of 12 cubic feet, and its contents do not add to the carrier's encumbrance.</p>
      <p><strong>Moonwell Pocket.</strong> As an action, [[lookup @name]]{the creature} can whisper the name of a stored item to retrieve it without searching.</p>
      <p><strong>Overfilled.</strong> If the bag is overloaded, it ruptures and spills moonlit mist into the nearest unoccupied space.</p>

  UNIDENTIFIED_DESCRIPTION:
    Unidentified Name: "Silver-Threaded Bag"
    Unidentified Description: |
      <p>A soft travel bag stitched with silver thread and tiny pearl toggles.</p>

  CHAT_FLAVOR:
    Chat Description: |
      [[lookup @name]]{The creature} reaches into a cold shimmer of moonlight.

💎 Starfall Opal (`LOOT`)

SCHEMA_VERSION: 1
LOOT:
  ITEM:
    Name: "Starfall Opal"
    Rarity: rare
    Loot Type: gem

  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false

  COST_AND_WEIGHT:
    Price Value: 750
    Price Denomination: gp
    Weight Value: 0
    Weight Units: lb

  PROPERTIES:
    Magical: true

  DESCRIPTION:
    Description: |
      <p>This dark opal holds a silver streak like a falling star.</p>
      <p><strong>Diviner's Lens.</strong> A spellcaster can use the opal as a focus for divination rituals. A creature examining it can identify the omen trapped inside with a [[/check arcana 15 format=long]].</p>
      <p><strong>Celestial Residue.</strong> The gem is warm near sources of &Reference[radiant] damage and cold near sources of &Reference[necrotic] damage.</p>

  UNIDENTIFIED_DESCRIPTION:
    Unidentified Name: "Dark Opal"
    Unidentified Description: |
      <p>A polished black opal with a pale streak deep beneath its surface.</p>

  CHAT_FLAVOR:
    Chat Description: |
      The opal catches the light like a tiny falling star.

✨ Lantern Mote (`SPELL`)

SCHEMA_VERSION: 1
SPELL:
  ITEM:
    Name: "Lantern Mote"
    Level: 1
    School: evo
    Ability: n/a

  COMPONENTS:
    Vocal: true
    Somatic: true
    Material: true

  MATERIALS:
    Value: "a firefly wing sealed in amber"
    Cost: 0
    Supply: 1
    Consumed: false

  PREPARATION:
    Method: spell
    Prepared: true

  ACTIVATION:
    Type: action
    Value: 1
    Condition: n/a

  RANGE:
    Units: ft
    Value: 60

  DURATION:
    Units: minute
    Value: 10
    Concentration: false

  TARGETS:
    Type: space
    Count: 1
    Choice: false
    Special: n/a

  AREA:
    Shape: sphere
    Size: 10
    Units: ft
    Count: n/a
    Width: n/a
    Height: n/a
    Contiguous: n/a

  USAGE:
    Uses Spent: 0
    Uses Max: n/a

  RECOVERY: []

  DESCRIPTION:
    Description: |
      <p>[[lookup @name]]{The creature} creates a tiny floating mote of warm light at a point they can see within range.</p>
      <p>The mote sheds bright light in a 10-foot radius and dim light for an additional 10 feet. Invisible creatures in the bright light shimmer with a faint outline but are not revealed automatically.</p>
      <p>When the spell ends, one creature of the caster's choice in the bright light gains [[/heal 1d4 temp average]] temporary hit points.</p>
      <section class="secret" id="upcast"><p><strong>At Higher Levels.</strong> When [[lookup @name]]{the creature} casts this spell using a spell slot of 2nd level or higher, the bright-light radius increases by 5 feet for each slot level above 1st.</p></section>

  CHAT_FLAVOR:
    Chat Description: |
      [[lookup @name]]{The creature} releases a small sun-colored mote.

⚒️ Cartographer's Quillcase (`TOOL`)

SCHEMA_VERSION: 1
TOOL:
  ITEM:
    Name: "Cartographer's Quillcase"
    Rarity: uncommon
    Tool Type: art
    Base Tool: cartographer

  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false

  COST_AND_WEIGHT:
    Price Value: 75
    Price Denomination: gp
    Weight Value: 1
    Weight Units: lb

  PROPERTIES:
    Magical: true
    Tool Bonus: 1

  ATTUNEMENT:
    Attunement: none
    Attunement By: n/a

  ABILITY_CHECK:
    Proficient: Automatic
    Ability: wis

  USAGE:
    Uses Spent: 0
    Uses Max: 3

  RECOVERY:
    - Period: dawn
      Type: recoverAll
      Formula: n/a

  DESCRIPTION:
    Description: |
      <p>This lacquered case contains enchanted inks, folding rulers, waxed vellum, and a silver nib that points toward true north.</p>
      <p>While using these tools, [[lookup @name]]{the creature} has a +1 bonus to ability checks made with them.</p>
      <p><strong>True-North Mark.</strong> [[lookup @name]]{The creature} can expend 1 charge while drawing a map to mark one safe route they can see. For the next 24 hours, checks to follow that route can use [[/check survival 13 format=long]] or [[/check cartographer 13 format=long]].</p>

  UNIDENTIFIED_DESCRIPTION:
    Unidentified Name: "Lacquered Quillcase"
    Unidentified Description: |
      <p>A travel-worn case filled with precise mapping tools and unusually bright ink.</p>

  CHAT_FLAVOR:
    Chat Description: |
      [[lookup @name]]{The creature} sketches a line that refuses to point anywhere but true north.

📦 Mixed-Type Batch Example

SCHEMA_VERSION: 1
WEAPON:
  ITEM:
    Name: "Stormglass Rapier"
    Rarity: rare
    Weapon Type: martialM
    Base Weapon: rapier
  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false
  COST_AND_WEIGHT:
    Price Value: 2500
    Price Denomination: gp
    Weight Value: 2
    Weight Units: lb
  PROPERTIES:
    Magical: true
    Finesse: true
  ATTUNEMENT:
    Attunement: required
    Magic Bonus: 1
  RANGE:
    Reach: 5
  DAMAGE:
    Damage Formula: "1d8[piercing] + 1d6[lightning]"
    Damage Type: piercing
  USAGE:
    Uses Spent: 0
    Uses Max: 3
  RECOVERY:
    - Period: dawn
      Type: formula
      Formula: "1d3"
  DESCRIPTION:
    Description: |
      <p>A blue crystal dueling blade that crackles before a storm. When [[lookup @name]]{the creature} hits with it, the target takes an extra [[/damage 1d6 lightning average]].</p>

CONSUMABLE:
  ITEM:
    Name: "Potion of Sunlit Breath"
    Rarity: uncommon
    Consumable Type: potion
  COST_AND_WEIGHT:
    Price Value: 125
    Price Denomination: gp
    Weight Value: 0.5
    Weight Units: lb
  PROPERTIES:
    Magical: true
  USAGE:
    Uses Spent: 0
    Uses Max: 1
    Destroy on Empty: true
  RECOVERY: []
  DESCRIPTION:
    Description: |
      <p>For 1 hour, [[lookup @name]]{the creature} can breathe underwater and in smoke-filled air.</p>
  CHAT_FLAVOR:
    Chat Description: |
      [[lookup @name]]{The creature} drinks a potion bright as sunrise.

LOOT:
  ITEM:
    Name: "Starfall Opal"
    Rarity: rare
    Loot Type: gem
  COST_AND_WEIGHT:
    Price Value: 750
    Price Denomination: gp
    Weight Value: 0
    Weight Units: lb
  PROPERTIES:
    Magical: true
  DESCRIPTION:
    Description: |
      <p>This dark opal holds a silver streak like a falling star. A creature examining it can identify the omen trapped inside with a [[/check arcana 15 format=long]].</p>

🔁 Same-Type Batch Example

SCHEMA_VERSION: 1
WEAPON:
  ITEM:
    Name: "Stormglass Rapier"
    Rarity: rare
    Weapon Type: martialM
    Base Weapon: rapier
  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false
  COST_AND_WEIGHT:
    Price Value: 2500
    Price Denomination: gp
    Weight Value: 2
    Weight Units: lb
  PROPERTIES:
    Magical: true
    Finesse: true
  ATTUNEMENT:
    Attunement: required
    Magic Bonus: 1
  RANGE:
    Reach: 5
  DAMAGE:
    Damage Formula: "1d8[piercing] + 1d6[lightning]"
    Damage Type: piercing
  MASTERY:
    Mastery: vex
  USAGE:
    Uses Spent: 0
    Uses Max: 3
  RECOVERY:
    - Period: dawn
      Type: formula
      Formula: "1d3"
  DESCRIPTION:
    Description: |
      <p>A blue crystal dueling blade that crackles before a storm. When [[lookup @name]]{the creature} hits with it, the target takes an extra [[/damage 1d6 lightning average]].</p>
---
SCHEMA_VERSION: 1
WEAPON:
  ITEM:
    Name: "Whisperpin Dagger"
    Rarity: uncommon
    Weapon Type: simpleM
    Base Weapon: dagger
  INVENTORY:
    Quantity: 1
    Identified: true
    Equipped: false
  COST_AND_WEIGHT:
    Price Value: 600
    Price Denomination: gp
    Weight Value: 1
    Weight Units: lb
  PROPERTIES:
    Magical: true
    Finesse: true
    Light: true
    Thrown: true
    Returning: true
  ATTUNEMENT:
    Attunement: none
    Attunement By: n/a
    Magic Bonus: 1
  RANGE:
    Reach: 5
    Range Normal: 20
    Range Long: 60
    Range Units: ft
  DAMAGE:
    Damage Formula: "1d4"
    Damage Type: piercing
  MASTERY:
    Mastery: nick
  PROFICIENCY:
    Proficient: Automatic
  USAGE:
    Uses Spent: 0
    Uses Max: 2
  RECOVERY:
    - Period: dusk
      Type: recoverAll
      Formula: n/a
  DESCRIPTION:
    Description: |
      <p>A matte-black returning dagger that drinks in nearby sound.</p>
      <p>When [[lookup @name]]{the creature} hits with this weapon, they can expend 1 charge to force the target to make a [[/save wis 13 format=long]] or be unable to speak above a whisper until the end of its next turn.</p>
  CHAT_FLAVOR:
    Chat Description: |
      [[lookup @name]]{The creature} throws a blade that returns without a sound.

Advanced: dnd5e description enrichers and name lookups

Description and Chat Description fields preserve Foundry/dnd5e text features for Foundry to resolve when displayed. You can use dnd5e enrichers like [[/damage 1d6 fire average]], roll-data formulas like @prof, dynamic lookups like [[lookup @name]]{the creature}, System HTML classes, and pass-through document links like @UUID[...] or @Embed[...].

Use dynamic name lookups for active narration and chat flavor, such as [[lookup @name]]{The creature} drinks the potion. or When [[lookup @name]]{the creature} hits with this weapon.... Keep passive rules text natural.

Optional companion: Token Name Lookup can make the same stock dnd5e [[lookup @name]] text prefer concrete token names for aliases, disguises, and token inventory views. Items remain fully compatible without that module; dnd5e simply resolves the lookup to the actor name.

Template Downloads

The full strict templates live as real module files under templates/YAML Templates/. Use those files as the source of truth; the README keeps only validated examples so the docs do not drift.

After installing the module, the same files are available locally in your Foundry data folder:

modules/5e-item-importer/templates/YAML Templates/

Template	View in Repo	Raw Download
Weapon	Strict Weapon Template	Raw
Consumable	Strict Consumable Template	Raw
Container	Strict Container Template	Raw
Equipment	Strict Equipment Template	Raw
Loot	Strict Loot Template	Raw
Spell	Strict Spell Template	Raw
Tool	Strict Tool Template	Raw

For import-ready examples, use the validated custom YAML examples, the mixed-type batch example, and the same-type batch example above.

Strict YAML rules worth knowing

For mixed weapon damage, use a dnd5e typed custom formula such as 1d8[piercing] + 1d6[lightning] and set Damage Type to the weapon's primary damage type, such as piercing. Do the same for Versatile Damage Type. The primary type gives dnd5e a default for system-added ability and magic bonuses, while bracketed formula terms keep extra damage such as lightning separate for resistance and immunity. Use n/a only for fully self-contained typed formulas that will not receive system-added ability, magic, or ammunition bonuses. For saves, conditions, healing, and other effects that need automation beyond base item fields, keep the rules in the description text unless the user explicitly wants Activity Importer support.

Strict YAML reports unknown sections and field names as warnings so typos are not silently ignored. A parse with validation errors returns no importable item; correct the reported fields before importing.

Strict numeric scalars are parsed exactly: quantities and uses must be integers, while price, weight, and weight/volume capacities may be finite decimals; these values cannot be negative. Values with trailing text such as 12abc are errors rather than numeric prefixes. Attunement By is retained only when Attunement is required or optional; it is cleared with a warning for none or invalid attunement values.

Advanced: Schema versions, exports, and integration contracts

New strict YAML documents begin with visible schema metadata:

SCHEMA_VERSION: 1
WEAPON:
  ITEM:
    Name: "Example Weapon"

The parser reports migration provenance and carries it through mixed and multi-document batches. Documents declaring a schema version newer than the installed importer supports are rejected instead of being partially imported. Uses Max, magic bonuses, tool bonuses, and recharge thresholds preserve compatible dnd5e formula strings; legacy Uses Current cannot be converted against a formula maximum and fails with an instruction to provide Uses Spent.

The strict exporter supports Weapon, Equipment, Consumable, Tool, Loot, Container, and Spell Items. Core Item export is always available, excludes Activities and Active Effects, and is the default for api.export(), api.exportBatch(), copy, download, and Item drops when the companion serializers are unavailable. Full Item export is an explicit companion workflow exposed by api.exportFull(), api.exportFullBatch(), { mode: "full" }, and the Full Item YAML context actions shown when Activity Importer exposes both synchronous serializers. Batch export uses --- document separators so repeated Item types remain lossless.

For full export, every live dnd5e Activity and Active Effect is serialized from its current document state through Activity Importer's api.serializeActivity() and api.serializeEffect() services, so later edits supersede stored provenance. If the companion is unavailable, the current state cannot be represented, a third-party field is present, or the serializer cannot prove a lossless mapping, full export stops with an explicit error. Activity-specific effect application metadata is matched separately from the effect body. A shared Active Effect referenced by multiple Activities is rejected because the current strict format cannot preserve that topology without duplication; duplicate requested effect IDs are also rejected during import. A linked effect is omitted from the standalone effects section only when its exact serialized body is embedded in its owning Activity. Low-level export options continue to accept includeActivities and includeEffects; each alias takes precedence over the older aggregate attachment options when both are supplied.

Custom properties use this strict shape:

CUSTOM_PROPERTIES:
  Registered:
    - "registeredPropertyId"
  Metadata:
    my-module.note: "Namespaced metadata only"

Registered accepts only property IDs registered for that Item type by dnd5e. Metadata requires namespaced keys and is stored under the Item Importer's flags. Metadata keys are never treated as system.* update paths. The core adapter returns registered property IDs separately from the nested flag object so callers cannot accidentally flatten metadata into Item system data.

Parser confidence, provenance, and review suggestions are produced locally. Natural-text suggestions can recognize explicit extra damage, healing, saving throws, conditions, and recharge wording. They remain previews unless automation synthesis is explicitly requested. If Activity Importer is available, attachment payloads can also be checked through its public parser API.

Compendium image candidates are collected locally and can be selected randomly, with a seed for reproducible random choice, or deterministically. Cache enablement, lifetime, size, statistics, and clearing are explicit controls. AutoAnimations candidates now cover weapons, spells, consumables, tools, and equipment, can use inline activity hints, and are persisted only when a sufficiently confident candidate is available; installed animation database availability is checked at runtime.

The supported module API remains feature-detected:

const importer = game.modules.get("5e-item-importer")?.api;
const result = importer?.parse(text, {
  trace: true,
  synthesizeAutomation: false
});

Internal UI integrations load scripts/itemCoreFeatures.js defensively and verify each capability before use. That facade exposes the strict exporters, schema migration helpers, parse insights, safe custom-property adapters, compendium image candidate/cache services, natural automation synthesis/validation, and AutoAnimations preview/flag builders. Callers should likewise feature-detect functions and must not interpret returned metadata keys as Foundry property paths.

Import Workflow

Paste text, choose a template, or drop an Item, Actor, Journal passage, or local text/YAML file into the importer. After parsing, review the preview and choose a World Items folder, an owned Actor, or a writable Item compendium as the destination.

When a matching Item already exists, choose whether to create another copy, update it, merge conservatively, or skip it. Update and merge show the exact target and any field conflicts before writing. Ambiguous matches are stopped for review.

Saved presets, import options, normalized YAML, and session history stay collapsed until you need them. Batch imports can be filtered, cancelled before the next write, and retried without recreating successful entries. Session history can download a report or undo an unchanged import from the current session.

Advanced: Settings and public API

Relevant registered settings:

Setting key	Scope	Purpose
`savedPresets`	client	Bounded reusable input presets
`lastDestination`	client	Last permission-validated destination
`compendiumImageMode`	client	Deterministic or random top image selection

const api = game.modules.get("5e-item-importer").api;
api.schemaVersion; // Public API schema 3
api.capabilities.exportModes; // ["core", "full"]
const preview = api.parseWithInsights(sourceText);
await api.import(sourceText, {
  destination: { kind: "actor", actorUuid: actor.uuid },
  duplicateMode: "merge",
  confirmExisting: true
});
const coreYaml = await api.export(item);       // Standalone default: Item fields only
const fullYaml = await api.exportFull(item);   // Explicit companion export
const sameFullYaml = await api.export(item, { mode: "full" });
await api.copyExport(item);
await api.downloadExport(item);

API undo is intentionally explicit: api.history.undo(sessionId, { confirmed: true }). The legacy api.import(text, folderId) signature remains supported.

Common Issues

The natural parser missed or misread a field.

Check the preview before importing. Clear labels such as Damage:, Properties:, and Weight: help. For complicated Items, use the strict template for that Item type.

Icons aren't matching automatically.

Go to Module Settings and enable "Match Icons from Compendiums". This works best when the item name includes a recognizable D&D 5e base item or item type (for example, "Stormglass Rapier", "Emberguard Half Plate", or "Potion of Sunlit Breath"). Use Compendium image choice to select the best deterministic match or a random top match. Random selection can still be made reproducible with a seed when using the core service programmatically.

Description is empty.

If using Natural Language: Ensure there is a n/a line between the stat block and the description. If using Strict Format: Use the YAML block form Description: | and indent the HTML description beneath it, as shown in the validated examples and template files.

Installation

Foundry -> Add-on Modules -> Install Module.
Search "5e Item Importer", or paste this manifest URL:

https://github.com/GnollStack/5e-Item-Importer/releases/latest/download/module.json

Enable the module in your world.

Compatibility

Requirement	Version
Foundry VTT	v14+ (verified through v14.363)
D&D 5e System	v5.3.3+ (verified through v5.3.3)

This release line intentionally targets Foundry VTT v14 and dnd5e v5.3.x. If your world is staying on Foundry v13, use the last stable v13-compatible release instead.

Community

Report bugs — open an issue with your Foundry version, module version, steps to reproduce, console logs, and screenshots or short clips when useful.
Request features — tell me what happened at your table and what you wish the module could do.
Star the repo — if the module is useful at your table, a star helps other GMs find it.
Watch releases — follow the repo for updates, compatibility notes, and new feature releases.

Contributing

Bug reports, feature ideas, reproduction notes, documentation fixes, and localization ideas are welcome.

Contribution policy

I am not generally accepting unsolicited code PRs for features, refactors, architecture, or behavior changes. This is still my module and my codebase; I will decide how features are designed and implemented unless I explicitly say otherwise.

Bug reports — include Foundry version, module version, a console log, and the steps to reproduce. Screenshots or short clips help a lot.
Feature requests — tell me what happened at your table and what you wish the module could do.
Pull requests — please do not open code PRs unless I ask for one. Open an issue with the idea instead.
Code ownership — core implementation, architecture, and release decisions remain with GnollStack unless stated otherwise.
Translations and docs - UI strings use Foundry's public localization setup in lang/en.json, primarily under II.* keys. Typo fixes, wording suggestions, and translation files are welcome by issue first; the code-contribution policy above still applies.

Submitted ideas may be adapted, declined, or implemented by GnollStack. Any accepted contribution or submitted project material may be released under the same EULA as the rest of the module.

AI-Assisted Development

This module is developed and maintained with the help of AI-assisted tools for coding, debugging, and testing.

I care about the quality, behavior, performance, security, and long-term maintainability of this module, and I take full responsibility for what ships. AI assistance does not replace review, testing, debugging, or security and design judgment.

AI is used here as a tool under my direction to make Foundry better and allow for long term mod support while still having a life outside of building and maintaining my free and premium modules.

If you are uncomfortable using software developed with AI-assisted tools, this module is not for you.

🥩 Support Development

This module represents many hours of development.

If this module enhanced your immersion, consider treating me to a steak, much better than coffee!

"Thanks for the support! It helps me maintain support for the module and puts a nice steak on the table."

⚖️ License & Permissions

Proprietary EULA

This module is licensed under the GnollStack Proprietary EULA. It is Free for Personal Use, meaning you can use it in your home games, stream it, or modify it for your own table without restriction.

However, Commercial Redistribution is Strictly Prohibited. You may NOT sell this module, bundle it within paid content (such as Patreon maps or adventures), or host it as a commercial service without prior written consent.

Commercial Licensing

I am open to partnerships! If you are a map maker, adventure writer, or developer who wishes to use this module commercially, please contact me. I offer commercial licenses for:

Bundling this module with paid VTT content.
Official integration into commercial systems.
Custom feature development for your specific product.

Contact

For licensing inquiries or permission slips:

Discord: GnollStack (Preferred)
Email: Somedudeed@gmail.com
Please do not open GitHub Issues for commercial licensing discussions. But feel free to contact me via Discord or Email

Author: GnollStack · Compatibility: Foundry VTT v14+ (verified v14.363)

⬆ Back to Top

Name		Name	Last commit message	Last commit date
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
lang		lang
scripts		scripts
styles		styles
templates		templates
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE.txt		LICENSE.txt
README.md		README.md
jsconfig.json		jsconfig.json
module.json		module.json

Latest commit

History

Folders and files

Repository files navigation

5e Item Importer

Overview

Quick Start

Preview

See it in Action on YouTube

What You Get

Natural Language Parser

Strict Format Parser

Batch Imports

Lightweight Key/Value Drafts

Natural Language Parser

Best Practice Patterns

BEST PRACTICE PATTERNS

1. Naming & Header

2. Type Detection

3. Weapons

4. Armor & Equipment

5. Consumables

6. Containers

EXAMPLE: WEAPON (Best Result)

Input

EXAMPLE: ARMOR (Best Result)

Input

EXAMPLE: CONTAINER (Best Result)

Input

EXAMPLE: TOOL (Best Result)

Input

HOW IT WORKS (Internal Logic)

Strict Format Parser

Validated Custom YAML Examples

Template Downloads

Import Workflow

Common Issues

Installation

Compatibility

Community

Contributing

AI-Assisted Development

🥩 Support Development

⚖️ License & Permissions

Proprietary EULA

Commercial Licensing

Contact

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages