Magic Variant Implementation Summary

Note: The dedicated 5etools splitter crate was removed in v0.5.0. Source data archives are now pre-processed externally. This document is retained as a reference for understanding the magic variant expansion logic.

Overview

The 5etools magic variant expansion system was implemented in the Mimir 5etools splitter. This system dynamically generates thousands of magic item variants by combining base items with generic variant templates.

Implementation Status

✅ Completed Features

1. Magic Variant Parsing

   • Loads and parses magicvariants.json
   • Handles all variant fields including entries as both strings and objects
   • Supports optional fields like ammo, hasFluffImages

2. Requirement Matching

   • Implements OR logic for requirements array (item must match ANY requirement)
   • Implements AND logic within each requirement object (ALL properties must match)
   • Supports boolean, string, array, and nested object matching
   • Handles exclusions to prevent certain combinations

3. Item Transformation

   • Name modifications:
     • nameRemove: Removes text from name (applied first)
     • namePrefix: Adds prefix to name
     • nameSuffix: Adds suffix to name
   • Property modifications:
     • propertyAdd: Adds weapon/armor properties
     • propertyRemove: Removes properties
   • Inherited attributes:
     • Source, page, rarity, tier
     • Combat bonuses (bonusWeapon, bonusAc, etc.)
     • Loot tables
     • Entries with template variable replacement

4. Template Variable Replacement

   • {=bonusWeapon} → “+1”, “+2”, etc.
   • {=bonusWeaponAttack} → Attack bonus value
   • {=dmgType} → Full damage type name (e.g., “S” → “slashing”)

5. Output Generation

   • Includes both generic variants (templates) and specific variants (generated items)
   • Adds metadata fields (_category, _isGenericVariant, _isItemGroup)
   • Creates separate expanded-weapons.json for weapon variants
   • Preserves base item reference for linking

6. ItemGroup Processing

   • Loads itemGroup from items.json
   • Marks with _isItemGroup flag
   • Includes in output alongside regular items

Example Results

For the DMG book:

• 130 generic variants (the templates like “+1 Weapon”)
• 1,871 specific variants (generated items like “+1 Longsword”)
• Item groups included where applicable

Example: +1 Longsword

{
  "name": "+1 Longsword",
  "baseItem": "longsword|phb",
  "source": "DMG",
  "rarity": "uncommon",
  "tier": "major",
  "bonusWeapon": "+1",
  "entries": [
    "You have a +1 bonus to attack and damage rolls made with this magic weapon."
  ],
  // ... all base longsword properties preserved
}

Example: Chain Mail Barding

Demonstrates nameRemove in action:

• Base item: “Chain Mail Armor”
• Variant: Removes “ Armor“, adds “ Barding“
• Result: “Chain Mail Barding” (not “Chain Mail Armor Barding”)

Architecture

The implementation is split across two main modules:

1. magic_variants.rs

   • Parsing magic variant JSON structures
   • Requirement matching logic
   • Item transformation and template processing
   • Variant expansion algorithm

2. collector.rs

   • Integration with the book collection pipeline
   • Loading and filtering items
   • Orchestrating variant expansion
   • File generation

Testing

The system has been tested with:

• Full 5etools dataset (v1.210.46)
• DMG book generation with 1,871 magic item variants
• Various edge cases (nameRemove, property modifications, etc.)
• Template variable replacement
• ItemGroup inclusion

Future Enhancements

While the current implementation is comprehensive, potential future enhancements could include:

1. Item property and type definitions

   • Including itemProperty and itemType from items.json
   • Would provide complete metadata for rendering

2. Linked loot tables

   • Processing linkedLootTables from magicvariants.json
   • Mapping items to their loot table appearances

3. Brew support

   • Allowing custom magic variants
   • Supporting homebrew base items

4. Performance optimizations

   • Parallel processing of variants
   • Caching parsed structures

Conclusion

The magic variant expansion system is now fully functional and produces output compatible with 5etools’ data format. This enables the Mimir system to work with the complete range of D&D 5e magic items without requiring manual data entry for each variant.