Skip to main content

Stream Deck for Foundry VTT

Set up Stream Deck with Foundry VTT

Connect the Stream Deck plugin to the JDR Ninja module, test a first key, then prepare keys that are useful during play: change scenes, reveal clues, track tension.

What you can set up

The examples below describe practical uses during a game. If your installation already works, go straight to the one that interests you.

What you need

Prepare Foundry V14 or later, the enabled JDR Ninja module, the Stream Deck application, its JDR Ninja plugin and Node.js 24. The Foundry server may be remote, but open Foundry in a browser on the computer where Stream Deck runs.

Install the Foundry module

Install the plugin

Public distribution is being prepared. If you have a development build, install its .streamDeckPlugin file in the Stream Deck application. To set up the local connection, open a terminal in the source stream-deck directory and install dependencies with the following command.

npm ci

If you received a .tgz archive, extract it, open a terminal in its directory and use this command instead. Node.js 24 must be installed separately.

npm install --omit=dev --ignore-scripts

The local connection stays active as long as this terminal is open, and it does not start by itself. Keep this window open while playing.

Prepare the local connection

Run initialization with the first command. Enter the exact address of Foundry as it appears in the browser, such as http://localhost:30000 or https://foundry.example.net, with no path or trailing slash. Copy the generated pairing key: you will enter it in Foundry and in the plugin. Then start the local connection with the second command.

npm run companion:init
npm run companion

The configuration is saved in your user profile, at one of the paths below. Initialization will not overwrite an existing file. To change the Foundry address, the port or the key, stop the local connection with Ctrl+C, edit the configuration file and restart it. If the key changes, enter the new key in Foundry and in the plugin.

  • Windows : %LOCALAPPDATA%\JDR Ninja\companion.json
  • macOS / Linux : ~/.config/jdr-ninja/companion.json

Connect Foundry

In Foundry, open the “JDR Ninja connections” window and click “Configure Stream Deck” on the Stream Deck card. Enter the address below and the pairing key, then click “Save and enable”: this button saves the connection and enables Stream Deck in this browser. The card shows “Ready” once the local connection is established.

ws://127.0.0.1:19114/jdr-ninja

Connect the Stream Deck plugin

Add the “Foundry Control” action to a key. In its inspector, enter the address below in “Connection address”, paste the same “Pairing key” and choose “Connect”. These connection settings are shared by all keys. The key field clears after saving.

ws://127.0.0.1:19114/stream-deck

This key is used only for the local connection between Stream Deck and Foundry. It differs from the Atlas connection token and your JDR Ninja account credentials. Do not paste any of those other credentials into the “Pairing key” field.

Choose the Foundry session

In Foundry world and browser, choose the intended world, user and browser. Wait for Ready and the available commands and documents. Each key stores its own session, command and parameters. It never automatically switches worlds, users or browsers.

Create and test your first command

In Command, choose Open actor and select an actor whose sheet you can open. Press the key once. Check that the sheet opens in Foundry and the inspector reports Completed. An admitted command may still be waiting for execution.

If an outcome is uncertain, the key may briefly display “?”. Check what happened in Foundry before pressing again. The next section shows how to prepare keys that are useful during play.

Reuse your keys during play

These examples start with fixed keys, then introduce one notion at a time: a list to choose among several documents, a variable to store a value, a combined command to change a value before acting in Foundry, arguments for your macros and the direct change of a character sheet field. The last two examples combine this change with variables: revealing journal pages for good and displaying the tension to players. Only the macro example needs a script. Variables and lists are created in Foundry; the commands that use them appear in the “Command” list preceded by “Advanced ·”, like “Update a document”.

Prepare the commands for your next scene

Your players leave the inn for the crypt. Prepare three keys for this change of location: the first activates the scene, the second starts its ambient sound and the third darkens the lighting.

Before you start

Sign in as GM: these three commands are reserved for the GM. The world already contains the scene and a playlist with the track you want.

In Foundry

No module setting is needed: these commands use fixed values, chosen directly in the inspector.

On Stream Deck

Prepare the commands for your next scene
Key Command Settings
Go to the crypt Activate scene “Document”: the crypt scene.
Crypt ambience Play or stop sound “Document”: the audio track. “Play”: Yes (the default is No, which stops the track).
Darken Set darkness “Document”: the crypt scene. “Value”: a number from 0 (full daylight) to 1 (total darkness), for example 0.7.

