Familiar v2.23.0

Familiar v2.23.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

• Every generated image lands in the Art Library. Battle maps,
  portraits, tokens, item icons, and handouts file themselves into
  per-category journals under a "Familiar Art" folder, each page carrying
  the prompt, the provider, the model, and what the image cost. A new
  GM-only gallery window sits on top: category tabs, search across every
  stored prompt, and a lazy-loading thumbnail grid. Open it from the
  journal sidebar, the Tokens scene controls, or the folder header.
• Drag art from the gallery onto the map. A portrait or token card
  whose actor still exists drags as that actor, so Foundry places the
  token itself. Props, items, and handouts drop as a tile where you
  release them, sized to two grid squares with the aspect preserved.
  Hold Shift to bypass snapping.
• Portraits, tokens, and item icons in one call. generate-actor-art
  and generate-item-art generate the image, cut the background where
  the provider can do it, and write it to the actor portrait, the
  prototype token (dynamic ring included), or the item icon. Tokens
  already on the scene wearing the old art follow the change, and every
  result echoes the previous image so a manual revert is one edit away.
• Battle maps that match your grid. The requested image now carries
  your scene's aspect ratio per provider instead of a fixed 3:2, so a
  40x28 map stops arriving stretched off its squares. Four scale presets
  (small, medium, large, huge) plus a screen preset set the grid from a
  word, the prompt builder writes a composition brief instead of a bare
  scene description, and fal's Nano-Banana renders at its native 4K tier
  when you ask for high quality. Maps upload as WebP when the browser
  can encode it.
• Turn any generated map into a scene. "Create scene" on a map opens
  a dialog with the name prefilled from the prompt, editable grid size
  behind S / M / L / Screen chips, a live warning when the grid and the
  image disagree by more than 5%, and an Activate checkbox. The scene is
  created with the background applied, a thumbnail derived on the spot,
  and feet-per-square set from the same field. create-scene gained the
  same activate and thumbnail behaviour for MCP clients.
• "Finish this map" walls the map for you. One click on a generated
  map hands the model the image, the exact pixel-to-canvas mapping, and a
  brief: walls along the structures, doors and windows where they belong,
  lights in the lit rooms. It verifies its own work with a darkness
  screenshot and restores your lighting afterwards.
• Edit an image, or keep an NPC consistent. generate-image takes
  reference images from your Foundry storage plus an edit instruction:
  the same tavern at night, the same NPC in a new pose, a winter variant
  of a map you already like. Routed through OpenAI's edit endpoint,
  OpenRouter's reference channel, or fal's edit models.
• Generated art reaches the table. A Share button on every generated
  image posts it into Foundry chat where all your players see it,
  create-journal-page takes an image source for handouts, and the
  actor and item sheets grew a Generate art button in the header.
• What each image cost, on the image. Generations carry the
  provider's own reported cost as a caption under the image and in the
  MCP result. Actuals only: no price table, and no caption at all when
  the provider reports nothing.
• NanoGPT does images and voice on one balance. Both the image and
  the TTS providers run off the same sk-nano key you already use for
  chat, with 213 image models and 62 voices discovered live.
• "Use my chat key" copies the key across tabs. When the image or
  voice provider you picked has a chat sibling holding a key
  (OpenRouter, OpenAI, NanoGPT), a button next to the empty key field
  copies it over and runs the connection test. One-time copy, and the
  slots stay independent afterwards.
• Model fields suggest real models. Image and voice model inputs now
  fill from each provider's live catalog, cached for a day and refreshed
  on a green Test, exactly like the chat side already did.
• The chat header shows what the session is spending. Context
  percentage is visible from the first message instead of appearing at
  75%, the tooltip carries cumulative calls and tokens for the session,
  and background work (summarizing, memory, session titles) lights an
  indicator while it runs. A new Background AI settings section picks
  which model does that work.
• Windows that let light through. create-walls takes proximity
  thresholds per channel, so a window blocks sight past 20 feet but lets
  the beam out. Regions gained difficult-terrain vocabulary, so a pool
  can cost double movement.
