Familiar v2.24.0

Familiar v2.24.0 | AI DM for Foundry VTT.

Install: Add this manifest URL in Foundry → Add-on Modules → Install Module:

https://github.com/Ryanjansen92/familiar-releases/releases/latest/download/module.json

---

Features

• Players can talk to Familiar in the Foundry chat. Switch on Table
  Chat (Familiar settings, Chat tab; off by default) and a message that
  starts with @familiar gets an answer in the same chat, from your running
  Familiar, on your key, with the Familiar window open or closed. Hand an
  NPC to Familiar from its sheet header (or the set-table-npc tool) and it
  answers to @<its name> in character, with its portrait, from its public
  bio only. Familiar can ask the player for a roll and uses the result in
  the next answer. You see every question and answer on a whispered card.
  A player's own character follows your approval mode, also when they just
  ask for it: their hit points, slots and resources, a condition they take
  on, the state of their items, their own token. So do the things Foundry
  already lets a player do, like rolling dice or opening an unlocked door.
  Anything beyond that asks you first in every mode: another character, the
  whole party, XP, loot and the permanent numbers on their sheet, the rest
  of the scene, anything destructive, anything that bills your image or
  voice provider, and switching a tool bundle on or off. A request you leave
  unanswered for two minutes is declined and the player hears it is your
  call. A whispered question gets a whispered answer and remembers the
  player's earlier whispers to the same name; a roll request says who the
  link rolls for, so a GM rolling for a player selects that token first. A
  session budget pauses it with a toast. With no provider configured in the
  built-in chat, or no active licence, questions wait in the table inbox and
  your Claude, Codex, or Antigravity session reads them with
  get-pending-table-questions ("check the table"). One honest limit: an
  answer can only be as private as what Familiar can read, so switch it off
  where an answer would spoil the plot.
• Play from a player login with Familiar as your GM. Name one player
  account as the Solo Player (Chat tab, Table Chat) and log in as that player
  in a second window while your GM browser keeps running. That player's
  @familiar turns run under your own approval mode: Familiar makes the
  rulings, runs the NPCs and monsters, hands out XP and loot, and changes the
  sheet on request. Under Balanced a destructive call still waits for a click
  in the GM window; pick Yolo to never switch windows. Everyone else at the
  table keeps the player rules.
• Class and subclass features the engine actually resolves. Every 2024
  base-class feature is now triaged against the engine, and the first
  tranches run for real. Second Wind and Wholeness of Body roll the sheet's
  own healing activity. Cunning Action and Monk's Focus spend the Bonus
  Action through resolve-action, with the turn gate and the use draw
  behind them. Stunning Strike rides an attack on request, with the CON
  save, the Stunned carrier and the immunity arm. Blessed Strikes,
  Elemental Fury, Divine Strike, Primal Strike, Colossus Slayer, Frenzy,
  Innate Sorcery, Sculpt Spells, and the Champion's Improved and Superior
  Critical all land on the roll they belong to. Three Warlock invocations
  join them: Fiendish Vigor, Lifedrinker, and Eldritch Smite.
• Every SRD metamagic option now runs. Careful, Empowered, Extended,
  Heightened, Seeking, Transmuted, and Twinned Spell join Quickened,
  Subtle, and Distant on resolve-spell, stacking by the 2024 rule.
  Careful hands your allies an automatic save and no damage, Heightened
  imposes disadvantage that follows the spell into its repeat saves,
  Empowered rerolls the low dice and only spends its Sorcery Point when a
  die actually changes, Seeking rerolls a missed spell attack, Extended
  doubles the duration, and Twinned raises the target count through a new
  budget read off the spell's own scaling, so a two-target Twinned cast is
  checked rather than trusted.
