familiar-vtt 2.5.16 → 2.5.18
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/LICENSE +158 -6
- package/README.md +193 -141
- package/package.json +1 -1
package/LICENSE
CHANGED
|
@@ -1,8 +1,160 @@
|
|
|
1
|
-
|
|
1
|
+
PolyForm Shield License 1.0.0
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
and confidential. Unauthorized copying, distribution, modification, or use of this
|
|
5
|
-
Software, via any medium, is strictly prohibited without prior written permission
|
|
6
|
-
from the copyright holder.
|
|
3
|
+
Copyright (c) 2026 Ryan Jansen
|
|
7
4
|
|
|
8
|
-
|
|
5
|
+
https://polyformproject.org/licenses/shield/1.0.0/
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
Acceptance
|
|
9
|
+
|
|
10
|
+
In order to get any license under these terms, you must agree to them
|
|
11
|
+
as both strict obligations and conditions to all your licenses.
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
Copyright License
|
|
15
|
+
|
|
16
|
+
The licensor grants you a copyright license for the software to do
|
|
17
|
+
everything you might do with the software that would otherwise infringe
|
|
18
|
+
the licensor's copyright in it for any permitted purpose. However, you
|
|
19
|
+
may only distribute the software according to Distribution License and
|
|
20
|
+
make changes or new works based on the software according to Changes
|
|
21
|
+
and New Works License.
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
Distribution License
|
|
25
|
+
|
|
26
|
+
The licensor grants you an additional copyright license to distribute
|
|
27
|
+
copies of the software. Your license to distribute covers distributing
|
|
28
|
+
the software with changes and new works permitted by Changes and New
|
|
29
|
+
Works License.
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
Notices
|
|
33
|
+
|
|
34
|
+
You must ensure that anyone who gets a copy of any part of the software
|
|
35
|
+
from you also gets a copy of these terms or the URL for them above, as
|
|
36
|
+
well as copies of any plain-text lines beginning with "Required Notice:"
|
|
37
|
+
that the licensor provided with the software.
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
Changes and New Works License
|
|
41
|
+
|
|
42
|
+
The licensor grants you an additional copyright license to make changes
|
|
43
|
+
and new works based on the software for any permitted purpose.
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
Patent License
|
|
47
|
+
|
|
48
|
+
The licensor grants you a patent license for the software that covers
|
|
49
|
+
patent claims the licensor can license, or becomes able to license, that
|
|
50
|
+
you would infringe by using the software.
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
Noncompete
|
|
54
|
+
|
|
55
|
+
Any purpose is a permitted purpose, except for providing any product
|
|
56
|
+
that competes with the software or any product the licensor or any of
|
|
57
|
+
its affiliates provides using the software.
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
Competition
|
|
61
|
+
|
|
62
|
+
Goods and services compete even when they provide functionality through
|
|
63
|
+
different kinds of interfaces or for different technical platforms.
|
|
64
|
+
Applications can compete with services, libraries with plugins,
|
|
65
|
+
frameworks with development tools, and so on, even if they're written in
|
|
66
|
+
different programming languages or for different computer architectures.
|
|
67
|
+
Goods and services compete even when provided free of charge. If you
|
|
68
|
+
market a product as a practical substitute for the software or another
|
|
69
|
+
product, it definitely competes.
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
New Products
|
|
73
|
+
|
|
74
|
+
If you are using the software to provide a product that does not compete,
|
|
75
|
+
but the licensor or any of its affiliates brings your product into
|
|
76
|
+
competition by providing a new version of the software or another product
|
|
77
|
+
using the software, you may continue using versions of the software
|
|
78
|
+
available under these terms beforehand to provide your competing product,
|
|
79
|
+
but not any later versions.
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
Discontinued Products
|
|
83
|
+
|
|
84
|
+
You may begin using the software to compete with a product or service
|
|
85
|
+
that the licensor or any of its affiliates has stopped providing, unless
|
|
86
|
+
the licensor includes a plain-text line beginning with "Licensor Line of
|
|
87
|
+
Business:" with the software that mentions that line of business.
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
Sales of Business
|
|
91
|
+
|
|
92
|
+
If the licensor or any of its affiliates sells a line of business
|
|
93
|
+
developing the software or using the software to provide a product, the
|
|
94
|
+
buyer can also enforce Noncompete for that product.
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
Fair Use
|
|
98
|
+
|
|
99
|
+
You may have "fair use" rights for the software under the law. These
|
|
100
|
+
terms do not limit them.
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
No Other Rights
|
|
104
|
+
|
|
105
|
+
These terms do not allow you to sublicense or transfer any of your
|
|
106
|
+
licenses to anyone else, or prevent the licensor from granting licenses
|
|
107
|
+
to anyone else. These terms do not imply any other licenses.
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
Patent Defense
|
|
111
|
+
|
|
112
|
+
If you make any written claim that the software infringes or contributes
|
|
113
|
+
to infringement of any patent, your patent license for the software
|
|
114
|
+
granted under these terms ends immediately. If your company makes such a
|
|
115
|
+
claim, your patent license ends immediately for work on behalf of your
|
|
116
|
+
company.
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
Violations
|
|
120
|
+
|
|
121
|
+
The first time you are notified in writing that you have violated any of
|
|
122
|
+
these terms, or done anything with the software not covered by your
|
|
123
|
+
licenses, your licenses can nonetheless continue if you come into full
|
|
124
|
+
compliance with these terms, and take practical steps to correct past
|
|
125
|
+
violations, within 32 days of receiving notice. Otherwise, all your
|
|
126
|
+
licenses end immediately.
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
No Liability
|
|
130
|
+
|
|
131
|
+
As far as the law allows, the software comes as is, without any warranty
|
|
132
|
+
or condition, and the licensor will not be liable to you for any damages
|
|
133
|
+
arising out of these terms or the use or nature of the software, under
|
|
134
|
+
any kind of legal claim.
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
Definitions
|
|
138
|
+
|
|
139
|
+
The "licensor" is the individual or entity offering these terms, and the
|
|
140
|
+
"software" is the software the licensor makes available under these terms.
|
|
141
|
+
|
|
142
|
+
A "product" can be a good or service, or a combination of them.
|
|
143
|
+
|
|
144
|
+
"You" refers to the individual or entity agreeing to these terms.
|
|
145
|
+
|
|
146
|
+
"Your company" is any legal entity, sole proprietorship, or other kind
|
|
147
|
+
of organization that you work for, plus all its affiliates.
|
|
148
|
+
|
|
149
|
+
"Affiliates" means the other organizations than an organization has
|
|
150
|
+
control over, is under the control of, or is under common control with.
|
|
151
|
+
|
|
152
|
+
"Control" means ownership of substantially all the assets of an entity,
|
|
153
|
+
or the power to direct its management and policies by vote, contract, or
|
|
154
|
+
otherwise. Control can be direct or indirect.
|
|
155
|
+
|
|
156
|
+
"Your licenses" are all the licenses granted to you for the software
|
|
157
|
+
under these terms.
|
|
158
|
+
|
|
159
|
+
"Use" means anything you do with the software requiring one of your
|
|
160
|
+
licenses.
|
package/README.md
CHANGED
|
@@ -4,262 +4,314 @@
|
|
|
4
4
|
|
|
5
5
|
### Your AI co-pilot for Foundry VTT
|
|
6
6
|
|
|
7
|
-
**176 tools.
|
|
7
|
+
**176 tools. 28 AI providers. Zero prep.**
|
|
8
8
|
|
|
9
|
-
Give your favorite AI full control of your virtual tabletop
|
|
9
|
+
Give your favorite AI full control of your virtual tabletop - characters, combat, scenes, music, lighting, images, voices, and everything in between.
|
|
10
10
|
|
|
11
11
|
[](https://foundryvtt.com)
|
|
12
12
|
[](https://www.npmjs.com/package/familiar-vtt)
|
|
13
|
-
[ -->
|
|
13
|
+
[](#license)
|
|
17
14
|
|
|
18
15
|
[Installation](#installation) | [Quick Start](#quick-start) | [Features](#features) | [Connect Your AI](#connect-your-ai) | [FAQ](#faq)
|
|
19
16
|
|
|
20
17
|
</div>
|
|
21
18
|
|
|
22
|
-
---
|
|
23
|
-
|
|
24
19
|
## The story behind Familiar
|
|
25
20
|
|
|
26
|
-
I'm Ryan
|
|
21
|
+
I'm Ryan. Dad of two young kids, married to my favorite person, and perpetually short on free time.
|
|
27
22
|
|
|
28
|
-
I
|
|
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.
|
|
29
24
|
|
|
30
|
-
|
|
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.
|
|
31
26
|
|
|
32
|
-
|
|
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 176 tools across 24 domains and 28 AI providers.
|
|
33
28
|
|
|
34
|
-
|
|
29
|
+
Familiar 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.
|
|
35
30
|
|
|
36
31
|
## What can Familiar do?
|
|
37
32
|
|
|
38
|
-
|
|
33
|
+
Ask your AI to do things that would normally take you minutes of clicking through menus:
|
|
34
|
+
|
|
35
|
+
> "Roll initiative for all the goblins, have them attack the nearest player, and play battle music."
|
|
36
|
+
|
|
37
|
+
> "Create a torchlit dungeon room, place the party at the entrance, and add three skeletons near the altar."
|
|
38
|
+
|
|
39
|
+
> "What spells does Elara have prepared? Does she have enough slots to cast Fireball?"
|
|
40
|
+
|
|
41
|
+
> "Dim the lights, start rain and thunder, and have the innkeeper whisper a warning about the road ahead - in his voice."
|
|
42
|
+
|
|
43
|
+
> "We're done for tonight. Summarize what happened this session and save it."
|
|
44
|
+
|
|
45
|
+
Familiar exposes **176 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.
|
|
46
|
+
|
|
47
|
+
### Highlights
|
|
39
48
|
|
|
40
49
|
<table>
|
|
41
50
|
<tr>
|
|
42
|
-
<td width="
|
|
51
|
+
<td width="33%" valign="top">
|
|
43
52
|
|
|
44
|
-
|
|
45
|
-
Start combat, roll initiative, track turns, apply damage, manage conditions — all through natural conversation.
|
|
53
|
+
**Combat & AI**
|
|
46
54
|
|
|
47
|
-
|
|
55
|
+
Run full encounters hands-free. Roll initiative, resolve attacks, apply damage, track conditions - or let the AI play NPCs with tactical decision-making.
|
|
48
56
|
|
|
49
57
|
</td>
|
|
50
|
-
<td width="
|
|
58
|
+
<td width="33%" valign="top">
|
|
51
59
|
|
|
52
|
-
|
|
53
|
-
Generate speech for any character using AI voice providers. Each NPC gets their own voice, accent, and personality.
|
|
60
|
+
**Voice & Image Generation**
|
|
54
61
|
|
|
55
|
-
|
|
62
|
+
Give every NPC a unique AI-generated voice. Generate scene illustrations and character portraits mid-session without leaving the table.
|
|
56
63
|
|
|
57
64
|
</td>
|
|
58
|
-
|
|
59
|
-
<tr>
|
|
60
|
-
<td width="50%">
|
|
65
|
+
<td width="33%" valign="top">
|
|
61
66
|
|
|
62
|
-
|
|
63
|
-
Create character portraits, item illustrations, battlemaps, and handouts during play. Five image providers to choose from.
|
|
67
|
+
**Scenes & Canvas**
|
|
64
68
|
|
|
65
|
-
|
|
69
|
+
Build maps on the fly. Place tokens, draw walls, set lighting and weather, configure regions - control the entire canvas through natural language.
|
|
66
70
|
|
|
67
71
|
</td>
|
|
68
|
-
|
|
72
|
+
</tr>
|
|
73
|
+
<tr>
|
|
74
|
+
<td width="33%" valign="top">
|
|
69
75
|
|
|
70
|
-
|
|
71
|
-
Switch scenes, adjust lighting, change weather, play music — set the mood without ever leaving the conversation.
|
|
76
|
+
**Audio & Atmosphere**
|
|
72
77
|
|
|
73
|
-
|
|
78
|
+
Manage playlists, trigger sound effects, crossfade tracks. Set the mood without alt-tabbing to Foundry's sidebar.
|
|
74
79
|
|
|
75
80
|
</td>
|
|
76
|
-
|
|
77
|
-
<tr>
|
|
78
|
-
<td width="50%">
|
|
81
|
+
<td width="33%" valign="top">
|
|
79
82
|
|
|
80
|
-
|
|
81
|
-
Read full character sheets, update HP, import items from the compendium, manage spell slots — the AI sees everything.
|
|
83
|
+
**Knowledge & Memory**
|
|
82
84
|
|
|
83
|
-
|
|
85
|
+
Campaign journal, session summaries, and a searchable knowledge base the AI can reference. It remembers what happened three sessions ago.
|
|
84
86
|
|
|
85
87
|
</td>
|
|
86
|
-
<td width="
|
|
88
|
+
<td width="33%" valign="top">
|
|
87
89
|
|
|
88
|
-
|
|
89
|
-
Players went off-script? The AI creates NPCs, spawns tokens, builds encounters, writes journal entries — in seconds.
|
|
90
|
+
**Characters & Items**
|
|
90
91
|
|
|
91
|
-
|
|
92
|
+
Create, update, and inspect actors, inventory, spells, features, and active effects. Bulk operations across the whole party.
|
|
92
93
|
|
|
93
94
|
</td>
|
|
94
95
|
</tr>
|
|
95
96
|
</table>
|
|
96
97
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
|
102
|
-
|
|
103
|
-
| **
|
|
104
|
-
| **
|
|
105
|
-
| **
|
|
106
|
-
| **
|
|
107
|
-
| **
|
|
108
|
-
| **Canvas
|
|
109
|
-
| **
|
|
110
|
-
| **
|
|
111
|
-
| **
|
|
112
|
-
| **
|
|
113
|
-
| **
|
|
114
|
-
| **
|
|
115
|
-
| **
|
|
116
|
-
|
|
|
117
|
-
| **
|
|
118
|
-
|
|
119
|
-
|
|
98
|
+
### All 24 Domains
|
|
99
|
+
|
|
100
|
+
| Domain | Tools | What it does |
|
|
101
|
+
|---|--:|---|
|
|
102
|
+
| **Characters & Actors** | 14 | Create, inspect, update, and manage player characters and NPCs |
|
|
103
|
+
| **Combat & Initiative** | 13 | Start encounters, roll initiative, advance turns and rounds |
|
|
104
|
+
| **Scenes & Tokens** | 19 | Build scenes, place and move tokens, configure vision and movement |
|
|
105
|
+
| **Canvas Environment** | 18 | Walls, lights, weather effects, fog of war, darkness levels |
|
|
106
|
+
| **Audio & Playlists** | 14 | Play, stop, and crossfade music and ambient sound |
|
|
107
|
+
| **Journals & Notes** | 10 | Create and edit journal entries, map pins, and handouts |
|
|
108
|
+
| **Card Decks** | 9 | Draw, deal, shuffle, pass, and manage card hands and decks |
|
|
109
|
+
| **Canvas Drawing** | 8 | Draw shapes, text, and freehand annotations on the canvas |
|
|
110
|
+
| **Rollable Tables** | 7 | Create tables and roll on them for random encounters or loot |
|
|
111
|
+
| **Macros** | 7 | Create, edit, and execute Foundry macros |
|
|
112
|
+
| **World & System** | 6 | World info, system settings, time, pause, and user management |
|
|
113
|
+
| **Combat AI** | 6 | NPC tactical decisions - target selection, ability usage, positioning |
|
|
114
|
+
| **Items** | 6 | Create, update, delete, and search world-level items |
|
|
115
|
+
| **Active Effects** | 5 | Apply, remove, and toggle buffs, debuffs, and status effects |
|
|
116
|
+
| **Folders** | 5 | Organize documents into folder hierarchies |
|
|
117
|
+
| **Regions** | 5 | Define map regions with triggered behaviors |
|
|
118
|
+
| **Ember Events** | 5 | Custom event system for module-to-module hooks |
|
|
119
|
+
| **Knowledge & Memory** | 5 | Campaign knowledge base, session memory, context retrieval |
|
|
120
|
+
| **Compendium & Rules** | 4 | Search and import from compendium packs and rule references |
|
|
121
|
+
| **Voice Generation** | 4 | Generate NPC speech audio with distinct AI voices |
|
|
122
|
+
| **Chat Messages** | 2 | Send and read chat messages in the Foundry sidebar |
|
|
123
|
+
| **Dice** | 1 | Roll any dice expression with full Foundry roll parsing |
|
|
124
|
+
| **Image Generation** | 1 | Generate scene art or character portraits on demand |
|
|
125
|
+
| **Scene Generator** | 1 | Generate complete scenes from text blueprints |
|
|
120
126
|
|
|
121
127
|
## Connect your AI
|
|
122
128
|
|
|
123
|
-
|
|
129
|
+
There are three ways to connect an AI to your game. They all give the AI the same 176 tools - the difference is where the AI runs.
|
|
124
130
|
|
|
125
|
-
### Built-in chat (easiest)
|
|
126
|
-
No server, no config. Install the module, pick an AI provider, paste your API key, and start talking.
|
|
131
|
+
### Option 1: Built-in chat (easiest)
|
|
127
132
|
|
|
128
|
-
|
|
133
|
+
No server. No terminal. No config files. Just install the module, pick a provider, paste an API key, and start talking to your game.
|
|
129
134
|
|
|
130
|
-
|
|
131
|
-
Already paying for Claude Pro, ChatGPT Plus, or Gemini? Connect them directly via the [Model Context Protocol](https://modelcontextprotocol.io). Your AI subscription becomes your DM assistant at no extra cost.
|
|
135
|
+
Familiar connects directly to **28 AI providers** across four categories:
|
|
132
136
|
|
|
133
|
-
|
|
|
134
|
-
|
|
135
|
-
| **
|
|
136
|
-
| **
|
|
137
|
-
| **
|
|
138
|
-
| **
|
|
139
|
-
| **Cursor / Windsurf / VS Code** | stdio | Via MCP config |
|
|
137
|
+
| Category | Providers |
|
|
138
|
+
|----------|-----------|
|
|
139
|
+
| **Chat** (16) | OpenRouter, Anthropic, OpenAI, Google, Groq, Mistral, Together AI, DeepSeek, xAI, Cohere, Perplexity, Fireworks AI, Cerebras, SambaNova, Ollama (local), LM Studio (local) |
|
|
140
|
+
| **Voice** (4) | ElevenLabs, Cartesia, OpenAI TTS, PlayHT |
|
|
141
|
+
| **Image** (5) | OpenAI (GPT Image), Stability AI, fal.ai, Leonardo AI, Replicate |
|
|
142
|
+
| **Transcription** (3) | Gladia, Deepgram, AssemblyAI |
|
|
140
143
|
|
|
141
|
-
|
|
144
|
+
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.
|
|
142
145
|
|
|
143
|
-
###
|
|
144
|
-
Familiar never proxies, meters, or marks up your AI costs. You bring your own API keys, and every token goes straight to the provider. With 25 providers to choose from, you're never locked in.
|
|
146
|
+
### Option 2: MCP - use your existing AI subscription
|
|
145
147
|
|
|
146
|
-
|
|
148
|
+
Already paying for Claude, ChatGPT, or Gemini? You can connect them directly to Familiar through the [Model Context Protocol](https://modelcontextprotocol.io). Your subscription becomes a DM assistant at no extra cost.
|
|
147
149
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
### From Foundry (recommended)
|
|
151
|
-
1. Open Foundry VTT as GM
|
|
152
|
-
2. Go to **Settings** > **Manage Modules** > **Install Module**
|
|
153
|
-
3. Search for **"Familiar"** or paste the manifest URL:
|
|
154
|
-
```
|
|
155
|
-
https://github.com/Ryanjansen92/familiar/releases/latest/download/module.json
|
|
156
|
-
```
|
|
157
|
-
4. Click **Install**, then enable the module in your world
|
|
150
|
+
The MCP server ships as an npm package. Most clients just need one line:
|
|
158
151
|
|
|
159
|
-
### For MCP clients (npm)
|
|
160
152
|
```bash
|
|
161
153
|
npx familiar-vtt
|
|
162
154
|
```
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
155
|
+
|
|
156
|
+
| Client | Transport | Config |
|
|
157
|
+
|--------|-----------|--------|
|
|
158
|
+
| Claude Desktop | stdio | Add to `claude_desktop_config.json` |
|
|
159
|
+
| Claude Code | stdio | `claude mcp add familiar -- npx familiar-vtt` |
|
|
160
|
+
| ChatGPT | Streamable HTTP | Remote URL via Cloudflare tunnel |
|
|
161
|
+
| Gemini CLI | stdio | Add to MCP settings (free with Gemini 2.5 Pro) |
|
|
162
|
+
| Cursor | stdio | Add to `.cursor/mcp.json` |
|
|
163
|
+
| Windsurf | stdio | Add to MCP config |
|
|
164
|
+
| VS Code (Copilot) | stdio | Add to `.vscode/mcp.json` |
|
|
165
|
+
|
|
166
|
+
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 generates the exact config block for your chosen client - just copy and paste.
|
|
167
|
+
|
|
168
|
+
### Option 3: MCP subscription providers
|
|
169
|
+
|
|
170
|
+
This is a hybrid of the first two. ChatGPT and Mistral's Le Chat can connect as subscription-based providers inside the built-in chat UI. They bring their own models - you authenticate with your existing account, and Familiar handles the rest through MCP.
|
|
171
|
+
|
|
172
|
+
You get the convenience of the built-in chat window with the cost advantage of your existing subscription.
|
|
173
|
+
|
|
174
|
+
### Which should I pick?
|
|
175
|
+
|
|
176
|
+
| I want to... | Use |
|
|
177
|
+
|--------------|-----|
|
|
178
|
+
| Get started in under a minute | **Built-in chat** with any API key |
|
|
179
|
+
| Use my Claude/ChatGPT/Gemini subscription | **MCP** |
|
|
180
|
+
| Run everything offline | **Built-in chat** with Ollama or LM Studio |
|
|
181
|
+
| Have voice, images, and transcription | **Built-in chat** (MCP is text-only) |
|
|
182
|
+
| Use the AI from my code editor | **MCP** via Cursor, Windsurf, or VS Code |
|
|
183
|
+
|
|
184
|
+
### Your keys, your cost
|
|
185
|
+
|
|
186
|
+
Familiar never proxies, meters, or marks up your AI usage. API keys go straight from your browser to the provider. With MCP, your existing subscription handles it. Either way, there is no middleman.
|
|
187
|
+
|
|
188
|
+
## Installation
|
|
189
|
+
|
|
190
|
+
In Foundry VTT, go to **Settings > Manage Modules > Install Module**, then search for **Familiar**.
|
|
191
|
+
|
|
192
|
+
Or paste the manifest URL directly:
|
|
193
|
+
|
|
166
194
|
```
|
|
195
|
+
https://github.com/Ryanjansen92/familiar-releases/releases/latest/download/module.json
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Enable the module in your world under **Settings > Manage Modules**.
|
|
199
|
+
|
|
200
|
+
### For MCP Clients (Claude Desktop, ChatGPT, etc.)
|
|
167
201
|
|
|
168
|
-
|
|
202
|
+
If you want to connect an external AI client via the [Model Context Protocol](https://modelcontextprotocol.io), you need the MCP server:
|
|
169
203
|
|
|
170
|
-
|
|
204
|
+
```sh
|
|
205
|
+
npx familiar-vtt
|
|
206
|
+
```
|
|
171
207
|
|
|
172
|
-
|
|
173
|
-
2. **Open settings** — go to Module Settings > Familiar
|
|
174
|
-
3. **Pick a chat provider** (e.g., OpenAI, Anthropic, or a free local model via Ollama)
|
|
175
|
-
4. **Paste your API key**
|
|
176
|
-
5. **Open the Familiar chat** from the sidebar button
|
|
177
|
-
6. **Start playing** — ask your AI to roll dice, run combat, describe a scene, or generate an image
|
|
208
|
+
Or install it globally:
|
|
178
209
|
|
|
179
|
-
|
|
210
|
+
```sh
|
|
211
|
+
npm install -g familiar-vtt
|
|
212
|
+
```
|
|
180
213
|
|
|
181
|
-
|
|
214
|
+
The **Setup Wizard** in Module Settings > Familiar walks you through connecting your MCP client step by step - config snippets, WebSocket port, the works.
|
|
182
215
|
|
|
183
|
-
|
|
216
|
+
## Quick Start
|
|
184
217
|
|
|
185
|
-
|
|
218
|
+
1. Open **Module Settings > Familiar**
|
|
219
|
+
2. Pick a chat provider - [OpenAI](https://platform.openai.com/api-keys), [Anthropic](https://console.anthropic.com/), or run local models free with [Ollama](https://ollama.com)
|
|
220
|
+
3. Paste your API key
|
|
221
|
+
4. Open the Familiar chat panel from the sidebar
|
|
222
|
+
5. Start playing
|
|
186
223
|
|
|
187
|
-
|
|
224
|
+
That's it. No server to run, no terminal, no config files. The built-in chat works entirely inside Foundry.
|
|
188
225
|
|
|
189
|
-
|
|
226
|
+
### Compatibility
|
|
190
227
|
|
|
191
|
-
|
|
228
|
+
| | Supported |
|
|
229
|
+
|---|---|
|
|
230
|
+
| **Foundry VTT** | v13, v14 |
|
|
231
|
+
| **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. |
|
|
192
232
|
|
|
193
233
|
## FAQ
|
|
194
234
|
|
|
195
235
|
<details>
|
|
196
|
-
<summary><b>Is
|
|
236
|
+
<summary><b>Is Familiar free?</b></summary>
|
|
237
|
+
|
|
238
|
+
The core module is free and includes all 176 tools, 28 providers, built-in chat, and full MCP support. There is a Pro tier with premium features like session persistence, auto-summarization, campaign memory, knowledge base RAG, and voice transcription - pricing is handled through Polar.sh.
|
|
197
239
|
|
|
198
|
-
Yes. All 176 tools, all 25 providers, the built-in chat, and full MCP support are free. A Pro tier with premium features (session persistence, auto-summarization, NPC memory) is coming soon for a small monthly fee.
|
|
199
240
|
</details>
|
|
200
241
|
|
|
201
242
|
<details>
|
|
202
|
-
<summary><b>Does
|
|
243
|
+
<summary><b>Does Familiar collect my data?</b></summary>
|
|
244
|
+
|
|
245
|
+
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.
|
|
203
246
|
|
|
204
|
-
Only when you talk to an AI provider — the same as any other AI chat. Familiar runs locally inside Foundry. No telemetry, no analytics, no data collection. If you use a local model (Ollama/LM Studio), nothing ever leaves your machine.
|
|
205
247
|
</details>
|
|
206
248
|
|
|
207
249
|
<details>
|
|
208
250
|
<summary><b>Can the AI break my world?</b></summary>
|
|
209
251
|
|
|
210
|
-
Familiar
|
|
252
|
+
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.
|
|
253
|
+
|
|
211
254
|
</details>
|
|
212
255
|
|
|
213
256
|
<details>
|
|
214
|
-
<summary><b>
|
|
257
|
+
<summary><b>What is the difference between MCP mode and built-in chat?</b></summary>
|
|
258
|
+
|
|
259
|
+
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 176 tools.
|
|
215
260
|
|
|
216
|
-
Absolutely — that's one of the main use cases. The AI can run NPCs, manage encounters, describe scenes, and make rulings. It's like having a DM available whenever you want to play.
|
|
217
261
|
</details>
|
|
218
262
|
|
|
219
263
|
<details>
|
|
220
|
-
<summary><b>
|
|
264
|
+
<summary><b>Which AI models work best?</b></summary>
|
|
265
|
+
|
|
266
|
+
For the best experience: Claude Sonnet 4.6 or Opus 4.6, GPT-4.1, or Gemini 2.5 Pro. If you want free options, Gemini CLI has a free tier, and Ollama runs local models like Qwen3 or Llama 4 with no API costs at all.
|
|
221
267
|
|
|
222
|
-
Familiar works alongside any Foundry module. Dedicated integrations with Midi-QOL, Sequencer, Token Magic FX, and JB2A are on the roadmap.
|
|
223
268
|
</details>
|
|
224
269
|
|
|
225
270
|
<details>
|
|
226
|
-
<summary><b>
|
|
271
|
+
<summary><b>Can I use this for solo play?</b></summary>
|
|
272
|
+
|
|
273
|
+
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.
|
|
227
274
|
|
|
228
|
-
For the best experience, use a model with a large context window and strong tool-use support: **Claude 4 Sonnet/Opus**, **GPT-4o**, or **Gemini 2.5 Pro**. For free/local options, **Gemini CLI** (free tier) or **Ollama with Qwen/Llama** work well.
|
|
229
275
|
</details>
|
|
230
276
|
|
|
231
|
-
|
|
277
|
+
<details>
|
|
278
|
+
<summary><b>Does it work with game systems other than D&D 5e?</b></summary>
|
|
232
279
|
|
|
233
|
-
|
|
280
|
+
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.
|
|
281
|
+
|
|
282
|
+
</details>
|
|
234
283
|
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
- [ ] NPC character cards (personality, speech patterns, memory)
|
|
238
|
-
- [ ] Session recaps (one-click journal summary)
|
|
239
|
-
- [ ] Module integrations (Midi-QOL, Sequencer, Token Magic FX)
|
|
240
|
-
- [ ] AI Campaign Setup (import an adventure, auto-prep your sessions)
|
|
284
|
+
<details>
|
|
285
|
+
<summary><b>Will Familiar conflict with my other Foundry modules?</b></summary>
|
|
241
286
|
|
|
242
|
-
|
|
287
|
+
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.
|
|
243
288
|
|
|
244
|
-
|
|
289
|
+
</details>
|
|
245
290
|
|
|
246
|
-
|
|
291
|
+
## Roadmap
|
|
247
292
|
|
|
248
|
-
-
|
|
249
|
-
- [Join the discussion](https://github.com/Ryanjansen92/familiar/discussions)
|
|
293
|
+
These are things I'm actively working toward. No promises on timelines - this is a nights-and-weekends project.
|
|
250
294
|
|
|
251
|
-
|
|
295
|
+
- Module integrations (Midi-QOL, Sequencer, Token Magic FX, JB2A) for automated rolls, visual effects, and animations
|
|
296
|
+
- AI Campaign Setup - import a published adventure and let the AI help you prep sessions
|
|
297
|
+
- Pathfinder 2e support
|
|
298
|
+
- More game systems beyond D&D 5e
|
|
252
299
|
|
|
253
|
-
##
|
|
300
|
+
## Feedback
|
|
254
301
|
|
|
255
|
-
Familiar is
|
|
302
|
+
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:
|
|
303
|
+
|
|
304
|
+
- Drop a message in the [Foundry VTT Discord](https://discord.gg/foundryvtt)
|
|
305
|
+
- Use the built-in feedback button inside the module
|
|
306
|
+
|
|
307
|
+
## License
|
|
256
308
|
|
|
257
|
-
|
|
309
|
+
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.
|
|
258
310
|
|
|
259
311
|
<div align="center">
|
|
260
312
|
|
|
261
|
-
Built
|
|
313
|
+
Built for the DM who has more ideas than free time.
|
|
262
314
|
|
|
263
|
-
*
|
|
315
|
+
*May your rolls be high, your prep be low, and your players never notice the AI is helping.*
|
|
264
316
|
|
|
265
317
|
</div>
|
package/package.json
CHANGED