Bytes AI Foundry

Generate complete, game-ready D&D 5e content with AI — items, NPCs, characters, and roll tables.

🆕 What’s New in v2.3.0 — NPC & Character Generation + Multi-Provider AI

17 new files, 8 modified files, ~7,000 lines of new code. 367 unit tests.

🎭 AI-Powered Actor Generation

• NPC Generation — Describe any creature and the module generates a complete stat block (CR 0–30) with ability scores, HP, AC, actions, traits, spellcasting, legendary actions/resistances, and lair actions. Weapons, spells, and features embedded from compendium when available.
• Character Generation — Create full player characters with class, subclass, race, level, background, ability scores, skills, equipment, spells, personality, and biography. Spell slots computed per class caster type (full/half/third/pact).
• SRD Compendium Integration — SRD races and classes pull traits, features, and spells directly from dnd5e compendium packs with proper icons, descriptions, and advancement flags.
• Homebrew Race Support — Non-SRD races get AI-generated original racial traits as homebrew feat items, balanced against SRD benchmarks. No copying from published sourcebooks.
• NPC Compendium Lookups — NPC traits (Sunlight Sensitivity, Undead Fortitude, Magic Resistance, etc.) matched against SRD compendium for proper icons and descriptions.
• Actor Validator — Strict D&D 5e rule enforcement: HP from hit dice + CON, proficiency from CR/level, spell slots from class caster tables, AC from armor, ability scores clamped, skills/languages normalized. All corrections shown in preview.
• Portrait + Token Images — Two separate AI images per actor, each regenerable independently.
• Actor Preview Dialog — Review stats, embedded items, corrections, and warnings before creating. Regen buttons for name, portrait, token, and stats.
• 11 Actor Templates — 5 NPC archetypes + 5 character archetypes + 1 placeholder.

⚠️ Generated actors are a starting point, not a finished product. Always review generated NPCs and characters before using them in play — the GM is the final authority. Stats, features, and descriptions can all be edited on the actor sheet after creation.

🔌 Multi-Provider AI Support

• Text AI Providers — OpenAI GPT (default), Google Gemini, xAI Grok, local Ollama, or any OpenAI-compatible custom endpoint.
• Image AI Providers — GPT Image 1 (default), DALL·E 3/2, xAI Aurora, Stability AI, fal.ai.
• Provider Registry — Clean base-class architecture with 10 provider implementations. Each handles its own API format, auth, and model selection.
• Settings UI — Dropdown to select text/image provider, API key field updates contextually with hints.
• Description-Fed Images — Item descriptions are now passed to image generation prompts for better visual consistency.

⚖️ SRD Compliance

• SRD vs Non-SRD Paths — SRD races leave species/background fields for Foundry’s built-in wizard. Non-SRD races get fully fleshed-out homebrew traits.
• Original Content Only — AI prompts explicitly instruct: “Do NOT copy from published D&D sourcebooks — create original content.”
• Legal Disclaimers — SRD content notice and AI-generated content disclaimer added to LICENSE and README.

🚀 Features

AI-Powered Item Creation

• One-Click Generation — Describe what you want and the module creates a fully populated item sheet with name, description, stats, image, and all dnd5e data fields
• All Item Types — Weapons, armor, shields, spells, feats, consumables (potions, scrolls, ammunition), tools, loot, containers, and backgrounds
• Smart Type Detection — A three-stage safety net ensures items are always classified correctly, even when the AI gets it wrong
• Item Preview Dialog — Review and edit name, description, image, and stat badges before committing, with per-field regeneration
• Try Again / Variations — Re-run the full generation with the same prompt until you get exactly what you want
• Compendium Validation — Items cross-referenced against SRD compendium packs with duplicate detection and smart defaults fallback
• AI Items Folder — All generated items auto-placed in an “AI Items” folder; roll table items get named subfolders
• Prompt Templates — 10 built-in presets that auto-fill the prompt, item type, and generation mode
• Generation History — View all items generated this session with regen buttons for name, image, or description
• Cost Estimation — Estimated USD cost on the progress bar during generation and session totals in History

AI-Powered Actor Generation

• NPC Generation — Complete stat blocks (CR 0–30) with actions, traits, spellcasting, legendary abilities, and compendium-sourced features
• Character Generation — Full player characters with class, race, level, background, skills, equipment, and personality
• Strict Rule Validation — HP, AC, proficiency, spell slots, ability scores all rule-validated with corrections shown in preview
• Portrait + Token Images — Two AI images per actor, each regenerable independently
• 11 Templates — 5 NPC + 5 character archetypes

