familiar-vtt 2.5.19 → 2.5.22

package/README.md

@@ -4,15 +4,16 @@
 
 ### Your AI co-pilot for Foundry VTT
 
-**175 tools. 28 AI providers. Zero prep.**
+**185 tools. 26 AI providers. Zero prep.**
 
-Give your favorite AI full control of your virtual tabletop, characters, combat, scenes, music, lighting, images, voices, and everything in between.
+Run combat, set the mood, and voice your NPCs - all by talking to your AI.
 
 [![Foundry v13+](https://img.shields.io/badge/Foundry-v13%2B-orange?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48cGF0aCBmaWxsPSIjZmZmIiBkPSJNMjU2IDhDMTE5LjA0MyA4IDggMTE5LjA4MyA4IDI1NmMwIDEzNi45OTcgMTExLjA0MyAyNDggMjQ4IDI0OHMyNDgtMTExLjAwMyAyNDgtMjQ4QzUwNCAxMTkuMDgzIDM5Mi45NTcgOCAyNTYgOHoiLz48L3N2Zz4=)](https://foundryvtt.com)
 [![npm](https://img.shields.io/npm/v/familiar-vtt?color=blue&label=npm)](https://www.npmjs.com/package/familiar-vtt)
+[![Discord](https://img.shields.io/discord/1361024685498564744?logo=discord&label=Discord&color=5865F2)](https://discord.gg/3633wB9yp)
 [![License](https://img.shields.io/badge/license-PolyForm%20Shield-lightgrey)](#license)
 
-[Installation](#installation) | [Connect Your AI](#connect-your-ai) | [FAQ](#faq) | [Roadmap](#roadmap)
+[Installation](#installation) | [Connect Your AI](#connect-your-ai) | [Pricing](#pricing) | [FAQ](#faq) | [Roadmap](#roadmap)
 
 </div>
 
@@ -24,11 +25,7 @@ My wife and I play D&D together, just the two of us, 1-on-1 campaigns. It's our
 
 I wanted something that could handle the mechanical side of the table so I could stay in the story. Not a replacement DM, a co-pilot. Something I could say "roll initiative for the goblins, dim the torches, and start combat music" to, and it would just... do it. While I kept talking.
 
-So I started building. First it was a handful of tools to move tokens and roll dice. Then I added combat tracking. Then scene management. Then I thought "what if it could also generate NPC portraits on the fly?" and "what if it could voice the tavern keeper?" and that's basically how you end up with 175 tools across 24 domains and 28 AI providers.
-
-The thing is, Familiar works best when there is already great content in your world. The Foundry community has spent years building incredible modules, battle maps, character sheets, compendium packs, and ready-to-play adventures. Familiar does not try to replace any of that. It reads what is already there and uses it. Right now I'm running [Ember](https://foundryvtt.com/packages/ember), Foundry's own 500-hour sandbox campaign, with Familiar as my co-pilot. Every quest, NPC, map, and encounter is already in the world. The AI just picks it up and runs with it. That beautifully lit dungeon map someone spent weeks on? The AI can place tokens on it, trigger the right music, and run the encounter. Those compendium entries with pre-built monsters, spells, and items? The AI pulls from them instead of making things up. The more content your world has, the better Familiar gets.
-
-That is also why module integrations are high on the roadmap. Tools like Midi-QOL, Sequencer, and JB2A already do amazing things, Familiar just needs to learn how to talk to them. The community built the stage. Familiar helps you run the show.
+So I started building. First it was a handful of tools to move tokens and roll dice. Then I added combat tracking. Then scene management. Then I thought "what if it could also generate NPC portraits on the fly?" and "what if it could voice the tavern keeper?" and that's basically how you end up with 185 tools across 24 domains and 26 AI providers.
 
 It started as a personal itch-scratcher for a dad who wanted to run better D&D games for his wife. It turns out a lot of GMs have the same itch.
 
@@ -38,15 +35,15 @@ Ask your AI to do things that would normally take you minutes of clicking throug
 
 > "Roll initiative for all the goblins, have them attack the nearest player, and play battle music."
 
-> "Create a torchlit dungeon room, place the party at the entrance, and add three skeletons near the altar."
-
-> "What spells does Elara have prepared? Does she have enough slots to cast Fireball?"
+> "Spawn two Wolves from the compendium as reinforcements, place them near the forest edge, and add them to combat with initiative rolled."
 
 > "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead, in his voice."
 
+> "Find a CR 3 werewolf in the compendium, drop it into the scene as a boss, and give it resistance to non-silvered weapons."
+
 > "We're done for tonight. Summarize what happened this session and save it."
 
-Familiar exposes **175 tools across 24 domains** through the Model Context Protocol. Five core bundles are always available; the rest load on demand when your AI needs them.
+Familiar exposes **185 tools across 24 domains** through the Model Context Protocol. Five core bundles are always available; the rest load on demand when your AI needs them.
 
 ### Highlights
 
@@ -56,21 +53,21 @@ Familiar exposes **175 tools across 24 domains** through the Model Context Proto
 
 **Combat & AI**
 
-Run full encounters hands-free. Roll initiative, resolve attacks, apply damage, track conditions, or let the AI play NPCs with tactical decision-making.
+29 tools manage encounters end-to-end: initiative, attacks, spells, damage, conditions, death saves, and XP. The AI can pilot NPC turns using battlefield snapshots, scored movement with cover analysis, and full action resolution including multiattack and legendary actions.
 
 </td>
 <td width="33%" valign="top">
 
 **Voice & Image Generation**
 
-Give every NPC a unique AI-generated voice. Generate scene illustrations and character portraits mid-session without leaving the table.
+Assign unique AI voices to NPCs and bring dialogue to life with multi-voice text-to-speech across four providers. Generate character portraits, item art, and battle map backgrounds on the fly.
 
 </td>
 <td width="33%" valign="top">
 
 **Scenes & Canvas**
 
-Build maps on the fly. Place tokens, draw walls, set lighting and weather, configure regions, control the entire canvas through natural language.
+Create scenes, place tokens, draw walls and doors, set lighting and darkness, add weather effects, and configure trigger regions. Full control over tiles, drawings, ambient sounds, fog of war, and camera.
 
 </td>
 </tr>
@@ -79,42 +76,43 @@ Build maps on the fly. Place tokens, draw walls, set lighting and weather, confi
 
 **Audio & Atmosphere**
 
-Manage playlists, trigger sound effects, crossfade tracks. Set the mood without alt-tabbing to Foundry's sidebar.
+Play, stop, and manage playlists and individual tracks with volume and fade control. Cue battle music, build ambient soundscapes, or silence everything without touching Foundry's sidebar.
 
 </td>
 <td width="33%" valign="top">
 
 **Knowledge & Memory**
 
-Campaign journal, session summaries, and a searchable knowledge base the AI can reference. It remembers what happened three sessions ago.
+Semantic search across all journals, characters, scenes, and items. A persistent memory bank stores important campaign facts that carry over between sessions, with full journal management for session notes and handouts.
 
 </td>
 <td width="33%" valign="top">
 
 **Characters & Items**
 
-Create, update, and inspect actors, inventory, spells, features, and active effects. Bulk operations across the whole party.
+Inspect, create, update, and clone actors, inventory, spells, features, and active effects. Import from compendiums, apply custom buffs, and manage player ownership.
 
 </td>
 </tr>
 </table>
 
-### All 24 Domains
+<details>
+<summary><b>All 24 Domains</b></summary>
 
 | Domain | Tools | What it does |
 |---|--:|---|
-| **Characters & Actors** | 14 | Create, inspect, update, and manage player characters and NPCs |
-| **Combat & Initiative** | 13 | Start encounters, roll initiative, advance turns and rounds |
 | **Scenes & Tokens** | 19 | Build scenes, place and move tokens, configure vision and movement |
 | **Canvas Environment** | 18 | Walls, lights, weather effects, fog of war, darkness levels |
+| **Combat & Initiative** | 17 | Start encounters, roll initiative, advance turns and rounds |
+| **Characters & Actors** | 14 | Create, inspect, update, and manage player characters and NPCs |
 | **Audio & Playlists** | 14 | Play, stop, and crossfade music and ambient sound |
+| **Combat AI** | 12 | NPC tactical decisions, target selection, ability usage, positioning |
 | **Journals & Notes** | 10 | Create and edit journal entries, map pins, and handouts |
 | **Card Decks** | 9 | Draw, deal, shuffle, pass, and manage card hands and decks |
 | **Canvas Drawing** | 8 | Draw shapes, text, and freehand annotations on the canvas |
 | **Rollable Tables** | 7 | Create tables and roll on them for random encounters or loot |
 | **Macros** | 7 | Create, edit, and execute Foundry macros |
 | **World & System** | 6 | World info, system settings, time, pause, and user management |
-| **Combat AI** | 6 | NPC tactical decisions, target selection, ability usage, positioning |
 | **Items** | 6 | Create, update, delete, and search world-level items |
 | **Active Effects** | 5 | Apply, remove, and toggle buffs, debuffs, and status effects |
 | **Folders** | 5 | Organize documents into folder hierarchies |
@@ -128,6 +126,27 @@ Create, update, and inspect actors, inventory, spells, features, and active effe
 | **Image Generation** | 1 | Generate scene art or character portraits on demand |
 | **Scene Generator** | 1 | Generate complete scenes from text blueprints |
 
+</details>
+
+## Installation
+
+Install the Foundry module, pick a provider, and start talking to your game.
+
+If you want to connect an MCP client (Claude Desktop, Claude Code, Gemini CLI, or ChatGPT), you also need the MCP server:
+
+```sh
+npx familiar-vtt
+```
+
+The **MCP Setup Wizard** in Module Settings > Familiar walks you through connecting your client step by step.
+
+### Compatibility
+
+| | Supported |
+|---|---|
+| **Foundry VTT** | v13, v14 |
+| **Game System** | D&D 5e (2024 rules), full support. Other systems work for general features (chat, journals, scenes, audio) but lack system-specific tools like character sheets and combat automation. |
+
 ## Connect your AI
 
 There are two ways to connect an AI to your game. Both give the AI the same tools, the difference is where the AI runs and how you pay.
@@ -136,20 +155,20 @@ There are two ways to connect an AI to your game. Both give the AI the same tool
 
 No server. No terminal. No config files. Just install the module, pick a provider, paste an API key, and start talking to your game.
 
-Familiar connects directly to **28 AI providers** across four categories:
+Familiar connects directly to **26 AI providers** across four categories:
 
 | Category | Providers |
 |----------|-----------|
 | **Chat** (16) | OpenRouter, Anthropic, OpenAI, Google, Groq, Mistral, Together AI, DeepSeek, xAI, Cohere, Perplexity, Fireworks AI, Cerebras, SambaNova, Ollama (local), LM Studio (local) |
 | **Voice** (4) | ElevenLabs, Cartesia, OpenAI TTS, PlayHT |
-| **Image** (5) | OpenAI (GPT Image), Stability AI, fal.ai, Leonardo AI, Replicate |
+| **Image** (3) | OpenAI (GPT Image), fal.ai, Leonardo AI |
 | **Transcription** (3) | Gladia, Deepgram, AssemblyAI |
 
 This is the right choice if you want the simplest setup, or if you want voice, images, and transcription alongside chat. It is also the only option that supports local models (Ollama, LM Studio) for fully offline play.
 
 ### Option 2: MCP (your existing subscription)
 
-Already paying for Claude, ChatGPT, or Gemini? Connect them directly to Familiar through the [Model Context Protocol](https://modelcontextprotocol.io). Your subscription becomes a DM assistant at no extra API cost.
+Already paying for Claude, ChatGPT, or Gemini? Put that subscription to work. Connect them directly to Familiar through the [Model Context Protocol](https://modelcontextprotocol.io). Your subscription becomes a DM assistant at no extra API cost.
 
 Familiar supports four MCP clients out of the box:
 
@@ -176,6 +195,7 @@ You do not need to configure each client by hand. The module includes a step-by-
 | Use my Claude/ChatGPT/Gemini subscription | **MCP** |
 | Run everything offline | **Built-in chat** with Ollama or LM Studio |
 | Have voice, images, and transcription | **Built-in chat** (MCP is text-only) |
+| Run complex multi-step tasks | **MCP** (external clients handle long chains better) |
 
 ### Your keys, your cost
 
@@ -183,36 +203,20 @@ Most AI tabletop tools lock you into their ecosystem. They charge per turn, per
 
 Familiar works differently. You bring your own AI, whether that is an API key you already have or a subscription to Claude, ChatGPT, or Gemini. Familiar never proxies, meters, or marks up your usage. Your API keys go straight from your browser to the provider. With MCP, your existing subscription handles it. There is no middleman, no per-turn limits, and no credits that run out.
 
-For $7/month you get all 175 tools, all 28 providers, voice, images, transcription, and full MCP support. No tiers, no feature gates. Compare that to platforms that charge $20-40/month and still limit how many turns you can take or what models you can use.
+## Works with what you already have
 
-## Installation
+Familiar works best when there is already great content in your world. The Foundry community has spent years building incredible modules, battle maps, character sheets, compendium packs, and ready-to-play adventures. Familiar does not try to replace any of that. It reads what is already there and uses it.
 
-In Foundry VTT, go to **Settings > Manage Modules > Install Module** and search for **Familiar**. Enable it in your world under **Settings > Manage Modules**.
+Those compendium entries with pre-built monsters, spells, and items? The AI pulls from them instead of making things up. That beautifully lit dungeon map someone spent weeks on? The AI can place tokens on it, trigger the right music, and run the encounter. The more content your world has, the better Familiar gets.
 
-If you want to connect an MCP client (Claude Desktop, Claude Code, Gemini CLI, or ChatGPT), you also need the MCP server:
-
-```sh
-npx familiar-vtt
-```
-
-The **MCP Setup Wizard** in Module Settings > Familiar walks you through connecting your client step by step.
+## Pricing
 
-### Compatibility
+**$3/month** with a **free 1-month trial** so you can try everything before you commit. All features are available during the trial, no restrictions.
 
-| | Supported |
-|---|---|
-| **Foundry VTT** | v13, v14 |
-| **Game System** | D&D 5e (2024 rules), full support. Other systems work for general features (chat, journals, scenes, audio) but lack system-specific tools like character sheets and combat automation. |
+Familiar itself costs $3/month. AI provider costs are separate and depend on your usage and chosen provider. A typical D&D session runs roughly $0.50–$3 in API costs depending on the model, or $0 if you use a subscription (Claude, ChatGPT, Gemini) through MCP or local models through Ollama.
 
 ## FAQ
 
-<details>
-<summary><b>How much does Familiar cost?</b></summary>
-
-Familiar is a paid module with a free 1-month trial so you can try everything before you commit. All features are available during the trial, no restrictions.
-
-</details>
-
 <details>
 <summary><b>Does Familiar collect my data?</b></summary>
 
@@ -230,7 +234,7 @@ Familiar sanitizes all document updates so the AI cannot change ownership, permi
 <details>
 <summary><b>What is the difference between MCP mode and built-in chat?</b></summary>
 
-Built-in chat runs directly inside Foundry with no server required, it makes API calls straight to your AI provider and is the fastest way to get started. MCP mode connects Familiar to external clients like Claude Desktop, ChatGPT, or Gemini through a local server, which lets you use your existing subscriptions and is more powerful for complex multi-step tasks. Both modes have access to the same 175 tools.
+Built-in chat runs directly inside Foundry with no server required, it makes API calls straight to your AI provider and is the fastest way to get started. MCP mode connects Familiar to external clients like Claude Desktop, ChatGPT, or Gemini through a local server, which lets you use your existing subscriptions and is more powerful for complex multi-step tasks. Both modes have access to the same 185 tools.
 
 </details>
 
@@ -248,6 +252,13 @@ Absolutely, solo and small-group play is one of the main use cases. I built Fami
 
 </details>
 
+<details>
+<summary><b>Can I use Familiar as a player (not a GM)?</b></summary>
+
+Familiar requires GM permissions. It is designed as a GM tool that reads and modifies world data. Players can interact with it through the built-in chat if the GM enables it, but the module itself needs GM-level access to function.
+
+</details>
+
 <details>
 <summary><b>Does it work with game systems other than D&D 5e?</b></summary>
 
@@ -268,37 +279,19 @@ Things I'm actively working toward. No promises on timelines.
 
 ### Module Integrations
 
-Let the AI control the most popular Foundry modules, automated rolls, visual effects, animations, loot, and more.
+Let the AI control the most popular Foundry modules - automated rolls, visual effects, animations, loot, and more.
 
 | Module | What Familiar will do with it |
 |--------|-------------------------------|
 | Midi-QOL | Automated attack rolls, saving throws, and damage application |
-| Sequencer | Orchestrate animation sequences and visual storytelling |
-| JB2A (Animated Assets) | Trigger spell effects, explosions, and environmental animations |
-| Automated Animations | Auto-apply JB2A effects to spells and abilities |
+| Sequencer + JB2A | Orchestrate animation sequences and trigger spell effects |
 | Token Magic FX | Apply shader effects to tokens and tiles (fire auras, glowing shields) |
-| Dice So Nice | Sync 3D dice rolls with AI-triggered actions |
 | Item Piles | Create and manage loot drops, merchants, and treasure hoards |
-| Monk's Active Tile Triggers | Set up interactive tiles (traps, doors, teleporters) by voice |
-| Tidy 5e Sheets | Read and update the enhanced character sheet layout |
 | DFreds Convenient Effects | Apply and manage curated status effects and buffs |
 
 ### Ready-to-Play Adventures
 
-Plug-and-play support for the most popular published adventures. Import the adventure, enable Familiar, and the AI already knows the story, NPCs, maps, and encounters.
-
-| Adventure | Publisher |
-|-----------|-----------|
-| Ember | Foundry VTT |
-| Curse of Strahd | Wizards of the Coast |
-| Phandelver and Below: The Shattered Obelisk | Wizards of the Coast |
-| Tomb of Annihilation | Wizards of the Coast |
-| Waterdeep: Dragon Heist | Wizards of the Coast |
-| Storm King's Thunder | Wizards of the Coast |
-| Ghosts of Saltmarsh | Wizards of the Coast |
-| Descent into Avernus | Wizards of the Coast |
-| Rime of the Frostmaiden | Wizards of the Coast |
-| Crown of the Oathbreaker | Elderbrain |
+Plug-and-play support for published adventures. Import the adventure, enable Familiar, and the AI already knows the story, NPCs, maps, and encounters. Starting with [Ember](https://foundryvtt.com/packages/ember) (Foundry's own 500-hour sandbox campaign) and expanding to popular published modules.
 
 ### Game System Support
 
@@ -310,30 +303,22 @@ Expanding beyond D&D 5e with full system-specific tools (character sheets, comba
 | Pathfinder 2e | Planned |
 | Call of Cthulhu | Planned |
 | Savage Worlds | Planned |
-| Warhammer Fantasy Roleplay | Planned |
 
 ### Improvements
 
-- **Voice generation**: more natural NPC voices, emotion control, multi-voice conversations
-- **Image generation**: faster scene art, consistent character portraits across sessions, style presets
-- **Transcription**: improved accuracy, real-time command detection, multi-language support
 - **Combat AI**: smarter NPC tactics, group coordination, retreat behavior, morale
+- **Voice generation**: more natural NPC voices, emotion control, multi-voice conversations
 - **Built-in chat**: conversation memory across sessions, campaign knowledge base, auto-summarization
+- **Image generation**: consistent character portraits across sessions, style presets
 - **MCP**: faster tool execution, better multi-step task handling, richer feedback to clients
 
-### Bug Fixes & Stability
-
-Active bug triage through the [Discord](https://discord.gg/3633wB9yp). Foundry version compatibility (v13, v14, and future releases) is always a priority.
-
 ## Feedback
 
-Familiar's source code is private, but your input matters. If you run into bugs, have feature ideas, or just want to tell me about the weird thing the AI did to your goblin encounter:
-
-- Join the [Discord](https://discord.gg/3633wB9yp)
+Join the [Discord](https://discord.gg/3633wB9yp) - bug reports, feature ideas, or just tell me about the weird thing the AI did to your goblin encounter.
 
 ## License
 
-Familiar is licensed under the [PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/). You can use, read, and modify the software freely, but you may not use it to build a competing product. See [LICENSE](LICENSE) for the full text.
+Familiar is licensed under the [PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/). You can use, read, and modify the software freely, but you may not use it to build a competing product. See [LICENSE](https://github.com/Ryanjansen92/familiar-releases/blob/main/LICENSE) for the full text.
 
 <div align="center">