Try it and go back to the start

Press the three keys in order: the crypt scene appears for the players, the track starts and the lighting drops. The darkness key shows, as a percentage, the darkness of the scene open in your browser. To go back to the start, add a “Play or stop sound” key with “Play” set to No, and a darkness key set to 0.

Good to know

“Activate scene” shows the scene to all players. “View scene” only changes your own view, so you can prepare what comes next without the players seeing it. The three commands stay separate: to chain them on one key, you need a macro that contains them.

Browse your NPCs with the same keys

At the inn, your players question several NPCs. Two keys switch from one NPC to another and a third opens the sheet of the selected NPC. The open key works for the whole list: adding or reordering NPCs requires no change on Stream Deck.

Before you start

Any user can follow this example with their personal variables. The world already contains three actors whose sheets you can open.

In Foundry

  1. Open “Variables and lists (advanced)” in the module settings and choose “Personal”. In the “Value lists” tab, create the list “Inn NPCs” of type “Actor”. For each NPC, click “Add entry”, enter a “Label” and select the actor from the suggestions in the “Document UUID (fixed binding)” field. Save.
  2. In the “Variables” tab, create “Selected NPC”: “Value type” set to “Actor”, “Definition” set to “List selection”, “Linked list” set to “Inn NPCs” and the first NPC as “Default value”. Check “Wrap after the last entry” if the list should start over after the last NPC. Save.
  3. A new selection does not have a current value yet. In “Change current value”, choose “Reset to default”, then “Apply”.

On Stream Deck

Browse your NPCs with the same keys
Key Command Settings
Previous NPC Previous list entry “Variable (advanced)”: Selected NPC.
Next NPC Next list entry “Variable (advanced)”: Selected NPC.
Open NPC Open actor “Actor”: “Value source” set to “Variable (advanced)”, then the variable Selected NPC.

Try it and go back to the start

Press “Open NPC”: the sheet of the first NPC opens. Press “Next NPC”, then “Open NPC” again: the second NPC’s sheet opens. The selected NPC appears in the “Variables and lists (advanced)” window and under “Current preview” in the inspector. To go back to the first NPC, add a “Reset variable” key on the same variable.

Good to know

The keys show neither the portrait nor the name of the selected NPC: check the selection in Foundry or in the inspector. Without wrapping, “Next list entry” does nothing on the last NPC.

Reveal clues in order

Your players investigate in the crypt and you want to show them three clues in the planned order. After the first clue, one key is enough to move to the next clue and show it to your players, with no macro.

Before you start

Sign in as GM: showing a page is reserved for the GM, who must also own it. Prepare three journal pages, one per clue, and give players at least the Observer permission on each. Players must be connected to receive the page.

In Foundry

  1. In “Variables and lists (advanced)”, choose “Personal”: that is enough for your own keys. Create the list “Crypt clues” of type “Journal page” and add the three pages in the order you want to show them.
  2. Create the variable “Current clue”: “Value type” set to “Journal page”, “Definition” set to “List selection”, this list as “Linked list” and the first page as “Default value”. Leave “Wrap after the last entry” unchecked.
  3. Save, then apply “Reset to default” in “Change current value”.

On Stream Deck

Reveal clues in order
Key Command Settings
Previous clue Previous list entry “Variable (advanced)”: Current clue.
Next clue Next list entry “Variable (advanced)”: Current clue.
Show clue Share journal page “Document”: “Value source” set to “Variable (advanced)”, then the variable Current clue. “Audience”: Players.
Next clue and show Change variables and run command “Add variable change”: “Operation” set to “Next list entry” (the default is “Toggle variable”), “Variable (advanced)” set to Current clue. “Foundry command”: “Share journal page”, with the same settings as “Show clue”.

Try it and go back to the start

First try the first three keys separately to check the selection and the recipients. During play, show the first clue with “Show clue”, then use “Next clue and show”: with each press, the next page is selected and shown to the connected players. Starting with the combined key would skip the first clue. To replay the investigation, apply “Reset to default”: the current clue becomes the first one again, but pages already shown are not taken back from the players and their permissions do not change.

Good to know

