familiar-vtt 2.9.0 → 2.11.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.
- package/README.md +146 -55
- package/dist/mcp-package/index.mjs +38 -32
- package/package.json +23 -22
package/README.md
CHANGED
|
@@ -4,34 +4,55 @@
|
|
|
4
4
|
|
|
5
5
|
### Your AI co-pilot for Foundry VTT
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**191 tools. 25 AI providers. Zero prep.**
|
|
8
8
|
|
|
9
9
|
Run combat, set the mood, and voice your NPCs, all by talking to your AI.
|
|
10
10
|
|
|
11
|
+
**It runs the rules, the dice, and the monsters, so you can stop running the game and start playing it — even solo.**
|
|
12
|
+
|
|
11
13
|
[](https://foundryvtt.com)
|
|
12
14
|
[](https://www.npmjs.com/package/familiar-vtt)
|
|
13
15
|
[](https://discord.gg/pN6pEvYH)
|
|
14
16
|
[](#license)
|
|
15
17
|
|
|
16
|
-
[
|
|
18
|
+
**[Install Familiar](#installation)** · [Connect your AI](#connect-your-ai) · [Pricing](#pricing) · [FAQ](#faq) · [Roadmap](#roadmap)
|
|
17
19
|
|
|
18
20
|
</div>
|
|
19
21
|
|
|
22
|
+
<!-- TODO(media): hero GIF here — the flagship line running live ("roll initiative for the goblins, dim the lights, start battle music" → tracker fills, scene darkens, music cues, all from one chat message). Capture via docs/RECORDING.md (OBS + obs-mcp). Host in familiar-releases (docs/media/) and reference by a raw.githubusercontent.com URL so it also renders on the npm page. Keep ≤10 MB GIF for GitHub. -->
|
|
23
|
+
|
|
24
|
+
## Plays at any table
|
|
25
|
+
|
|
26
|
+
You bought Foundry to run the game for everyone else. Familiar lets you finally **play** — in the world you already built. It takes the DM's side of the table: the rules, the dice, the monsters, and every NPC in their own voice, so you can take a seat at your own game instead of always running it.
|
|
27
|
+
|
|
28
|
+
And it scales to whoever shows up. The fewer humans at the table, the more of the world Familiar runs; with a full group, it quietly co-pilots the monsters and the mood while you tell the story.
|
|
29
|
+
|
|
30
|
+
| Your table | What Familiar runs for you |
|
|
31
|
+
|---|---|
|
|
32
|
+
| **Solo** — just you | Every NPC, every monster's turn, the scene, and the rules — with 2024 D&D enforced for real and a memory of your campaign that carries from one session to the next. You play your character; Familiar runs the world around it. |
|
|
33
|
+
| **Duet** — you and one other | Neither of you has to be the DM. Familiar plays the cast and runs the encounters, each NPC in their own voice, so you both stay players in the story. |
|
|
34
|
+
| **Small table** — you and a few | The supporting cast and the monsters' turns, run for you — the lighting, the music, the rulings — so nobody has to step out of the game to keep it moving. |
|
|
35
|
+
| **Full group** — you DM for four or more | The tactical NPC load, lifted off the GM. You run the encounter, not the spreadsheet — Familiar rolls initiative, plays the monsters, voices the NPCs, and gets out of the way. |
|
|
36
|
+
|
|
37
|
+
A co-pilot, not a replacement DM. Whoever's at the table, you're still the one telling the story — and the dice and the math are always right, no "you rolled a 47."
|
|
38
|
+
|
|
20
39
|
## What can Familiar do?
|
|
21
40
|
|
|
22
|
-
|
|
41
|
+
You stay in the story; Familiar runs the table. Say what you want and it happens, without breaking character to dig through menus:
|
|
23
42
|
|
|
24
|
-
> "Roll initiative for all the goblins, have them attack the nearest player, and
|
|
43
|
+
> "Roll initiative for all the goblins, have them attack the nearest player, and cue battle music."
|
|
25
44
|
|
|
26
|
-
> "
|
|
45
|
+
> "I swing at the bandit captain with my greataxe — roll my attack, and have her hit back."
|
|
27
46
|
|
|
28
47
|
> "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead, in his voice."
|
|
29
48
|
|
|
30
|
-
> "
|
|
49
|
+
> "Spawn two wolves from the compendium near the forest edge as reinforcements, and add them to combat with initiative rolled."
|
|
31
50
|
|
|
32
|
-
> "
|
|
51
|
+
> "What did the party promise the duke last session, and what was his daughter's name?"
|
|
33
52
|
|
|
34
|
-
|
|
53
|
+
> "We're done for tonight. Summarize what happened and save it to the journal."
|
|
54
|
+
|
|
55
|
+
Familiar exposes **191 tools across 24 domains** through the Model Context Protocol. Tools load as your AI needs them.
|
|
35
56
|
|
|
36
57
|
### Highlights
|
|
37
58
|
|
|
@@ -41,7 +62,7 @@ Familiar exposes **188 tools across 24 domains** through the Model Context Proto
|
|
|
41
62
|
|
|
42
63
|
**Combat & AI**
|
|
43
64
|
|
|
44
|
-
|
|
65
|
+
31 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.
|
|
45
66
|
|
|
46
67
|
</td>
|
|
47
68
|
<td width="33%" valign="top">
|
|
@@ -55,7 +76,7 @@ Click "Run NPC" and walk away. Familiar plays every enemy turn in the encounter
|
|
|
55
76
|
|
|
56
77
|
**Live Transcription**
|
|
57
78
|
|
|
58
|
-
Speak instead of type. Familiar transcribes your session in real time across three providers, color-codes per speaker, and saves
|
|
79
|
+
Speak instead of type. Familiar transcribes your session in real time across three providers, color-codes per speaker, and saves it to a Foundry journal. Broadcast a read-only transcript to your players, export to SRT or Markdown, and the AI remembers what was said.
|
|
59
80
|
|
|
60
81
|
</td>
|
|
61
82
|
</tr>
|
|
@@ -71,7 +92,7 @@ Create scenes, place tokens, draw walls and doors, set lighting and darkness, ad
|
|
|
71
92
|
|
|
72
93
|
**Voice & Image Generation**
|
|
73
94
|
|
|
74
|
-
Assign unique AI voices to NPCs across
|
|
95
|
+
Assign unique AI voices to NPCs across three 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.
|
|
75
96
|
|
|
76
97
|
</td>
|
|
77
98
|
<td width="33%" valign="top">
|
|
@@ -87,7 +108,7 @@ Play, stop, and crossfade playlists and individual tracks with volume and fade c
|
|
|
87
108
|
|
|
88
109
|
**Knowledge & Memory**
|
|
89
110
|
|
|
90
|
-
|
|
111
|
+
Full-text search across every journal, character, scene, item, and recorded transcript. A persistent memory bank stores campaign facts that carry over between sessions, plus a continuously-rewritten plot summary the GM can read later.
|
|
91
112
|
|
|
92
113
|
</td>
|
|
93
114
|
<td width="33%" valign="top">
|
|
@@ -116,10 +137,10 @@ Build NPCs, manage party inventory, apply buffs, and clone monsters from any com
|
|
|
116
137
|
| **Canvas Environment** | 18 | Walls, lights, weather effects, fog of war, darkness levels |
|
|
117
138
|
| **Combat & Initiative** | 17 | Start encounters, roll initiative, advance turns and rounds |
|
|
118
139
|
| **Characters & Actors** | 16 | Create, inspect, update, and manage player characters and NPCs |
|
|
140
|
+
| **Combat AI** | 14 | NPC tactical decisions, target selection, ability usage, positioning |
|
|
119
141
|
| **Audio & Playlists** | 14 | Play, stop, and crossfade music and ambient sound |
|
|
120
|
-
| **Combat AI** | 12 | NPC tactical decisions, target selection, ability usage, positioning |
|
|
121
142
|
| **Journals & Notes** | 10 | Create and edit journal entries, map pins, and handouts |
|
|
122
|
-
| **Card Decks** | 9 |
|
|
143
|
+
| **Card Decks** | 9 | Create, draw, shuffle, and reset card stacks and decks |
|
|
123
144
|
| **Canvas Drawing** | 8 | Draw shapes, text, and freehand annotations on the canvas |
|
|
124
145
|
| **Rollable Tables** | 7 | Create tables and roll on them for random encounters or loot |
|
|
125
146
|
| **Macros** | 7 | Create, edit, and execute Foundry macros |
|
|
@@ -135,33 +156,30 @@ Build NPCs, manage party inventory, apply buffs, and clone monsters from any com
|
|
|
135
156
|
| **Chat Messages** | 2 | Send and read chat messages in the Foundry sidebar |
|
|
136
157
|
| **Dice** | 1 | Roll any dice expression with full Foundry roll parsing |
|
|
137
158
|
| **Image Generation** | 1 | Generate scene art or character portraits on demand |
|
|
138
|
-
| **Scene Generator** |
|
|
159
|
+
| **Scene Generator** | 2 | Generate AI battle-map backgrounds from a text description (image only, no walls or tokens) |
|
|
139
160
|
|
|
140
161
|
</details>
|
|
141
162
|
|
|
142
|
-
##
|
|
163
|
+
## Installation
|
|
143
164
|
|
|
144
|
-
|
|
165
|
+
Familiar installs like any other Foundry module.
|
|
145
166
|
|
|
146
|
-
|
|
167
|
+
1. In Foundry, open **Add-on Modules → Install Module**.
|
|
168
|
+
2. Paste this manifest URL and click Install:
|
|
147
169
|
|
|
148
|
-
|
|
170
|
+
```
|
|
171
|
+
https://github.com/Ryanjansen92/familiar-releases/releases/latest/download/module.json
|
|
172
|
+
```
|
|
149
173
|
|
|
150
|
-
|
|
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.
|
|
174
|
+
3. Enable Familiar in your world, open its settings, pick a provider, and paste an API key.
|
|
153
175
|
|
|
154
|
-
|
|
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:
|
|
176
|
+
That is the whole setup for the built-in chat. If you would rather drive your game from an MCP client (Claude Desktop, Claude Code, Codex CLI / Desktop, Antigravity CLI / Editor, Gemini CLI, or ChatGPT), you also need the local MCP server:
|
|
159
177
|
|
|
160
178
|
```sh
|
|
161
179
|
npx familiar-vtt
|
|
162
180
|
```
|
|
163
181
|
|
|
164
|
-
The **MCP Setup Wizard** in Module Settings → Familiar walks you through connecting your client step by step
|
|
182
|
+
The **MCP Setup Wizard** in Module Settings → Familiar walks you through connecting your client step by step, including the auto-generated `FAMILIAR_WS_SECRET`. No JSON editing.
|
|
165
183
|
|
|
166
184
|
### Compatibility
|
|
167
185
|
|
|
@@ -172,58 +190,98 @@ The **MCP Setup Wizard** in Module Settings → Familiar walks you through conne
|
|
|
172
190
|
|
|
173
191
|
## Connect your AI
|
|
174
192
|
|
|
175
|
-
There are two ways to connect an AI to your game. Both
|
|
193
|
+
There are two ways to connect an AI to your game. Both reach the same 191 tools. The difference is where the model runs and how you pay.
|
|
176
194
|
|
|
177
195
|
### Option 1: Built-in chat (API key)
|
|
178
196
|
|
|
179
197
|
No server. No terminal. No config files. Install the module, pick a provider, paste an API key, and start talking.
|
|
180
198
|
|
|
181
|
-
Familiar connects directly to **
|
|
199
|
+
Familiar connects directly to **25 AI providers** across four categories:
|
|
182
200
|
|
|
183
201
|
| Category | Providers |
|
|
184
202
|
|----------|-----------|
|
|
185
203
|
| **Chat** (16) | OpenRouter¹, Anthropic, OpenAI, Google, Groq, Mistral, Together AI, DeepSeek, xAI, Cohere, Perplexity, Fireworks AI, Cerebras, SambaNova, Ollama (local), LM Studio (local) |
|
|
186
|
-
| **Voice** (
|
|
204
|
+
| **Voice** (3) | ElevenLabs, Cartesia, OpenAI TTS |
|
|
187
205
|
| **Image** (3) | OpenAI (GPT Image), fal.ai, Leonardo AI |
|
|
188
206
|
| **Transcription** (3) | Gladia, Deepgram, AssemblyAI |
|
|
189
207
|
|
|
190
208
|
¹ *OpenRouter unlocks 300+ models on a single key.*
|
|
191
209
|
|
|
192
|
-
This is the right choice if you want the simplest setup, or if you want voice, images, and live transcription alongside chat. It
|
|
210
|
+
This is the right choice if you want the simplest setup, or if you want voice, images, and live transcription alongside chat. It is also the only option that supports local models (Ollama, LM Studio) for fully offline play.
|
|
193
211
|
|
|
194
212
|
### Option 2: MCP (your existing subscription)
|
|
195
213
|
|
|
196
|
-
Already paying for Claude, ChatGPT/Codex, or
|
|
214
|
+
Already paying for Claude, ChatGPT/Codex, Gemini, or have a Google account for Antigravity? 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.
|
|
197
215
|
|
|
198
|
-
Familiar supports
|
|
216
|
+
Familiar supports eight MCP clients out of the box:
|
|
199
217
|
|
|
200
|
-
| Client | Transport | Setup |
|
|
201
|
-
|
|
202
|
-
| Claude Desktop | stdio | Add to `claude_desktop_config.json` with `env: { FAMILIAR_WS_SECRET }` |
|
|
203
|
-
| Claude Code (CLI) | stdio | `claude mcp add --env FAMILIAR_WS_SECRET=… familiar -- npx familiar-vtt` |
|
|
204
|
-
| Codex CLI | stdio | `codex mcp add familiar --env FAMILIAR_WS_SECRET=… -- npx -y familiar-vtt` |
|
|
205
|
-
| Codex Desktop | stdio | Add `[mcp_servers.familiar]` block to `~/.codex/config.toml` (shared with CLI / IDE) |
|
|
206
|
-
|
|
|
207
|
-
|
|
|
218
|
+
| Client | Subscription | Transport | Setup |
|
|
219
|
+
|--------|-------------|-----------|-------|
|
|
220
|
+
| Claude Desktop | Anthropic Pro / Max / Team | stdio | Add to `claude_desktop_config.json` with `env: { FAMILIAR_WS_SECRET }` |
|
|
221
|
+
| Claude Code (CLI) | Anthropic Pro / Max / Team | stdio | `claude mcp add --scope user --env FAMILIAR_WS_SECRET=… familiar -- npx familiar-vtt` |
|
|
222
|
+
| Codex CLI | ChatGPT Plus / Pro / Team | stdio | `codex mcp add familiar --env FAMILIAR_WS_SECRET=… -- npx -y familiar-vtt` |
|
|
223
|
+
| Codex Desktop | ChatGPT Plus / Pro / Team | stdio | Add `[mcp_servers.familiar]` block to `~/.codex/config.toml` (shared with CLI / IDE) |
|
|
224
|
+
| Antigravity CLI (`agy`) | Google free / Pro / Ultra | stdio | Generates `~/.gemini/config/mcp_config.json`; sign in via `agy` → Google OAuth |
|
|
225
|
+
| Antigravity Editor | Google free / Pro / Ultra | stdio | Add to `~/.gemini/antigravity/mcp_config.json` (desktop IDE; separate install from CLI) |
|
|
226
|
+
| Gemini CLI ¹ | Google | stdio | Add to MCP settings with the `env` block |
|
|
227
|
+
| ChatGPT | ChatGPT Plus / Pro / Team | Streamable HTTP | Remote URL via Cloudflare tunnel |
|
|
208
228
|
|
|
209
|
-
|
|
229
|
+
¹ *Gemini CLI is deprecated by Google on 2026-06-18 — use Antigravity CLI instead.*
|
|
230
|
+
|
|
231
|
+
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, including the auto-generated `FAMILIAR_WS_SECRET` baked in. Copy and paste.
|
|
210
232
|
|
|
211
233
|
### Which should I pick?
|
|
212
234
|
|
|
213
235
|
| I want to... | Use |
|
|
214
236
|
|--------------|-----|
|
|
215
237
|
| Get started in under a minute | **Built-in chat** with any API key |
|
|
216
|
-
| Use my Claude/ChatGPT/Codex/Gemini subscription | **MCP** |
|
|
238
|
+
| Use my Claude / ChatGPT / Codex / Gemini / Antigravity subscription | **MCP** |
|
|
217
239
|
| Run everything offline | **Built-in chat** with Ollama or LM Studio |
|
|
218
|
-
| Have voice, images, and transcription | **Built-in chat** (MCP
|
|
240
|
+
| Have voice, images, and transcription | **Built-in chat** (over MCP, media renders in Foundry — see below) |
|
|
219
241
|
| Run complex multi-step tasks | **MCP** (external clients handle long chains better) |
|
|
220
242
|
|
|
243
|
+
### What's different between the two paths
|
|
244
|
+
|
|
245
|
+
All 191 tools work from both paths. Two things differ:
|
|
246
|
+
|
|
247
|
+
- **Media renders in Foundry, not in your MCP client.** When an external client (ChatGPT, Claude Desktop, Codex) calls a voice or scene tool, the audio plays and the scene updates in your Foundry browser tab. The MCP client only gets a text confirmation. Generated images are the exception: they come back inline, so clients that render images can show them.
|
|
248
|
+
- **A few features are built-in-chat only.** Live transcription, auto-pilot for NPC turns, automatic memory and knowledge-base context, slash commands, and drag-and-drop attachments live only in the in-Foundry chat window. MCP clients reach every tool, but not these chat-UI features.
|
|
249
|
+
|
|
250
|
+
A full surface-by-surface capability matrix lives in [docs/chat-vs-mcp.md](docs/chat-vs-mcp.md).
|
|
251
|
+
|
|
221
252
|
## Works with what you already have
|
|
222
253
|
|
|
223
254
|
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.
|
|
224
255
|
|
|
225
256
|
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.
|
|
226
257
|
|
|
258
|
+
Here's the part that's harder than it looks. Bolting a chat box onto a virtual tabletop is a weekend project. The real work is the engine underneath: teaching the AI how a real table actually operates — how initiative and reactions resolve, what a spell does to which token, when a saving throw is forced, why you can't swing a melee weapon from thirty feet away. Most AI tabletop tools skip that and rebuild a thin, simplified game inside their own walled garden, inventing the rules as they go. Familiar runs on the real thing, with real dice and real 5e enforcement on the mechanics that matter, on top of a decade of Foundry content. It operates your table instead of faking one.
|
|
259
|
+
|
|
260
|
+
So the on-ramp is short. Buy a Foundry-ready adventure — official D&D modules run about $20–30, with the maps, walls, and lighting already built — drop in a battle map or two (plenty are free), enable Familiar, and you're playing. Import the adventure without reading it, and Familiar reads its journals so it knows the story you're about to discover. Then, as you play, it pulls monsters and items straight from your compendia, places the tokens, and runs the encounters — while you stay the player.
|
|
261
|
+
|
|
262
|
+
## Pricing
|
|
263
|
+
|
|
264
|
+
**$3 a month, or $25 a year.** Start with a free 1-month trial: every feature unlocked, no restrictions, cancel anytime.
|
|
265
|
+
|
|
266
|
+
That price is the whole cost of Familiar. No per-message fee, no token metering, no credits to top up.
|
|
267
|
+
|
|
268
|
+
### Do I pay twice?
|
|
269
|
+
|
|
270
|
+
Fair question. You pay for Familiar, and you pay for the AI that powers it, but never to us and never marked up. Here is how it breaks down:
|
|
271
|
+
|
|
272
|
+
| What you pay for | Who you pay | Typical cost |
|
|
273
|
+
|---|---|---|
|
|
274
|
+
| Familiar (the module + all 191 tools) | Us | $3 / month or $25 / year |
|
|
275
|
+
| The AI itself | Your provider, directly | $0.50–$3 per session, or $0 |
|
|
276
|
+
|
|
277
|
+
That $0 is real. If you connect a subscription you already pay for (Claude, ChatGPT/Codex, Gemini, Antigravity) through MCP, the AI cost is already covered. The same goes for local models through Ollama or LM Studio: nothing leaves your machine, and nothing hits a bill. Bring your own API key instead, and a typical session costs about the price of a coffee, paid straight to the provider.
|
|
278
|
+
|
|
279
|
+
### Your keys, your cost
|
|
280
|
+
|
|
281
|
+
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.
|
|
282
|
+
|
|
283
|
+
Familiar works differently. You bring your own AI, an API key you already have or a subscription to Claude, ChatGPT/Codex, or Gemini. Your keys go straight from your browser to the provider. Familiar never proxies, meters, or marks up your usage: no middleman, no per-turn limits, no credits to run out of. With MCP, your existing subscription handles it.
|
|
284
|
+
|
|
227
285
|
## Why I built this
|
|
228
286
|
|
|
229
287
|
I'm Ryan. Dad of two young kids, married to my favorite person, with the free time you'd expect.
|
|
@@ -232,7 +290,7 @@ My wife and I play D&D together, just the two of us, 1-on-1 campaigns. It's our
|
|
|
232
290
|
|
|
233
291
|
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.
|
|
234
292
|
|
|
235
|
-
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
|
|
293
|
+
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 here.
|
|
236
294
|
|
|
237
295
|
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.
|
|
238
296
|
|
|
@@ -241,21 +299,42 @@ It started as a personal itch-scratcher for a dad who wanted to run better D&D g
|
|
|
241
299
|
<details>
|
|
242
300
|
<summary><b>Does Familiar collect my data?</b></summary>
|
|
243
301
|
|
|
244
|
-
No. There's no telemetry
|
|
302
|
+
No. There's no telemetry and no analytics, and Familiar never collects your game data. It runs entirely inside your local Foundry instance, and 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. (In MCP mode, the server validates your license with Polar; that request carries only your license key, never any world content.)
|
|
303
|
+
|
|
304
|
+
</details>
|
|
305
|
+
|
|
306
|
+
<details>
|
|
307
|
+
<summary><b>How hard is it to set up?</b></summary>
|
|
308
|
+
|
|
309
|
+
For the built-in chat, about as easy as it gets: install the module, open Familiar's settings, pick a provider, paste an API key, and start talking. No terminal, no config files. If you'd rather use an existing Claude, ChatGPT, or Gemini subscription through MCP, there's one extra piece, a small local server you start with `npx familiar-vtt`, and the in-app MCP Setup Wizard detects your client and generates the exact config to copy and paste.
|
|
245
310
|
|
|
246
311
|
</details>
|
|
247
312
|
|
|
248
313
|
<details>
|
|
249
314
|
<summary><b>Can the AI break my world?</b></summary>
|
|
250
315
|
|
|
251
|
-
Familiar sanitizes
|
|
316
|
+
Familiar sanitizes every document update, so the AI can't change ownership, permissions, or internal IDs. Prototype-pollution protection is built in, and WebSocket connections use shared-secret authentication. Risky actions are flagged for confirmation: the built-in chat shows an inline approval row before running them, and external AI clients receive the same "destructive" hints so they can prompt you. The AI also can't create or edit script macros or code-running region behaviors, even though it can run ones you wrote yourself. Always keep backups regardless. Good practice with or without AI.
|
|
317
|
+
|
|
318
|
+
</details>
|
|
319
|
+
|
|
320
|
+
<details>
|
|
321
|
+
<summary><b>How does the free trial work, and will I be charged automatically?</b></summary>
|
|
322
|
+
|
|
323
|
+
The trial is a full month with every feature unlocked, no restrictions. Billing runs through Polar. Cancel any time before the month is up and you won't be charged. If you do cancel, Familiar simply stops running new AI tool calls once the license check lapses; everything the AI already created stays in your Foundry world, untouched.
|
|
252
324
|
|
|
253
325
|
</details>
|
|
254
326
|
|
|
255
327
|
<details>
|
|
256
328
|
<summary><b>What happens to my data if I cancel?</b></summary>
|
|
257
329
|
|
|
258
|
-
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
|
|
330
|
+
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 lapses, but nothing the AI already created gets touched.
|
|
331
|
+
|
|
332
|
+
</details>
|
|
333
|
+
|
|
334
|
+
<details>
|
|
335
|
+
<summary><b>Will Familiar slow down my Foundry or cause lag?</b></summary>
|
|
336
|
+
|
|
337
|
+
No meaningful impact on Foundry's frame rate. The chat window is a plain DOM panel; it doesn't touch the canvas renderer, so it doesn't add to the per-token rendering cost that bogs down big battles. The AI's tool calls run the same Foundry operations you'd do by hand, just triggered by text. The only thing that takes a moment is the AI itself thinking and streaming its reply, which happens on the provider's side, not in your game.
|
|
259
338
|
|
|
260
339
|
</details>
|
|
261
340
|
|
|
@@ -269,21 +348,23 @@ Built-in chat works anywhere Foundry runs, including The Forge. The module makes
|
|
|
269
348
|
<details>
|
|
270
349
|
<summary><b>What's the difference between MCP mode and built-in chat?</b></summary>
|
|
271
350
|
|
|
272
|
-
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
|
|
351
|
+
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 / Desktop, Antigravity CLI / Editor, ChatGPT, Gemini) through a local server, letting you use existing subscriptions and handling complex multi-step tasks better. Both reach the same 191 tools, though media (voice, scenes) renders in your Foundry tab rather than the MCP client.
|
|
273
352
|
|
|
274
353
|
</details>
|
|
275
354
|
|
|
276
355
|
<details>
|
|
277
356
|
<summary><b>Which AI models work best?</b></summary>
|
|
278
357
|
|
|
279
|
-
For the best experience: Claude Opus 4.
|
|
358
|
+
For the best experience: Claude Opus 4.8 or Sonnet 4.7 (Anthropic), GPT-5.5 (OpenAI), Gemini 3.1 Pro (Google), Grok 4.3 (xAI), Mistral Large 3 (Mistral), or DeepSeek V3.2 (DeepSeek). Familiar works with any model these providers expose, but the larger flagship models follow multi-step tool instructions most reliably. For a budget option, DeepSeek V3.2 is capable and inexpensive; for fully offline play, any strong local model through Ollama or LM Studio works.
|
|
280
359
|
|
|
281
360
|
</details>
|
|
282
361
|
|
|
283
362
|
<details>
|
|
284
|
-
<summary><b>Can I
|
|
363
|
+
<summary><b>Can I play solo, or one-on-one?</b></summary>
|
|
285
364
|
|
|
286
|
-
|
|
365
|
+
That's one of the main reasons it exists. Most people who own Foundry are the GM — the one who never gets to play. Familiar runs the rules, the monsters, and the NPCs so you can sit in a player's seat at your own table, solo or one-on-one. I built it for 1-on-1 campaigns with my wife. (It still needs GM-level access — see the next question.)
|
|
366
|
+
|
|
367
|
+
Two honest notes. Familiar runs the _DM's_ side — it doesn't yet play a companion character adventuring next to you (that's on the roadmap). And the surprises come from the adventure you're playing and Foundry's own fog-of-war and hidden doors, not from the AI "keeping secrets" — an AI can't truly hide what it can read. What it can do is run a real, rules-accurate game so you finally get to be the player.
|
|
287
368
|
|
|
288
369
|
</details>
|
|
289
370
|
|
|
@@ -338,6 +419,14 @@ Expanding beyond D&D 5e with full system-specific tools (character sheets, comba
|
|
|
338
419
|
| Call of Cthulhu | Planned |
|
|
339
420
|
| Savage Worlds | Planned |
|
|
340
421
|
|
|
422
|
+
### Solo & duet play
|
|
423
|
+
|
|
424
|
+
Sharpening Familiar for the player who runs the table for everyone else and wants to play for once, solo or one-on-one. Full plan in [docs/solo-play.md](docs/solo-play.md).
|
|
425
|
+
|
|
426
|
+
- **Companion party-fill**: let the AI run a designated ally's combat turns, so one hero against four goblins is a fight again, not a mugging
|
|
427
|
+
- **Encounter scaling for one PC**: balance a fight for a solo or duet party
|
|
428
|
+
- **Solo mode**: a one-click preset that puts the AI on the rules, the monsters, and the NPC voices so you can sit in a player's seat at your own table
|
|
429
|
+
|
|
341
430
|
### Improvements
|
|
342
431
|
|
|
343
432
|
- **Combat AI**: retreat behavior, morale, group coordination beyond what shipped
|
|
@@ -351,11 +440,13 @@ Join the [Discord](https://discord.gg/pN6pEvYH) for bug reports, feature ideas,
|
|
|
351
440
|
|
|
352
441
|
## License
|
|
353
442
|
|
|
354
|
-
Familiar is licensed under the [PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/)
|
|
443
|
+
Familiar is licensed under the [PolyForm Shield License 1.0.0](https://polyformproject.org/licenses/shield/1.0.0/): you can use and self-host it for any purpose except building a competing product. It ships as a compiled build, and the source repository is private. See [LICENSE](https://github.com/Ryanjansen92/familiar-releases/blob/main/LICENSE) for the full text.
|
|
355
444
|
|
|
356
445
|
<div align="center">
|
|
357
446
|
|
|
358
|
-
Built for the DM who has more ideas than free time.
|
|
447
|
+
Built for the DM who has more ideas than free time — and wouldn't mind playing for once.
|
|
448
|
+
|
|
449
|
+
**[Install Familiar — free for a month](#installation)**
|
|
359
450
|
|
|
360
451
|
*May your rolls be high, your prep be low, and your players never notice the AI is helping.*
|
|
361
452
|
|