• Extra Attack is a budget, not a note on the sheet. Taking the Attack
  action stamps how many attacks it buys, from Extra Attack up through the
  Fighter's Two and Three Extra Attacks, plus Thirsting Blade and Devouring
  Blade on a pact weapon. Later attacks that turn draw from that budget
  before Action Surge hands out a slot and before a Great Weapon Master
  reroute, a second Attack action re-stamps it, and the attack past the
  budget is refused with the spent count in the message. The combat
  snapshot shows what is left.
• The rest of the character sheet, when you ask for it. get-character
  and list-party-members take sections: bio, traits, skills,
  resources, or all. Biography and appearance, languages and
  resistances, senses and proficiencies, all eighteen skills with their
  passives, currency, XP, hit dice, death saves, exhaustion and resource
  trackers. The default sheet stays lean and now carries a small identity
  block of its own: the sheet's gender and pronouns text, alignment, size,
  age, class levels, and for an NPC the challenge rating and creature type.
• Familiar stops guessing pronouns. The party line and the @mention
  header carry the sheet's own gender and pronouns field word for word, and
  the core prompt has one rule about it: use it as written, and when it is
  empty use the name or they/them. Never inferred from a name or a portrait.
• Build a character in one call, choices included. create-character
  takes items, effects, and a prototype token, create-item writes a
  homebrew item straight onto a sheet, create-effect puts a transfer
  effect on an owned item, and update-character reaches the identity,
  biography, trait, skill, currency and token paths plus the D&D 5e Special
  Traits panel. For a class, species, background, or a level-up, pass
  applyAdvancement and the system's own advancement engine does the work:
  the steps with no choice in them apply by themselves, and every real
  choice (subclass, ASI or feat, fighting style, skills, weapon mastery)
  opens Foundry's Advancement window for you. One honest limit while that
  window is open: every other edit to that character is refused, because
  the window would overwrite it. A whisper tells you when it is done.
• One art style for the whole campaign. Pick it once in settings
  (Painterly, Realistic, Cartographer Ink, Hand-Drawn, or a sentence of your
  own) and every generation follows it: loose images and edits, actor
  portraits and token art, item icons, battle maps and their candidates,
  each with vocabulary suited to a map or an illustration. The chat knows
  which style is set and can override it for a single image, and every
  result echoes the style it was rendered in. The image model field became
  a picker (provider default, the live catalog, or a custom model id)
  instead of a free-text box that read as stuck, and every Art Library card
  gained Remove from library. One honest limit there: Foundry has no
  file-delete API, so the card goes and the image file stays on disk.
• Edit a generated image from the image itself. Every stored image
  in the Familiar chat (the image cell, the map block, the lightbox), every
  Art Library card, and every art journal page now carries Edit…. It
  opens a small dialog: a thumbnail, "What should change?", and the
  provider that will run it. Type what to remove, add, or keep, press
  Edit, and the chat runs the edit for you, so you no longer need to know
  that an edit means "the path plus an instruction". The result lands as a
  new image next to the original (the original is never overwritten), the
  Art Library marks it Edited with a link back to the source, and the
  result cell gets Try again for another variant of the same edit. One
  honest limit: the whole image is regenerated from your instruction, so
  nearby details may change. Providers without an edit channel (Leonardo,
  NanoGPT) show the button disabled with a hint instead of failing after
  the click. MCP clients get the same version chain: an edit through
  generate-image names its parent as editOf in the result and the
  legend, and files the result with that parent in the Art Library.