After the last clue, the combined key no longer changes page and shows the last one again. If a player does not have the Observer permission, the command is refused and the current clue does not change. The “Show without changing ownership” option shows the page once without changing those permissions.

Announce the tension level

In a horror game, you raise the tension when the situation worsens. One key adds 1 to the counter and announces the new level in the chat, for example “Tension: 3 / 6”. You decide when to press: no game event raises the counter by itself.

Before you start

Any user can create this personal variable and write in the chat. No document is needed.

In Foundry

In “Variables and lists (advanced)”, under “Personal”, create the variable “Tension”: “Value type” set to “Number”, “Definition” set to “Stored value”, “Minimum” 0, “Maximum” 6, “Default value” and “Current value” 0. Check “Clamp increments and decrements to bounds”. Save.

On Stream Deck

Announce the tension level
Key Command Settings
Raise tension Increase variable “Variable (advanced)”: Tension. “Adjustment”: 1 (the default is 0, which changes nothing).
Lower tension Decrease variable “Variable (advanced)”: Tension. “Adjustment”: 1.
Reset to zero Reset variable “Variable (advanced)”: Tension.
Raise and announce Change variables and run command An “Increase variable” change on Tension, “Adjustment” 1. “Foundry command”: “Send chat message”. “Chat message”: “Value source” set to “Compose text (advanced)”, then three parts in order: the text “Tension:” followed by a space, the variable Tension and the text “/ 6” preceded by a space.

Try it and go back to the start

First check the first three keys: the value of Tension changes in the “Variables and lists (advanced)” window. Then, with the counter at 2, press “Raise and announce”: the counter goes to 3 and the chat shows “Tension: 3 / 6”. The message is public and sent under your name. “Reset to zero” brings the counter back to 0 without removing the messages already sent.

Good to know

At the maximum, the counter stays at 6, but the message is still sent. If sending the message fails, the new value may remain saved and the key displays “!”: check the counter and the chat in Foundry before pressing again.

Roll with a variable bonus

An ally helps the character or a high position makes their shot easier: the bonus changes from one scene to the next. Save this bonus in a variable: a single key then rolls 1d20 plus the current bonus. Each press uses the value of the moment.

Before you start

Any user can roll dice and create their personal variables. No document is needed.

In Foundry

Under “Personal”, create the variable “Situation bonus”: “Value type” set to “Number”, “Definition” set to “Stored value”, “Minimum” 0, “Maximum” 5, “Default value” and “Current value” 0. Check “Clamp increments and decrements to bounds”. Save.

On Stream Deck

Roll with a variable bonus
Key Command Settings
Increase bonus Increase variable “Variable (advanced)”: Situation bonus. “Adjustment”: 1.
Reduce bonus Decrease variable “Variable (advanced)”: Situation bonus. “Adjustment”: 1.
Zero bonus Reset variable “Variable (advanced)”: Situation bonus.
Roll with bonus Roll dice “Dice expression”: “Value source” set to “Compose text (advanced)”, then the text “1d20 +” and the variable Situation bonus. “Roll visibility”: “Only me” to practice.

Try it and go back to the start

Choose the “Roll dice” command in the “Foundry Control” action: the Stream Deck action called “Roll Dice” is a different action, meant for the overlay. Press “Roll with bonus”: the result appears in the Foundry chat, for you alone. Increase the bonus twice and press again: the roll uses 1d20 + 2. When the table should see the roll, choose “Everyone”. “Zero bonus” brings the bonus back to 0.

Good to know

This is a generic dice roll: it does not replace the attack or damage rolls of your game system, and the variable does not follow any actor characteristic. The expression accepts dice, numbers and simple operations, but not modifiers such as “kh”: a “2d20kh1” roll is refused.

Pass values to a macro

You already have a script macro that acts on an actor according to a quantity. Instead of copying it for each case, declare its arguments: each key runs the same macro with its own actor and its own quantity.

Before you start

This is the only example that requires a script. The macro must be a script macro that you own and can execute. The module provides no ready-made macro and does not modify your script.

