Back to Guides

Foundry VTT Integration Guide

Foundry v12+ for in-context rolls · v10/v11 for chat-only

RollSight uses Foundry's Manual dice setting. When you set a die type to Manual, Foundry opens a "waiting for dice" dialog. RollSight captures that dialog and fills it with your physical roll (or you can complete with digital dice). No separate RollSight option in the dice menu; just choose Manual and the module does the rest.

Play sessions: open Session → Set up or Start Session, choose Foundry, then pick how rolls reach the table: RollSight cloud room (paste one shared room key; best for The Forge and browsers, no add-on) or This PC (local bridge) (HTTP bridge on your machine + desktop polling or the VTT Bridge extension). Details are in Play sessions below.

Manual rolls don't let players cheat

When you allow Manual rolls for your players, every manual roll dialog is handled by the RollSight module. The player cannot type in a number. They must either:

  • Roll real dice in RollSight and send the result, or
  • Click Complete with Digital Rolls to use Foundry's built-in random roll.

So enabling Manual for RollSight does not open the door to fake values. RollSight captures the dialog and only accepts a RollSight result or an explicit digital roll.

What you get

Once the module is installed, enabled, and Dice Configuration is set to Manual for the dice you use, here's what happens:

  • In-context rolls (v12+): When you click Roll on an attack, spell, or save (or type /roll 1d20 in chat), Foundry opens a "Roll in RollSight" style dialog. You roll in the RollSight app; the result fills in and the roll completes in the same context, with no separate chat line.
  • Chat commands: /roll, /r, /gmroll, /blindroll, /selfroll (and formulas like 1d20, 2d20kh + 5) open the same waiting dialog; RollSight fills it and the result posts with the correct visibility.
  • Fallback to chat: If no roll is waiting (e.g. you roll in RollSight without a Foundry prompt open), the roll is sent to chat so it's never lost. You can turn this off in module settings.
  • Initiative: When combat has started and a combatant has no initiative yet, a single d20 from RollSight can be applied to that combatant's initiative.
  • Complete with digital rolls: In the waiting dialog, players can choose to fill any remaining dice with Foundry's digital RNG instead of rolling more in RollSight.
  • 3D dice: When a roll is fulfilled or sent to chat, Foundry's 3D dice (or Dice So Nice / dddice) animate if enabled. No extra setup.

Foundry v10/v11 do not have the Manual/fulfillment flow; on those versions, RollSight rolls go to chat only.

How it works in one sentence

You set dice to Manual in Foundry; when a roll uses that die, Foundry shows a manual-entry dialog. The RollSight module replaces that with a "Roll in RollSight" prompt and feeds your physical (or digital) result into Foundry so the roll completes in context.

Play sessions: cloud room or local bridge

When you send rolls to Foundry, you choose one delivery path. RollSight cloud room sends rolls over the internet to rollsight.com, with no local HTTP bridge and no browser extension. This PC (local bridge) uses a small HTTP server on your machine (default 127.0.0.1:8766) that only runs while a matching play session is active.

Option A: RollSight cloud room (recommended for The Forge)

Best when Foundry runs in a browser (The Forge, self-hosted, etc.) and you want no browser add-on and no local bridge port. Everyone uses the same room key: the GM creates it in Foundry; each person with the RollSight app pastes that key when starting a play session.

  1. In Foundry (GM): Configure Settings → module settings for RollSight Real Dice Reader → click Create RollSight room. The key is saved for the world and copied to your clipboard. Share it with players (voice, chat, etc.).
  2. In RollSight (each person who rolls): Session → Set up or Start Session → New session → Send rolls to: Foundry → select RollSight cloud room (paste the key from your GM) → paste the full key (starts with rs_) → Start.
  3. The same key should appear under RollSight cloud room key in Foundry module settings for that world (players receive it automatically once the GM has set it). Foundry polls rollsight.com in the background, with no extension install.
  4. End Session in RollSight when you're done; start again with the same saved session or re-enter the key next time.

Option B: This PC (local HTTP bridge)