• Point at the part of the image that should change. In the Edit
  image dialog, click two corners on the thumbnail (or drag) to mark an
  area, then describe the change as before. Familiar tells the image
  model where the change belongs in words. On OpenAI, fal.ai and
  OpenRouter it also draws a thin outline on a copy of the image, one
  the model sees and you never do. It is a hint, not a mask: nearby
  details may still change, and the whole image is still regenerated.
  The result caption names the area ("edited copy (upper-left), original
  kept") and Try again keeps it. MCP clients pass the same thing as
  editRegion on generate-image and get it echoed back with how it
  was applied.
• Your own rolls, read back. Type /rolled in the Familiar chat and
  the newest dice roll in the Foundry chat log goes straight to the AI:
  who rolled, the formula, each die, the total, and whatever the system's
  roll card says on top. No tool call, no "wait until I say Rolled"
  prompt. /rolled Jendra picks her newest roll when two characters
  rolled; /rolled 2 hands over the two newest. Works on every game
  system, because it reads Foundry's own roll data.
• Roll requests click on any system. request-player-rolls takes a
  formula on systems other than D&D 5e (2d6, 1d100, ...) and posts
  Foundry's own clickable dice link, so the player rolls it with their
  character as the speaker. Plain dice only: Familiar does not know
  another system's sheet, so skill values are not added. Without a
  formula the request still posts as plain text.
• Rolls in the chat log carry their dice. get-recent-messages now
  reports formula, total, and kept die results for every roll message,
  on every system, so an AI reading the log no longer sees a bare
  number.
• The ChatGPT desktop app is now its own setup card. The Codex desktop
  app merged into the ChatGPT app, so the wizard card says so: it walks you
  through the app's Codex tab, which is the part that can talk to
  Familiar. The Chat tab and "ChatGPT Classic" cannot reach a server running
  on your own machine, so the card names that up front. Every ChatGPT plan
  including Free has the Codex tab. Setup is the same ~/.codex/config.toml
  block, shared with Codex CLI.
• New wizard step: tell Codex when to use Familiar. Codex doesn't
  announce its MCP tools to the model, so a fresh conversation had no idea
  Familiar existed and would try to reach your game through a browser
  instead. Both Codex cards now hand you a short note to drop in
  ~/.codex/AGENTS.md, with a copy button. With them in place, "roll a d20
  in Foundry" reaches for Familiar on the first try. The verify step also
  stopped chasing /mcp: it lists Familiar with "Tools: (none)" even when
  every tool works, so the step now asks Codex to run a tool instead.

Changed

• Verified against Foundry 14.367 (V14 Stable 9). No code changes were
  needed. Minimum stays v13.
• Familiar's dialogs wear your chat theme. Edit image, Create scene from
  image, and Copy diagnostics rendered in Foundry's own grey chrome, violet
  focus ring included, next to a Desert or Midnight chat. They read as part
  of the chat now, in all three themes.
• Death saves stop being writable by hand mid-fight. During enforced
  combat, writing the death-save counters through update-character is
  refused; roll them through resolve-death-save. The two 2024 consequences
  the engine does not model, damage taken at 0 hit points and stabilizing
  with Medicine, still go through with a stated reason and a line in the
  chat log.
• Claude Sonnet 5 is in the Anthropic list before you connect a key. The
  dropdown fills from Anthropic's own model list once a key is in, but the
  cold-start seed behind it was a generation old, and picking Sonnet 5 on
  that path fell through to a 16k output cap with the reasoning-effort
  control hidden.
• A slow first start no longer looks like a broken connection. The
  generated Codex config now allows 60 seconds for start-up. The very first
  launch downloads Familiar before it can answer, and on a slow machine or
  connection that ran past the default budget and the client gave up on the
  server.

Fixes

• The Google provider answers again. Test connection and chat both came
  back HTTP 400. Three causes, all of them fixed: Gemini's OpenAI-compatible
  endpoint accepts only a Bearer header while the model list accepts only
  the Google key header, tools went out carrying an internal annotations
  field that Google's parser rejects, and Gemini 3.x returns a thought
  signature it expects echoed on the next turn. Parallel tool calls stay
  apart now that the compatibility layer's index-less stream deltas get a
  slot of their own, the model list drops the image, speech, and robotics
  models, and a Google AI Studio key (AQ.) is redacted from logs like
  every other provider key.
• A rate limit waits as long as the provider asked. Google's free tier
  puts the wait in the error body, where the browser cannot read the
  retry-after header, so Familiar backed off one second, then two, and
  burned nine requests in about half a minute before erroring out on a wait
  that would have cleared. The wait now comes off the body when the header
  is missing, and the chat says "Rate limited, retrying in 57s" while it
  sits there.
• The Party sheet reads as a party. get-character on a D&D 5e group
  reported 0/0 hit points, no AC, and no members, so Familiar concluded a
  four-member party was empty. A group now returns its roster in sheet
  order, the travel pace with its per-hour speeds and daily distance, the
  shared XP pool, and the party's coin. list-party-members and the chat's
  party block read that roster first, so a party you assembled on the sheet
  counts before any player owns a character.
• Other game systems get their own fields back. Item reads projected
  every system through the D&D 5e allowlist, so a Pathfinder 2e item lost
  its traits, bulk, and rules text with nothing to say it had. Token rows,
  screenshot legends, and the chat's party and tracker blocks read
  5e-shaped hit points the same way and showed none at all on Dragonbane,
  PF2e, or Call of Cthulhu. Both now go through the system probe, and D&D
  5e output is byte-identical to before.
• Effects that come from an item are visible. list-effects read only
  the effects sitting on the actor, so everything a weapon, a feature, or a
  class feature transfers was missing from the list and from
  get-character. Rows now name the item they come from, an unequipped or
  unattuned item's suppressed effects are marked, and updating or deleting
  one resolves to the item that owns it.
• A move that lands somewhere else says so. move-token snapped the
  token to the grid and returned a position that quietly differed from the
  one asked for. The result now echoes where the snap put it, notes when
  the token already stood there, and the description says outright that
  walls are ignored. resolve-movement used to report success and zero
  feet with no explanation when the destination snapped into the token's
  own square; it now names that as holding position.
• A battle map follows the art style you picked. Named once, halfway
  through a long map brief, the style held in roughly half the samples and
  in none of a five-style run: ink cartography, pencil sketch, and
  watercolor all came back as the same photoreal render. A styled prompt
  now opens with the style and closes by restating it, and the realism cues
  that dragged every medium back to the default look are gone. Unstyled
  prompts are unchanged.
• Auto-broadcast voice no longer goes quiet for good. Every clip in the
  fan-out waited on a Foundry socket acknowledgement with no time limit, so
  one lost acknowledgement, which is what a socket reconnect produces,
  wedged the chain for the rest of the session: you kept hearing every clip
  locally, your players never heard another one, and nothing was logged.
  Every step in that chain now runs under a deadline.
• Editing a map you already generated now goes straight to the edit. Ask
  for a change to an existing map or scene background, a front door drawn
  flat on the floor, a night-time version of the same street, and the chat
  reaches for the image edit at once (the original as reference, your words
  as the instruction) instead of first hunting through scenes, tiles, and
  walls for something to change. The tool result now carries the instruction
  that actually drove the edit and confirms the reference was applied, so the
  chat no longer describes a finished edit as a fresh generation.
• Every window and every thread keeps its tools. Opening a second
  thread in the ChatGPT/Codex desktop app, a second Claude Desktop
  window, or Codex CLI next to the app no longer leaves that client
  without Familiar's tools. Each of those starts its own Familiar
  server, and only one can hold the connection to Foundry; the extra
  ones now attach to the server that already has it instead of shutting
  down. Close the window that owned the connection and another one picks
  it up, and Foundry reconnects on its own.
• npx familiar-vtt stops warning on Node 20 and 22. The published
  manifest carried the repo's own npm floor, which those Node versions ship
  an older npm than, so a correct install printed EBADENGINE. The floor is
  stripped at publish time; the Node requirement is unchanged.

Internal

• PROTOCOL_VERSION stays 1. Every shared-schema change this release is
  additive-optional, and a second server instance negotiates its peer role
  behind optional fields, so an older primary rejects it cleanly. Tool
  count 209 → 211 across 25 domains (set-table-npc,
  get-pending-table-questions).
• The module bundle's size ceiling moved to 3 MB after a fresh composition
  pass: 91% of the output is Familiar's own source, with the combat content
  the part that keeps growing.