In Foundry

  1. Open “Compatible macros (advanced)”, choose the macro, then “Configure macro”. With “Add argument”, declare for example “target” of type “Actor” and “amount” of type “Number”. An argument name starts with a letter and contains no accented characters or spaces. Check “Required”, or check “Use a default value” and set the “Default value”. Then click “Save”.
  2. In the script, read the values from scope.jdrNinja.arguments. A document is passed there as a UUID; a number, text or boolean is passed as is.
  3. End the script with the acknowledgement line shown in the “Compatible macros (advanced)” window. Without it, the key reports an uncertain outcome, even if the macro worked.

On Stream Deck

Pass values to a macro
Key Command Settings
First case Execute macro “Document”: your macro. Check “Macro arguments (Advanced)”, then “target”: a first actor and “amount”: 2.
Second case Execute macro The same macro, with “amount”: 5. For “target”, set “Value source” to “Variable (advanced)”, then choose the variable Selected NPC: the macro then acts on the NPC selected in the NPC example.

Try it and go back to the start

Press each key and check in Foundry the macro’s effect on the actor concerned. The inspector shows “Completed.” once the acknowledgement is received. Going back to the starting state depends on what your macro does: the module undoes nothing.

Good to know

The declaration window creates no script: it only describes the expected values. A macro with no declared arguments receives none, and the inspector then asks you to choose a macro that declares compatible arguments in Foundry.

Give inspiration

One of your players has just pulled off a daring move and deserves inspiration. In a D&D5e game, a single key turns inspiration on in their character’s sheet; a second press turns it off.

Before you start

The GM can give inspiration to any player. A player can do it only for a character they own: in every other case, Foundry refuses the change. The world uses the D&D5e system.

In Foundry

If you have not done so yet, assign the player’s character to them in Foundry’s “User Configuration” (right-click their name in the player list), under “Player Character”: the key acts on this assigned character. No other module setting is needed.

On Stream Deck

Give inspiration
Key Command Settings
Inspiration Update a document “Document” set to “Player’s assigned character”, then “Foundry user”: the player concerned. “Add change”: “Field path” system.attributes.inspiration, “Operation” set to “Toggle true/false”.

Try it and go back to the start

Open the character’s sheet in Foundry, then press “Inspiration”: the sheet shows that the character has inspiration. Press again: inspiration is removed and the sheet returns to its starting state. Each press inverts the current state: if the character already had inspiration, the first press removes it.

Good to know

The path system.attributes.inspiration is specific to D&D5e: other game systems use other fields, and the module does not check the path you enter. If the field does not exist, the key shows an alert and the inspector reports that a field does not hold the expected type.

Reveal clues for good

In “Reveal clues in order”, the key shows a page that players already have permission to open. Here, each clue page stays hidden in their journal until you reveal it: one key reveals the current clue, another moves to the next clue and reveals it, with no macro.

Before you start

Sign in as GM: Foundry refuses a player’s request to change a page’s permission. You need the list “Crypt clues” and the variable “Current clue” from the example “Reveal clues in order”: create them first by following its “In Foundry” steps.

In Foundry

  1. Right-click the journal that contains the clue pages, choose “Configure Ownership” and set “All Players” to “Observer”: without it, that journal does not appear in the players’ Journal tab.
  2. For each clue page, right-click it in the journal’s page list, choose “Configure Ownership” and set “All Players” to “None”: a newly created page inherits the journal’s permission and would therefore be visible to them. This setting replaces the Observer permission asked for in the example “Reveal clues in order”.

On Stream Deck

Reveal clues for good
Key Command Settings
Reveal current clue Update a document “Document”: “Value source” set to “Variable (advanced)”, then the variable Current clue. “Add change”: “Field path” ownership.default, “Operation” set to “Set a value”, “Value type” set to “Number”, then “Value” 2, which is the Observer level.
Reveal next clue Change variables and run command “Add variable change”: “Operation” set to “Next list entry” (the default is “Toggle variable”), “Variable (advanced)” set to Current clue. “Foundry command”: “Update a document”, with the same settings as “Reveal current clue”.
Hide clue Update a document Optional. The same settings as “Reveal current clue”, but with the value 0, which is None: the key hides the current clue. The value -1 would make the page visible, because it would inherit the journal’s Observer permission.

Try it and go back to the start