D&D 5e v4/v5 Native Support

• Activities System — Automatically creates Attack, Save, Damage, Heal, Utility, and Cast activities with correct formulas, save DCs, and damage parts
• Active Effects — Parses item descriptions and maps bonuses to 80+ effect keys — skills, saves, AC, movement, resistances, immunities, senses, and more
• PHB Defaults — Built-in lookup tables for 40+ weapons and 18 armor types ensure stats match the Player’s Handbook exactly
• Two-Pass Description Validation — Regex scan then GPT-informed scan extracts every mechanical bonus and converts them into proper Active Effects
• Castable Spell Embedding — Items with spell-casting abilities get Cast activities linked to real spell documents from your world or compendiums

Multi-Provider AI

• Text Providers — OpenAI GPT, Google Gemini, xAI Grok, Ollama, or any OpenAI-compatible endpoint
• Image Providers — GPT Image 1, DALL·E 3/2, xAI Aurora, Stability AI, fal.ai, Stable Diffusion (local)
• Provider Selection — Dropdown in settings to choose text and image providers independently

Image Generation

• GPT Image 1 — Default image model with high-quality artwork and automatic local storage (PNG, WebP, or JPEG)
• DALL·E 3 / DALL·E 2 — Legacy support available but deprecated (stops working May 12, 2026)
• Stable Diffusion — Optional local image generation via Stable Diffusion API
• Media Optimizer — Compatible with the Media Optimizer module

Roll Table Generation

• Item Tables — Every entry is a fully generated item document with its own image, stats, and effects
• Generic Tables — Thematic text-only tables (random encounters, loot descriptions, rumors)
• Configurable Entry Count — Choose how many entries to generate per table

Robust Architecture

• 30+ Modular ES Modules — Clean separation of concerns: API, generators, validators, utilities, and UI
• Triple-Layer JSON Parsing — Native parse → GPT auto-repair → regex extraction
• Foundry v12 + v13 — Full compatibility with both major versions, no deprecation warnings
• Customizable Prompts — All generation prompts (items, NPCs, characters, images) exposed in module settings
• 367 Unit Tests — Comprehensive Vitest coverage of utilities, validators, and parsers

📖 How to Use

1. Open the Generator — Navigate to the Items or Actors tab in the sidebar. Click “Generate AI” in the directory footer (GM only).
2. Choose What to Generate — Item, Roll Table, NPC, or Character.
3. Configure Options — For items: type selection, templates, name override. For NPCs: CR, creature type, templates. For characters: level, class, race, background, templates.
4. Describe What You Want — Enter a prompt like “A cursed greatsword that drains the wielder’s health on each hit” or “A cunning goblin shaman who leads a small cult in the sewers”.
5. Preview & Create — Click Generate, review the preview (edit name, description, regen images/stats), then Confirm to create.

🛠 Supported Item Types

⚙️ Settings

All settings are found in Game Settings > Configure Settings > Bytes AI Foundry.

🔧 Troubleshooting

• “API Key is not set” — Add your API key in module settings for your selected provider.
• Image not saving — Ensure data/chatgpt-item-generator/ folder exists and has write permissions.
• Wrong item type — Try using explicit type selection instead of auto-detect for tricky items.
• JSON parse errors — The triple-layer parser handles most issues automatically. If it persists, try simplifying your prompt.
• Stable Diffusion not connecting — Add to your webui-user.bat: set COMMANDLINE_ARGS=--cors-allow-origins="*" --api

🗺 Roadmap

• ✅ Item preview before creation (v2.2)
• ✅ Regenerate individual parts (v2.2)
• ✅ Compendium-aware validation (v2.2)
• ✅ NPC & Character Generation (v2.3)
• ✅ Multi-Provider AI Support (v2.3)
• Encounter Generation — Generate balanced encounter groups with multiple NPCs
• Pathfinder 2e Support — System detection with PF2e-specific data models and prompts
• Community contributions welcome — feedback and ideas are appreciated

⚖️ Legal & Disclaimers

This module references game mechanics from the D&D 5e SRD 5.1 under the CC-BY-4.0 license. It does not distribute copyrighted content — SRD content is accessed from your own dnd5e compendium packs at runtime.

All NPCs, characters, items, and narrative content are generated dynamically by third-party AI services using the user’s own API key. This content is not created, reviewed, or endorsed by the module author. All generated content should be reviewed by the Game Master before use in play.

Author: Byte_Smarter · Discord: Byte_smarter · MIT License