familiar-vtt 2.5.20 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +137 -117
  2. package/dist/mcp-package/index.mjs +81 -50
  3. package/package.json +20 -15
package/README.md CHANGED
@@ -4,117 +4,126 @@
4
4
 
5
5
  ### Your AI co-pilot for Foundry VTT
6
6
 
7
- **175 tools. 28 AI providers. Zero prep.**
7
+ **188 tools. 26 AI providers. Zero prep.**
8
8
 
9
- Give your favorite AI full control of your virtual tabletop, characters, combat, scenes, music, lighting, images, voices, and everything in between.
9
+ Run combat, set the mood, and voice your NPCs, all by talking to your AI.
10
10
 
11
11
  [![Foundry v13+](https://img.shields.io/badge/Foundry-v13%2B-orange?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48cGF0aCBmaWxsPSIjZmZmIiBkPSJNMjU2IDhDMTE5LjA0MyA4IDggMTE5LjA4MyA4IDI1NmMwIDEzNi45OTcgMTExLjA0MyAyNDggMjQ4IDI0OHMyNDgtMTExLjAwMyAyNDgtMjQ4QzUwNCAxMTkuMDgzIDM5Mi45NTcgOCAyNTYgOHoiLz48L3N2Zz4=)](https://foundryvtt.com)
12
12
  [![npm](https://img.shields.io/npm/v/familiar-vtt?color=blue&label=npm)](https://www.npmjs.com/package/familiar-vtt)
13
+ [![Discord](https://img.shields.io/discord/1483457566594961419?logo=discord&label=Discord&color=5865F2)](https://discord.gg/pN6pEvYH)
13
14
  [![License](https://img.shields.io/badge/license-PolyForm%20Shield-lightgrey)](#license)
14
15
 
15
- [Installation](#installation) | [Connect Your AI](#connect-your-ai) | [FAQ](#faq) | [Roadmap](#roadmap)
16
+ [Installation](#installation) | [Connect Your AI](#connect-your-ai) | [Pricing](#pricing) | [FAQ](#faq) | [Roadmap](#roadmap)
16
17
 
17
18
  </div>
18
19
 
19
- ## The story behind Familiar
20
+ ## What can Familiar do?
20
21
 
21
- I'm Ryan. Dad of two young kids, married to my favorite person, and perpetually short on free time.
22
+ Ask your AI to do things that would normally take you minutes of clicking through menus:
22
23
 
23
- My wife and I play D&D together, just the two of us, 1-on-1 campaigns. It's our thing. But solo DMing is a lot. You're the storyteller, every NPC, the rules engine, the sound guy, and the atmosphere all at once. I'd be mid-monologue as a mysterious stranger and then have to break character to roll initiative, look up a spell range, adjust the lighting, and find that one tavern ambience track I swore I bookmarked. By the time I got back to the scene, the moment was gone.
24
+ > "Roll initiative for all the goblins, have them attack the nearest player, and play battle music."
24
25
 
25
- 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.
26
+ > "Spawn two Wolves from the compendium as reinforcements, place them near the forest edge, and add them to combat with initiative rolled."
26
27
 
27
- 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.
28
+ > "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead, in his voice."
28
29
 
29
- 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.
30
+ > "Find a CR 3 werewolf in the compendium, drop it into the scene as a boss, and give it resistance to non-silvered weapons."
30
31
 
31
- 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.
32
+ > "We're done for tonight. Summarize what happened and save it."
32
33
 
33
- 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.
34
+ Familiar exposes **188 tools across 24 domains** through the Model Context Protocol. Tools load as your AI needs them. No upfront configuration.
34
35
 
35
- ## What can Familiar do?
36
+ ### Highlights
36
37
 
37
- Ask your AI to do things that would normally take you minutes of clicking through menus:
38
+ <table>
39
+ <tr>
40
+ <td width="33%" valign="top">
38
41
 
39
- > "Roll initiative for all the goblins, have them attack the nearest player, and play battle music."
42
+ **Combat & AI**
40
43
 
41
- > "Create a torchlit dungeon room, place the party at the entrance, and add three skeletons near the altar."
44
+ 29 tools cover encounters end to end: initiative, attacks, spells, damage, conditions, death saves, and XP. NPCs make their own tactical decisions using battlefield snapshots, scored movement, and cover analysis.
42
45
 
43
- > "What spells does Elara have prepared? Does she have enough slots to cast Fireball?"
46
+ </td>
47
+ <td width="33%" valign="top">
44
48
 
45
- > "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead, in his voice."
49
+ **Auto-Pilot**
46
50
 
47
- > "We're done for tonight. Summarize what happened this session and save it."
51
+ Click "Run NPC" and walk away. Familiar plays every enemy turn in the encounter for you, with safety caps and optional turn-by-turn confirmation.
48
52
 
49
- 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.
53
+ </td>
54
+ <td width="33%" valign="top">
50
55
 
51
- ### Highlights
56
+ **Live Transcription**
52
57
 
53
- <table>
58
+ Speak instead of type. Familiar transcribes your session in real time across three providers, color-codes per speaker, and saves the transcript to a Foundry journal.
59
+
60
+ </td>
61
+ </tr>
54
62
  <tr>
55
63
  <td width="33%" valign="top">
56
64
 
57
- **Combat & AI**
65
+ **Scenes & Canvas**
58
66
 
59
- Run full encounters hands-free. Roll initiative, resolve attacks, apply damage, track conditions, or let the AI play NPCs with tactical decision-making.
67
+ 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.
60
68
 
61
69
  </td>
62
70
  <td width="33%" valign="top">
63
71
 
64
72
  **Voice & Image Generation**
65
73
 
66
- Give every NPC a unique AI-generated voice. Generate scene illustrations and character portraits mid-session without leaving the table.
74
+ Assign unique AI voices to NPCs across four providers. Have the tavern keeper actually speak his lines, in his own voice. Generate character portraits, item art, and battle map backgrounds on the fly.
67
75
 
68
76
  </td>
69
77
  <td width="33%" valign="top">
70
78
 
71
- **Scenes & Canvas**
79
+ **Audio & Atmosphere**
72
80
 
73
- Build maps on the fly. Place tokens, draw walls, set lighting and weather, configure regions, control the entire canvas through natural language.
81
+ Play, stop, and crossfade playlists and individual tracks with volume and fade control. Cue battle music, build ambient soundscapes, or silence everything without touching Foundry's sidebar.
74
82
 
75
83
  </td>
76
84
  </tr>
77
85
  <tr>
78
86
  <td width="33%" valign="top">
79
87
 
80
- **Audio & Atmosphere**
88
+ **Knowledge & Memory**
81
89
 
82
- Manage playlists, trigger sound effects, crossfade tracks. Set the mood without alt-tabbing to Foundry's sidebar.
90
+ Semantic search across every journal, character, scene, and item. A persistent memory bank stores campaign facts that carry over between sessions, plus a continuously-rewritten plot summary the GM can read later.
83
91
 
84
92
  </td>
85
93
  <td width="33%" valign="top">
86
94
 
87
- **Knowledge & Memory**
95
+ **Multi-Session Chat**
88
96
 
89
- Campaign journal, session summaries, and a searchable knowledge base the AI can reference. It remembers what happened three sessions ago.
97
+ Pin, archive, and switch between named campaign threads. Each thread persists as a Foundry journal entry with a full audit log, so you can return to any conversation later.
90
98
 
91
99
  </td>
92
100
  <td width="33%" valign="top">
93
101
 
94
102
  **Characters & Items**
95
103
 
96
- Create, update, and inspect actors, inventory, spells, features, and active effects. Bulk operations across the whole party.
104
+ Build NPCs, manage party inventory, apply buffs, and clone monsters from any compendium. Active effects, ownership, and player permissions all wired up.
97
105
 
98
106
  </td>
99
107
  </tr>
100
108
  </table>
101
109
 
102
- ### All 24 Domains
110
+ <details>
111
+ <summary><b>All 24 Domains</b></summary>
103
112
 
104
113
  | Domain | Tools | What it does |
105
114
  |---|--:|---|
106
- | **Characters & Actors** | 14 | Create, inspect, update, and manage player characters and NPCs |
107
- | **Combat & Initiative** | 13 | Start encounters, roll initiative, advance turns and rounds |
108
115
  | **Scenes & Tokens** | 19 | Build scenes, place and move tokens, configure vision and movement |
109
116
  | **Canvas Environment** | 18 | Walls, lights, weather effects, fog of war, darkness levels |
117
+ | **Combat & Initiative** | 17 | Start encounters, roll initiative, advance turns and rounds |
118
+ | **Characters & Actors** | 16 | Create, inspect, update, and manage player characters and NPCs |
110
119
  | **Audio & Playlists** | 14 | Play, stop, and crossfade music and ambient sound |
120
+ | **Combat AI** | 12 | NPC tactical decisions, target selection, ability usage, positioning |
111
121
  | **Journals & Notes** | 10 | Create and edit journal entries, map pins, and handouts |
112
122
  | **Card Decks** | 9 | Draw, deal, shuffle, pass, and manage card hands and decks |
113
123
  | **Canvas Drawing** | 8 | Draw shapes, text, and freehand annotations on the canvas |
114
124
  | **Rollable Tables** | 7 | Create tables and roll on them for random encounters or loot |
115
125
  | **Macros** | 7 | Create, edit, and execute Foundry macros |
116
- | **World & System** | 6 | World info, system settings, time, pause, and user management |
117
- | **Combat AI** | 6 | NPC tactical decisions, target selection, ability usage, positioning |
126
+ | **World & System** | 7 | World info, system settings, time, pause, and user management |
118
127
  | **Items** | 6 | Create, update, delete, and search world-level items |
119
128
  | **Active Effects** | 5 | Apply, remove, and toggle buffs, debuffs, and status effects |
120
129
  | **Folders** | 5 | Organize documents into folder hierarchies |
@@ -128,135 +137,173 @@ Create, update, and inspect actors, inventory, spells, features, and active effe
128
137
  | **Image Generation** | 1 | Generate scene art or character portraits on demand |
129
138
  | **Scene Generator** | 1 | Generate complete scenes from text blueprints |
130
139
 
140
+ </details>
141
+
142
+ ## Pricing
143
+
144
+ **$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.
145
+
146
+ 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/Codex, Gemini) through MCP or local models through Ollama.
147
+
148
+ ### Your keys, your cost
149
+
150
+ Most AI tabletop tools lock you into their ecosystem. They charge per turn, per credit, or per token, and you're stuck with whatever model they picked for you. Run out of credits mid-session? Too bad.
151
+
152
+ Familiar works differently. You bring your own AI, whether that's an API key you already have or a subscription to Claude, ChatGPT/Codex, 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's no middleman, no per-turn limits, and no credits that run out.
153
+
154
+ ## Installation
155
+
156
+ Install the Foundry module, pick a provider, and start talking to your game.
157
+
158
+ If you want to connect an MCP client (Claude Desktop, Claude Code, Codex CLI, Gemini CLI, or ChatGPT), you also need the MCP server:
159
+
160
+ ```sh
161
+ npx familiar-vtt
162
+ ```
163
+
164
+ The **MCP Setup Wizard** in Module Settings → Familiar walks you through connecting your client step by step. No JSON editing.
165
+
166
+ ### Compatibility
167
+
168
+ | | Supported |
169
+ |---|---|
170
+ | **Foundry VTT** | v13, v14 |
171
+ | **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. |
172
+
131
173
  ## Connect your AI
132
174
 
133
- 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.
175
+ There are two ways to connect an AI to your game. Both give the AI the same 188 tools. The difference is where the model runs and how you pay.
134
176
 
135
177
  ### Option 1: Built-in chat (API key)
136
178
 
137
- No server. No terminal. No config files. Just install the module, pick a provider, paste an API key, and start talking to your game.
179
+ No server. No terminal. No config files. Install the module, pick a provider, paste an API key, and start talking.
138
180
 
139
- Familiar connects directly to **28 AI providers** across four categories:
181
+ Familiar connects directly to **26 AI providers** across four categories:
140
182
 
141
183
  | Category | Providers |
142
184
  |----------|-----------|
143
- | **Chat** (16) | OpenRouter, Anthropic, OpenAI, Google, Groq, Mistral, Together AI, DeepSeek, xAI, Cohere, Perplexity, Fireworks AI, Cerebras, SambaNova, Ollama (local), LM Studio (local) |
185
+ | **Chat** (16) | OpenRouter¹, Anthropic, OpenAI, Google, Groq, Mistral, Together AI, DeepSeek, xAI, Cohere, Perplexity, Fireworks AI, Cerebras, SambaNova, Ollama (local), LM Studio (local) |
144
186
  | **Voice** (4) | ElevenLabs, Cartesia, OpenAI TTS, PlayHT |
145
- | **Image** (5) | OpenAI (GPT Image), Stability AI, fal.ai, Leonardo AI, Replicate |
187
+ | **Image** (3) | OpenAI (GPT Image), fal.ai, Leonardo AI |
146
188
  | **Transcription** (3) | Gladia, Deepgram, AssemblyAI |
147
189
 
148
- 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.
190
+ ¹ *OpenRouter unlocks 300+ models on a single key.*
191
+
192
+ This is the right choice if you want the simplest setup, or if you want voice, images, and live transcription alongside chat. It's also the only option that supports local models (Ollama, LM Studio) for fully offline play.
149
193
 
150
194
  ### Option 2: MCP (your existing subscription)
151
195
 
152
- 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.
196
+ Already paying for Claude, ChatGPT/Codex, or Gemini? Put that subscription to work. Connect it directly to Familiar through the [Model Context Protocol](https://modelcontextprotocol.io). Your subscription becomes a DM assistant at no extra API cost.
153
197
 
154
- Familiar supports four MCP clients out of the box:
198
+ Familiar supports five MCP clients out of the box:
155
199
 
156
200
  | Client | Transport | Setup |
157
201
  |--------|-----------|-------|
158
202
  | Claude Desktop | stdio | Add to `claude_desktop_config.json` |
159
203
  | Claude Code (CLI) | stdio | `claude mcp add familiar -- npx familiar-vtt` |
160
- | Gemini CLI | stdio | Add to MCP settings (free with Gemini 3.1 Pro) |
204
+ | Codex CLI | stdio | `codex mcp add familiar -- npx -y familiar-vtt` |
205
+ | Gemini CLI | stdio | Add to MCP settings |
161
206
  | ChatGPT | Streamable HTTP | Remote URL via Cloudflare tunnel |
162
207
 
163
- The MCP server ships as an npm package:
164
-
165
- ```bash
166
- npx familiar-vtt
167
- ```
168
-
169
- You do not need to configure each client by hand. The module includes a step-by-step **MCP Setup Wizard** (in Module Settings > Familiar) that detects your connected client and generates the exact config, just copy and paste.
208
+ You don't need to configure each client by hand. The **MCP Setup Wizard** in Module Settings → Familiar detects your connected client and generates the exact config. Copy and paste.
170
209
 
171
210
  ### Which should I pick?
172
211
 
173
212
  | I want to... | Use |
174
213
  |--------------|-----|
175
214
  | Get started in under a minute | **Built-in chat** with any API key |
176
- | Use my Claude/ChatGPT/Gemini subscription | **MCP** |
215
+ | Use my Claude/ChatGPT/Codex/Gemini subscription | **MCP** |
177
216
  | Run everything offline | **Built-in chat** with Ollama or LM Studio |
178
217
  | Have voice, images, and transcription | **Built-in chat** (MCP is text-only) |
218
+ | Run complex multi-step tasks | **MCP** (external clients handle long chains better) |
179
219
 
180
- ### Your keys, your cost
220
+ ## Works with what you already have
181
221
 
182
- Most AI tabletop tools lock you into their ecosystem. They charge per turn, per credit, or per token, and you're stuck with whatever model they picked for you. Run out of credits mid-session? Too bad.
222
+ Familiar works best when there's 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 doesn't try to replace any of that. It reads what's already there and uses it.
183
223
 
184
- 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.
224
+ 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.
185
225
 
186
- ## Installation
187
-
188
- In Foundry VTT, go to **Settings > Manage Modules > Install Module** and search for **Familiar**. Enable it in your world under **Settings > Manage Modules**.
226
+ ## Why I built this
189
227
 
190
- If you want to connect an MCP client (Claude Desktop, Claude Code, Gemini CLI, or ChatGPT), you also need the MCP server:
228
+ I'm Ryan. Dad of two young kids, married to my favorite person, with the free time you'd expect.
191
229
 
192
- ```sh
193
- npx familiar-vtt
194
- ```
230
+ My wife and I play D&D together, just the two of us, 1-on-1 campaigns. It's our thing. But solo DMing is a lot. You're the storyteller, every NPC, the rules engine, the sound guy, and the atmosphere all at once. Mid-monologue as a mysterious stranger, I'd have to break character to roll initiative, look up a spell range, adjust the lighting, and find that one tavern ambience track I swore I bookmarked. By the time I got back to the scene, the moment was gone.
195
231
 
196
- The **MCP Setup Wizard** in Module Settings > Familiar walks you through connecting your client step by step.
232
+ 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 handle it. While I kept talking.
197
233
 
198
- ### Compatibility
234
+ 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 "what if it could also generate NPC portraits on the fly?" and "what if it could voice the tavern keeper?" That's how you end up with 188 tools across 24 domains and 26 AI providers.
199
235
 
200
- | | Supported |
201
- |---|---|
202
- | **Foundry VTT** | v13, v14 |
203
- | **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. |
236
+ 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.
204
237
 
205
238
  ## FAQ
206
239
 
207
240
  <details>
208
- <summary><b>How much does Familiar cost?</b></summary>
241
+ <summary><b>Does Familiar collect my data?</b></summary>
209
242
 
210
- 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.
243
+ No. There's no telemetry, no analytics, and no data collection of any kind. Familiar runs entirely inside your local Foundry instance. Your data only leaves your machine when you choose to send a message to an external AI provider. If you use local models through Ollama or LM Studio, nothing ever leaves your network.
211
244
 
212
245
  </details>
213
246
 
214
247
  <details>
215
- <summary><b>Does Familiar collect my data?</b></summary>
248
+ <summary><b>Can the AI break my world?</b></summary>
216
249
 
217
- No. There is no telemetry, no analytics, and no data collection of any kind. Familiar runs entirely inside your local Foundry instance. Your data only leaves your machine when you choose to send a message to an external AI provider. If you use local models through Ollama or LM Studio, nothing ever leaves your network.
250
+ Familiar sanitizes all document updates so the AI can't change ownership, permissions, or internal IDs. Prototype pollution protection is built in, destructive operations require confirmation, and WebSocket connections use shared-secret authentication. Always keep backups regardless. Good practice with or without AI.
218
251
 
219
252
  </details>
220
253
 
221
254
  <details>
222
- <summary><b>Can the AI break my world?</b></summary>
255
+ <summary><b>What happens to my data if I cancel?</b></summary>
223
256
 
224
- Familiar sanitizes all document updates so the AI cannot change ownership, permissions, or internal IDs. Prototype pollution protection is built in, destructive operations require confirmation, and WebSocket connections use shared-secret authentication. That said, always keep backups of your world, that is good practice regardless.
257
+ Everything stays in your Foundry world. Memory banks, knowledge base indexes, session transcripts, generated portraits, all of it lives in your local Foundry data directory, owned by your world. Cancelling stops Familiar from running new tool calls once the license check fails, but nothing the AI already created gets touched.
225
258
 
226
259
  </details>
227
260
 
228
261
  <details>
229
- <summary><b>What is the difference between MCP mode and built-in chat?</b></summary>
262
+ <summary><b>Does this work on The Forge or other hosted Foundry providers?</b></summary>
230
263
 
231
- 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.
264
+ Built-in chat works anywhere Foundry runs, including The Forge. The module makes API calls directly from the browser. MCP mode is trickier: it needs a local MCP server alongside Foundry, so hosted providers without shell access can't run the server. Use built-in chat for hosted Foundry, MCP for self-hosted.
265
+
266
+ </details>
267
+
268
+ <details>
269
+ <summary><b>What's the difference between MCP mode and built-in chat?</b></summary>
270
+
271
+ Built-in chat runs inside Foundry with no extra server. The fastest way to start. MCP connects Familiar to external clients (Claude Desktop, Codex CLI, ChatGPT, Gemini) through a local server, letting you use existing subscriptions and handling complex multi-step tasks better. Both have access to the same 188 tools.
232
272
 
233
273
  </details>
234
274
 
235
275
  <details>
236
276
  <summary><b>Which AI models work best?</b></summary>
237
277
 
238
- For the best experience: Claude Opus 4.6 or Sonnet 4.6 (Anthropic), GPT-5.4 (OpenAI), Gemini 3.1 Pro (Google), Grok 4 (xAI), Mistral 3 (Mistral), or DeepSeek V3.2 (DeepSeek).
278
+ For the best experience: Claude Opus 4.7 or Sonnet 4.6 (Anthropic), GPT-5.5 (OpenAI), Gemini 3.1 Pro (Google), Grok 4.3 (xAI), Mistral Large 3 (Mistral), or DeepSeek V3.2 (DeepSeek).
239
279
 
240
280
  </details>
241
281
 
242
282
  <details>
243
283
  <summary><b>Can I use this for solo play?</b></summary>
244
284
 
245
- Absolutely, solo and small-group play is one of the main use cases. I built Familiar for 1-on-1 D&D campaigns with my wife. The AI can run NPCs, manage encounters, describe scenes, and help with rulings so you can play without a dedicated DM.
285
+ Absolutely. Solo and small-group play is one of the main use cases. I built Familiar for 1-on-1 D&D campaigns with my wife. The AI can run NPCs, manage encounters, describe scenes, and help with rulings so you can play without a dedicated DM.
286
+
287
+ </details>
288
+
289
+ <details>
290
+ <summary><b>Can I use Familiar as a player (not a GM)?</b></summary>
291
+
292
+ Familiar requires GM permissions. It's 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.
246
293
 
247
294
  </details>
248
295
 
249
296
  <details>
250
297
  <summary><b>Does it work with game systems other than D&D 5e?</b></summary>
251
298
 
252
- Familiar is designed and tested for D&D 5e (2024 rules) on Foundry VTT. Basic features like dice rolling, scene management, and journal editing work with other systems, but system-specific tools (character creation, spell resolution, combat automation) are built around the dnd5e data model and are not officially supported elsewhere.
299
+ Familiar is designed and tested for D&D 5e (2024 rules). Basic features like dice rolling, scene management, and journal editing work with other systems, but system-specific tools (character creation, spell resolution, combat automation) are built around the dnd5e data model and won't work elsewhere without changes.
253
300
 
254
301
  </details>
255
302
 
256
303
  <details>
257
304
  <summary><b>Will Familiar conflict with my other Foundry modules?</b></summary>
258
305
 
259
- No. Familiar operates through its own namespaced flags and does not monkey-patch or override core Foundry functionality. It works alongside any other module you have installed.
306
+ No. Familiar operates through its own namespaced flags and doesn't monkey-patch or override core Foundry functionality. It works alongside any other module you have installed.
260
307
 
261
308
  </details>
262
309
 
@@ -266,37 +313,19 @@ Things I'm actively working toward. No promises on timelines.
266
313
 
267
314
  ### Module Integrations
268
315
 
269
- Let the AI control the most popular Foundry modules, automated rolls, visual effects, animations, loot, and more.
316
+ Let the AI control the most popular Foundry modules: automated rolls, visual effects, animations, loot, and more.
270
317
 
271
318
  | Module | What Familiar will do with it |
272
319
  |--------|-------------------------------|
273
320
  | Midi-QOL | Automated attack rolls, saving throws, and damage application |
274
- | Sequencer | Orchestrate animation sequences and visual storytelling |
275
- | JB2A (Animated Assets) | Trigger spell effects, explosions, and environmental animations |
276
- | Automated Animations | Auto-apply JB2A effects to spells and abilities |
321
+ | Sequencer + JB2A | Orchestrate animation sequences and trigger spell effects |
277
322
  | Token Magic FX | Apply shader effects to tokens and tiles (fire auras, glowing shields) |
278
- | Dice So Nice | Sync 3D dice rolls with AI-triggered actions |
279
323
  | Item Piles | Create and manage loot drops, merchants, and treasure hoards |
280
- | Monk's Active Tile Triggers | Set up interactive tiles (traps, doors, teleporters) by voice |
281
- | Tidy 5e Sheets | Read and update the enhanced character sheet layout |
282
324
  | DFreds Convenient Effects | Apply and manage curated status effects and buffs |
283
325
 
284
326
  ### Ready-to-Play Adventures
285
327
 
286
- 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.
287
-
288
- | Adventure | Publisher |
289
- |-----------|-----------|
290
- | Ember | Foundry VTT |
291
- | Curse of Strahd | Wizards of the Coast |
292
- | Phandelver and Below: The Shattered Obelisk | Wizards of the Coast |
293
- | Tomb of Annihilation | Wizards of the Coast |
294
- | Waterdeep: Dragon Heist | Wizards of the Coast |
295
- | Storm King's Thunder | Wizards of the Coast |
296
- | Ghosts of Saltmarsh | Wizards of the Coast |
297
- | Descent into Avernus | Wizards of the Coast |
298
- | Rime of the Frostmaiden | Wizards of the Coast |
299
- | Crown of the Oathbreaker | Elderbrain |
328
+ 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.
300
329
 
301
330
  ### Game System Support
302
331
 
@@ -308,30 +337,21 @@ Expanding beyond D&D 5e with full system-specific tools (character sheets, comba
308
337
  | Pathfinder 2e | Planned |
309
338
  | Call of Cthulhu | Planned |
310
339
  | Savage Worlds | Planned |
311
- | Warhammer Fantasy Roleplay | Planned |
312
340
 
313
341
  ### Improvements
314
342
 
315
- - **Voice generation**: more natural NPC voices, emotion control, multi-voice conversations
316
- - **Image generation**: faster scene art, consistent character portraits across sessions, style presets
317
- - **Transcription**: improved accuracy, real-time command detection, multi-language support
318
- - **Combat AI**: smarter NPC tactics, group coordination, retreat behavior, morale
319
- - **Built-in chat**: conversation memory across sessions, campaign knowledge base, auto-summarization
320
- - **MCP**: faster tool execution, better multi-step task handling, richer feedback to clients
321
-
322
- ### Bug Fixes & Stability
323
-
324
- Active bug triage through the [Discord](https://discord.gg/3633wB9yp). Foundry version compatibility (v13, v14, and future releases) is always a priority.
343
+ - **Combat AI**: retreat behavior, morale, group coordination beyond what shipped
344
+ - **Voice generation**: emotion control, more natural multi-voice conversations
345
+ - **Image generation**: consistent character portraits across sessions, style presets
346
+ - **MCP**: richer `notifications/message` feedback so external clients see tool progress in real time
325
347
 
326
348
  ## Feedback
327
349
 
328
- 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:
329
-
330
- - Join the [Discord](https://discord.gg/3633wB9yp)
350
+ Join the [Discord](https://discord.gg/pN6pEvYH) for bug reports, feature ideas, or just tell me about the weird thing the AI did to your goblin encounter.
331
351
 
332
352
  ## License
333
353
 
334
- 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.
354
+ 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.
335
355
 
336
356
  <div align="center">
337
357