• The vault folder scope tells you when it's wrong. The Notes tab
  rejects absolute paths on save with the two real fixes, suggests folder
  names from your vault as you type, and the Test button cross-checks
  what you scoped against what the vault actually holds.

Changed

• Generated maps render as their own block in chat, with the scene
  name, the cost, and Activate / Finish this map / Share underneath,
  instead of hiding inside a collapsed tool call.
• The scene generator joins the chat tool set automatically once
  image generation is configured, so asking for a battle map works
  without enabling a bundle first.
• The curated MCP profile swapped voice for art. Image generation is
  in, voice generation is out (Claude Desktop's 100-tool ceiling fits one
  of them). Bring voice back with
  FAMILIAR_TOOL_BUNDLES=voice-generation.
• Verified against Foundry 14.366 (V14 Stable 8). Minimum stays
  v13, and the standing policy is now written down: build for the newest
  release, keep v13 working through version gates.

Fixes

• Any Foundry system could take a bad damage write. apply-damage
  called actor.applyDamage on every system that defined the method,
  but the argument shapes differ: Shadowdark parsed the dnd5e array into
  a NaN hit-point write, and pf1 read it as healing. The system branch is
  now dnd5e-only; everything else takes the guarded manual path.
• Thrown weapons are melee weapons. A dagger thrown across the room
  was classified as ranged, which cost it the melee attack profile,
  invented 60-foot "melee" reach, dropped opportunity attacks, and
  misread Sneak Attack and Divine Smite eligibility.
• Defeated markers no longer spread. Dropping one unlinked goblin to
  0 HP marked every sibling goblin sharing that world actor as defeated.
  Healing had the same problem in reverse.
• Combat rounds stopped inflating. Foundry v14 leaves a stale turn
  pointer behind on roster changes; the next advance persisted an extra
  round, which also handed out fresh action budgets.
• dnd5e 6.0 readiness. The unreleased 6.0 branch moves every
  roll-time bonus field the resolver reads. Familiar now reads the new
  paths first and falls back to 5.x, so global attack, damage, and save
  bonuses cannot silently drop out of the math. A weapon's flat to-hit
  override works again too.
• A malformed origin allowlist opened the WebSocket. A
  FAMILIAR_WS_ALLOWED_ORIGINS value holding only separators parsed to
  an empty list, which the connection check read as allow-all. It now
  falls back to the loopback defaults.
• Scene backgrounds land on Foundry v14. Creating a scene with a
  background silently dropped it, and the advertised update-scene
  background round-trip was a no-op on the same code path. Both write
  through the version-aware helper now, and the deprecation warnings
  they logged are gone.
• The lightbox actions were invisible. The overlay mounts on the
  document body, where none of its theme tokens resolved, so it rendered
  transparent under the app windows and its buttons went unseen.
• The microphone tells you why it won't start. On a plain-HTTP LAN
  address the browser withholds microphone access entirely; live
  transcription now names the fix (https, or localhost on the host
  machine) instead of failing with a raw type error.
• Multi-candidate battle maps come back with all four. fal's
  flux-2-pro takes no image count, so a request for four returned one.
  The batch now tops itself up in parallel. The picker also keeps its
  tiles at full size, stays open while you choose, and hands you the map
  actions after you pick.
• Generated images survive closing the chat. Reopening the window in
  the same page load rebuilt empty cells where the images had been.
• A bad image key reports as a bad key. Leonardo answers 500 rather
  than 401, which the connection test read as success.
• Voice retention stopped stalling. Foundry core has no file-delete
  API, so the cleanup sweep hung on its first stale clip and never
  reached the rest. It now reports honestly instead of waiting forever.

Internal

• PROTOCOL_VERSION stays 1 — every shared-schema change this release is
  additive-optional. Tool count 207 → 209 across 25 domains
  (generate-actor-art, generate-item-art).
• A model-catalog drift sensor (npm run catalog:drift) diffs the seeded
  model lists, capability patterns, and pinned sunset dates against every
  live provider catalog, and runs as a release step. Every catalog fetch
  now goes through one shared layer.
• Dependency hygiene: nanoid raised past GHSA-2v37-7h3g-55p8,
  @hono/node-server past GHSA-frvp-7c67-39w9, @orama/orama pinned
  exact.