Press “Reveal current clue”: the first clue appears in the players’ journal and the other pages stay hidden. Then press “Reveal next clue”: with each press, the current clue moves to the next page, which is revealed. Starting with the combined key would skip the first clue. The players’ journal and the journal windows they have open update immediately, with no reload, and revealed pages stay in their journal. To replay the investigation, set each clue page back to None in Foundry, then apply “Reset variable” to Current clue.

Good to know

On the last clue, the combined key changes nothing. “Reset variable” brings the current clue back to the first one, but does not hide pages already revealed. If a player presses these keys, Foundry refuses the change. A combined command runs a single Foundry command: revealing a page and showing it to players with “Share journal page” takes two keys. A hidden page is hidden only in the players’ interface: its content is already in their browser, so it is not a secret.

Show the tension to players

In “Announce the tension level”, the level is announced in the chat. Here, you show it in the name of a journal that players see in their journal list: one key raises the tension and renames the journal, for example “Tension: 3 / 6”. You decide when to press.

Before you start

Sign in as GM: Foundry refuses a player’s request to rename a journal they do not own. You need the variable “Tension” from the example “Announce the tension level”: create it first with its “In Foundry” step.

In Foundry

Create a journal named “Tension”, right-click it, choose “Configure Ownership” and set “All Players” to “Observer”: without it, it does not appear in the players’ Journal tab.

On Stream Deck

Show the tension to players
Key Command Settings
Raise and show Change variables and run command An “Increase variable” change on Tension, “Adjustment” 1. “Foundry command”: “Update a document”. “Document”: the journal “Tension”, chosen from the list. “Add change”: “Field path” name, “Operation” set to “Set a value”, “Value type” set to “Compose text (advanced)”, then three parts in order: the text “Tension:” followed by a space, the variable Tension and the text “/ 6” preceded by a space.

Try it and go back to the start

With the counter at 2, press “Raise and show”: the counter goes to 3 and the journal is renamed “Tension: 3 / 6”, and the new name appears in every player’s Journal tab immediately, with no reload. To go back to the start, reset the counter with the “Reset to zero” key from the example “Announce the tension level”, then rename the journal “Tension” in Foundry.

Good to know

At the maximum, the counter stays at 6 and the journal name does not change. The key renames the journal itself, not one of its pages: the journal list shows journal names, while a page name only appears inside the open journal.

Create variables and lists in Foundry

After reconnecting

When the Foundry browser reconnects, it appears as a new session. Select it again on every affected key, including after restarting the local connection. If only the plugin reconnects, it can rediscover a Foundry session that stayed connected. If you press Ctrl+C in the terminal, the local connection stops and the current sessions are interrupted.

Troubleshooting

  • No connection: check that the terminal window is still open, that the addresses you entered match those given in this guide, and that Foundry and the plugin use the same key.
  • Foundry refused or missing: check the exact allowed origin in companion.json and the switch on the Stream Deck card in this browser. A different server address changes the origin.
  • Foundry over HTTPS: the browser may require wss and a trusted local certificate. Set tlsCert and tlsKey to absolute paths to PEM files, then use wss in Foundry and in the plugin. The certificate must cover the local address and be trusted by the Foundry browser and by Stream Deck. It is not installed automatically.
  • Missing or synchronizing session: wait until it is ready, then reselect the world, user and browser on the key.
  • Refused command or missing document: check the Foundry account's permissions and target document. Selecting a session grants no additional rights.
  • Overlay test unavailable: check JDR Ninja account connection, overlay enablement in Foundry and Premium verification. The local key does not confirm this access.
  • Uncertain or partial result: inspect the affected sheet, scene, variables or combat in Foundry before pressing again. An interruption can occur after execution. The plugin does not automatically retry the command.

Frequently asked questions

Why does the key disappear from the field?

The plugin clears the field after saving so the stored key is not displayed. This does not mean the connection was removed.

Why must I select the session again?

A Foundry reconnection creates a new identity. Keys keep their previous choice to avoid sending commands to another world, user or browser.

Can I repeat a command with an uncertain result?

Check Foundry first. The command may already have executed despite the connection interruption. Every new press is a new command.

Can a key show the value of a variable?

No. Keys show the pause state, the darkness level, a token’s resource bar or, briefly, the result of a command. The value of a variable or the selected NPC can be checked in Foundry or in the inspector.

Stream Deck for Foundry VTT The JDR Ninja module for Foundry