The bridge listens on 127.0.0.1:8766 only while a play session is running with Send rolls to: Foundry and This PC (local bridge) selected, and (for that path) Let Foundry talk to this app enabled. Use the VTT Bridge browser extension or desktop-bridge polling in the module; see Connecting RollSight to Foundry below.

  1. Open the Play session dialog: Session → Set up or Start Session.
  2. Under Send rolls to: choose Foundry, then This PC (local bridge, browser add-on or Foundry desktop app).
  3. Enable Let Foundry talk to this app, set the port to match Settings → Integrations → Foundry / VTT, and choose browser vs desktop so it matches your Foundry client.
  4. Copy Link for Foundry into the module's roll-request field if you use HTTP roll requests from Foundry to RollSight (port 8765 by default, separate from the bridge).
  5. Optionally enable replay clips, camera stream, or OBS shortcuts for this session.
  6. Click Start. End Session stops the bridge.

Session types are separate

Each session picks one destination: Foundry, Discord, or This PC only. A Discord session doesn't send to Foundry; This PC only keeps rolls local. Use Saved session → Continue to reuse a prior setup.

The small roll-request HTTP server (default 8765) starts with the RollSight app so Foundry can POST roll prompts to your PC. With a cloud room session, physical results are published to rollsight.com instead of the local bridge queue.

Prerequisites

  • Foundry VTT (v12+ recommended for in-context rolls; v10/v11 supported for chat-only)
  • The RollSight desktop app on each machine where someone rolls physical dice, with an active Foundry play session (Send rolls to: Foundry). For a cloud room, no local HTTP bridge is required on that PC. For a local bridge session, the bridge listens on 127.0.0.1:8766 while the session runs.
  • RollSight Real Dice Reader module installed and enabled in your world (see Step 1–2)
  • One of the connection methods below: cloud room (world key + HTTPS poll), desktop bridge polling, or VTT Bridge extension, configured per Foundry client

With a cloud room, rolls go from RollSight to rollsight.com and Foundry picks them up over HTTPS (no extension). With a local bridge, rolls queue on your PC and Foundry uses desktop polling or the browser extension as before.

Connecting RollSight to Foundry: three paths

Start the right play session in RollSight (cloud room vs local bridge), then match module settings on each Foundry client. Module options are per client (Configure Settings → Module Settings → RollSight Real Dice Reader).

Method 1: RollSight cloud room

Best for: The Forge, browsers, groups that don't want a browser extension

Requires a cloud room play session in RollSight (same rs_… key as in Foundry). Turn off desktop bridge polling on clients that use the cloud; the module polls rollsight.com instead. Do not install the VTT Bridge extension for this path.

  1. GM: create or paste the room key under RollSight cloud room key in module settings (or use Create RollSight room).
  2. Everyone: paste the same key in RollSight when starting a Foundry play session with RollSight cloud room selected.
  3. Leave Desktop bridge polling off unless you also use the local bridge on that machine (you normally don't mix both).
  4. Reload the world after changing the key. Optional: Cloud room API (advanced) only for development; leave empty for production.

Method 2: Desktop bridge (local polling)

Best for: GMs and players using the Foundry desktop application

The Foundry app is built with Chromium but does not use your normal browser, so the RollSight browser extension does not apply. Instead, the module polls the same HTTP bridge the extension would use (no extension required).

  1. Install and enable the RollSight module (Steps 1–2).
  2. Open Configure Settings → Module Settings → RollSight Real Dice Reader.
  3. Turn on Desktop bridge (Foundry app: poll HTTP bridge).
  4. Leave Desktop bridge base URL as http://127.0.0.1:8766 unless you changed the bridge port in RollSight.
  5. Keep RollSight Real Dice Reader (this client) enabled so this Foundry client processes rolls.
  6. Reload the world. With debug logging on, you should see a log line that polling is enabled for 127.0.0.1.

Windows tip

Use 127.0.0.1, not localhost, in the bridge URL if you have trouble. The RollSight bridge listens on IPv4 loopback; some systems resolve localhost to IPv6 first and the connection fails silently.

Do not enable desktop bridge polling and the VTT Bridge extension on the same machine for the same roll queue; both consume the bridge and can steal each other's rolls.

Method 3: RollSight VTT Bridge (browser extension)

Best for: Foundry in Chrome or Edge (The Forge, self-hosted in browser, localhost:30000, etc.)

Install the RollSight VTT Bridge extension from the Chrome Web Store (or load unpacked for development). The extension polls 127.0.0.1:8766 and forwards rolls into the Foundry tab via the module's script.

  1. Install the module (Steps 1–2).
  2. Keep Desktop bridge polling off on this browser if you use the extension. Enabling both on the same machine makes two consumers fight over the same queue.
  3. Install RollSight VTT Bridge and allow it for your Foundry site (e.g. *.forge-vtt.com or your host).
  4. Open your Foundry world in that browser with the extension enabled; reload after installing the module.
  5. Confirm RollSight Real Dice Reader (this client) is on in module settings.

Optional: Foundry in a browser can use desktop bridge polling instead of the extension (same fetch loop as the app). Choose one delivery method per machine, not extension + polling together.

Remote players each run RollSight on their own PC and use the extension in their browser so their Foundry session receives their rolls. The GM can use desktop polling in the Foundry app while players use the extension. That mix is fine because it's different machines and different clients.

Quick comparison

  • Cloud room → set the world key in Foundry + paste the same key in RollSight; no extension; no local bridge queue on the RollSight PC.
  • Foundry desktop app + local bridge session → enable Desktop bridge polling; no extension.
  • Foundry in a browser + local bridge session → install RollSight VTT Bridge; leave desktop polling off on that client.
  • Local bridge methods share the same HTTP bridge on 127.0.0.1:8766; cloud room uses HTTPS to rollsight.com instead.

Step 1: Install the module

Manifest URL (recommended for The Forge and most hosts)

On The Forge and similar hosts you don't have filesystem access; use the manifest URL so Foundry can install the module directly.

  1. In Foundry, go to Setup → Add-on Modules.
  2. Click Install Module.
  3. In Manifest URL, paste this URL exactly:
    https://raw.githubusercontent.com/smegill/rollsight-integrations/main/rollsight-integration/module.json
  4. Click Install, then close the dialog.

Foundry will fetch the module from the manifest. The module name in the list will be RollSight Real Dice Reader.

Manual install (self-hosted with file access)

  1. Download the rollsight-integration folder (e.g. from the releases page or clone the repo).
  2. Place it in Foundry's Data/modules/ directory (e.g. Data/modules/rollsight-integration/).
  3. Restart Foundry or reload the world.

Data paths: Windows %localappdata%\FoundryVTT\Data\; macOS ~/Library/Application Support/FoundryVTT/Data/. Self-hosted Foundry on other platforms may use a different path; see Foundry's documentation for your host.

Step 2: Enable the module

  1. Open your world in Foundry (as GM).
  2. Go to Settings (gear icon) → Manage Modules.
  3. Find RollSight Real Dice Reader (or RollSight Integration) and check the box.
  4. Click Update Modules or close, then reload the world (refresh the browser or use Reload World).

The GM enables the module once; it then runs for all connected clients. On cloud hosts (e.g. The Forge), ensure the module is available to players if you want them to use RollSight. It usually is by default once the GM enables it.

Step 3: Allow players to use Manual rolls (permissioning)

For RollSight to work, each player who rolls physically must set their Dice Configuration to Manual for the dice they use. Foundry only shows the Manual option if the player has permission to configure dice. As GM, you need to grant that permission.

Why this step matters

Dice Configuration is per user. If only the GM has access to it, only the GM can set Manual, and only the GM's rolls would wait for RollSight. Giving players permission to configure dice (and choose Manual) lets each player use RollSight for their own rolls.

  1. Go to Setup → Game Settings (or Configure Settings), then open the Core or Permission section where player roles are defined.
  2. Find the permission that controls whether players can change Dice Configuration or select Manual Rolls. In Foundry v12 this is often under a "Configure Dice" or "Dice Configuration" capability for the Player (or Trusted Player) role.
  3. Enable that permission for the role(s) that should use RollSight (e.g. Player, Trusted Player).
  4. On The Forge: In your Forge dashboard, check Game Settings or Player Permissions for anything related to "Dice" or "Manual rolls" and ensure players are allowed to configure dice. If Dice Configuration is GM-only on your host, you may need to enable a Forge-level option so players can access it.

After this, each player can open Setup → Dice Configuration while logged in and set their dice to Manual (see Step 4). You can reassure them: allowing Manual does not allow cheating, because RollSight captures every manual dialog (see the green callout at the top).

Step 4: Dice Configuration (set to Manual)

For Foundry to wait for RollSight instead of rolling digitally, each die type that players will roll physically must be set to Manual. The RollSight module then feeds physical rolls into Foundry's manual-roll flow. This is the main configuration step for in-context rolls.

  1. Each player who will use RollSight should log in as themselves, open Setup → Dice Configuration (or Game Settings → Configure Dice, depending on version).
  2. For each die they want to roll physically, set the fulfillment method to Manual:
    • d20: attacks, saves, ability checks, initiative
    • d4, d6, d8, d10, d12, d100: set these too if they roll damage or other dice in RollSight
  3. Leave any die they don't roll physically as Default (digital).
  4. Click Save Changes, then do a full world reload (F5 or refresh).

Tip

There is no separate "RollSight" option in the dice dropdown. RollSight works with Foundry's built-in Manual option: when Manual is selected, the RollSight module intercepts the manual-entry dialog and replaces it with a "Roll in RollSight" prompt, then feeds the result in.

MidiQoL, Dice So Nice, dddice & other modules

RollSight plugs into Foundry's standard roll and manual-fulfillment flow. That means it works with the same dialogs and chat messages that other modules use. No special configuration is required for these popular add-ons:

  • MidiQoL: MidiQoL must be set to allow manual (not automatic) rolling. If MidiQoL is set to automatic, it performs the roll itself and never opens Foundry's roll dialog, so the RollSight pipeline is skipped. In MidiQoL settings, choose manual rolling so that when a player clicks Roll, Foundry opens the "waiting for dice" step and the RollSight dialog appears. The player who clicks Roll must also have Dice Configuration set to Manual for the relevant dice (e.g. d20 for attacks).
  • Dice So Nice: RollSight posts rolls through Foundry's normal chat/roll API. If Dice So Nice is enabled for your world, RollSight rolls will trigger 3D dice animations like any other roll. No extra Dice So Nice configuration.
  • dddice: Same idea. If dddice is handling roll display for your game, RollSight's rolls are just normal Foundry rolls and will be picked up by dddice. No special dddice settings for RollSight.

If a specific dialog or module still rolls digitally, that flow may not use Foundry's standard Roll.evaluate() path. In that case, use Fallback to chat (roll in RollSight and the result appears in chat) or type the roll in chat (e.g. /roll 1d20).

Step 5: Module settings (optional)

In Configure Settings, scroll to RollSight Integration (or RollSight Real Dice Reader). These options control how Foundry receives rolls. The RollSight app needs an active Foundry play session (cloud room or local bridge) whenever you want rolls sent online.

  • RollSight cloud room key / Create RollSight room: For the cloud path. GMs can generate a key in one click; paste the same key in RollSight when starting a session. Leave empty if you only use the local bridge.
  • Cloud room API (advanced): Leave empty for production (uses rollsight.com). For development only.
  • Desktop bridge (Foundry app: poll HTTP bridge): Turn on for the Foundry desktop application when using a local bridge play session, not when using a cloud room on that client.
  • Desktop bridge base URL: Default http://127.0.0.1:8766. Change only if you changed the bridge port in RollSight (Settings → Integrations → Foundry / VTT and the play session dialog should stay in sync).
  • RollSight Real Dice Reader (this client): Per-client master toggle. It should be on for anyone using RollSight from this Foundry session.
  • Replace manual dice dialog with RollSight: When Foundry opens the manual dice dialog, replace it with a RollSight prompt (recommended: on).
  • Fallback to chat: When no roll is waiting, send RollSight rolls to chat (default: on).
  • Apply RollSight rolls to pending initiative: Use a single d20 from RollSight for initiative when combat has started (default: on).
  • Debug logging: Turn on to troubleshoot in the developer console (F12 in browser; similar tools in the Foundry app).

Step 6: Test the integration

After you configure a cloud room or local bridge session (and matching module settings), with RollSight running:

  1. In RollSight: Play session → Foundry → either RollSight cloud room (paste key) or This PC (local bridge) (enable Let Foundry talk to this app when using the bridge) → Start. Confirm the status shows Foundry.
  2. Reload the world after enabling the module and setting Dice Configuration (and permissioning).
  3. In chat, type /roll 1d20 and send.
  4. A dialog should appear: "Roll 1d20 in RollSight…" with a Complete with Digital Rolls button.
  5. Roll a d20 in RollSight (or click Complete with Digital Rolls); the result should fill in and the roll post to chat.
  6. Try an attack or save from a character sheet (or MidiQoL); the same RollSight dialog should appear and the roll should complete in context.

If the dialog appears and rolls complete as above, your Foundry setup is correct. Each player needs Dice Configuration set to Manual for the dice they roll, plus either a cloud room (same key in RollSight and Foundry) or local bridge delivery (desktop bridge polling or VTT Bridge, not both on the same client).

Troubleshooting

Manual not available or greyed out in Dice Configuration

  • The GM must give players permission to configure dice / use Manual rolls (Step 3). Check Game Settings or your host's Player Permissions.
  • Use Foundry v12+ for Dice Configuration and the manual-fulfillment flow.
  • Ensure RollSight Real Dice Reader is enabled in Manage Modules and you've reloaded the world.

Foundry rolls digitally instead of waiting

  • Dice Configuration is per user. The player who rolls must open Setup → Dice Configuration as that player, set the die (e.g. d20) to Manual, Save, and reload.
  • If Manual is greyed out: enable the "Configure Dice" / Manual-rolls permission for that player's role (Step 3).

Rolls not appearing in Foundry

  • In RollSight, confirm a play session is started with Send rolls to: Foundry. For a local bridge session, Let Foundry talk to this app must be on. For a cloud room session, the bridge is not used. Ensure the room key matches Foundry module settings.
  • Cloud room: Same rs_… key in RollSight and in Foundry; leave Desktop bridge polling off. Check your network; rollsight.com must be reachable from the browser.
  • Foundry desktop app (local bridge): Enable Desktop bridge (poll HTTP bridge) and set the base URL to http://127.0.0.1:8766 (avoid localhost on Windows if polls never return rolls).
  • Foundry in browser (local bridge): Install RollSight VTT Bridge and turn off desktop bridge polling on that client so only one path consumes the queue.
  • Confirm the RollSight app is running and the camera pipeline is working; for local bridge, the bridge port matches Settings and the module.
  • Enable Debug logging in module settings, reload, then open the developer console (F12) when you roll and look for Received roll or bridge / poll errors.

Dialog doesn't appear for /roll 1d20

  • Confirm Dice Configuration has Manual for that die for the user who is rolling, and you've saved and reloaded.
  • Foundry v12+ is required for the "wait for RollSight" flow; on v10/v11, rolls go to chat only.

MidiQoL or other dialog rolls digitally

  • MidiQoL must use manual rolling, not automatic. If MidiQoL is set to automatic, it rolls digitally and never opens the RollSight pipeline. In MidiQoL settings, enable manual rolling so Foundry opens the roll dialog.
  • The player who clicks Roll must have Setup → Dice Configuration set to Manual for the relevant dice (e.g. d20), then Save and reload.
  • If it still rolls digitally, that dialog may not use Foundry's standard roll path; use Fallback to chat or type the formula in chat (e.g. /roll 1d20).

Next steps

  • Remind players to set Dice Configuration to Manual for the dice they use (d20, d6, etc.) and that Manual + RollSight does not allow cheating. RollSight captures the dialog.
  • Share the room key (cloud room) or confirm each person uses the VTT Bridge / desktop bridge setup (local bridge). Everyone should start a Foundry play session in RollSight when they play so rolls are delivered.