Skip to main content

The JDR Ninja module for Foundry

Control Foundry VTT with Stream Deck

Control your character sheets from your Stream Deck.

Activate a scene, show a clue, make a roll or edit a character sheet directly from Stream Deck. The JDR Ninja plugin sends your commands to Foundry VTT, and variables let you reuse the same keys throughout the game.

Edit your character sheets

A key can change any field that Foundry lets you edit: a character’s inspiration, hit points or currency, an item’s charges, the name of a journal page. Up to 16 fields change in a single update.

  • Five operations: set a value, increase, decrease, toggle true/false, remove a field.
  • The target of your choice: a specific document, a player’s assigned character, the selected token or its actor, or a document given by a variable.
  • Fixed values or values taken from your variables: a bonus, a counter, a composed text.
  • Your Foundry permissions apply: the GM can edit anything, a player only what belongs to them.
  • Fields depend on the game system: you enter their path, for example system.attributes.inspiration in D&D5e. The module does not check this path.

Examples for your next game

Each example shows what it uses and links to its step-by-step setup in the guide.

Foundry commands

Change location in three keys

Activate the next scene, start its ambient sound and set its darkness, each command on its own key.

See the step-by-step example

Variables: list and combined command

Reveal clues in order

A list of pages and a combined command: move to the next clue and show it to your connected players, with no macro.

See the step-by-step example

Variables: counter and composed text

Announce the tension level

A counter from 0 to 6 saved in a variable: raise it and announce its new value in the chat.

See the step-by-step example

The commands

The plugin offers 40 commands: 31 for Foundry VTT, including document updates, and 9 for variables. Each command respects the permissions of the signed-in Foundry user, and commands marked GM are reserved for the game master.

Variables and lists

A list of NPCs or clues, a counter, a bonus: with variables and lists created in Foundry, a few keys are enough for the whole game. A combined command changes a value and then runs an action, for example moving to the next clue and showing it. Values and permissions are checked on every press.

Set variable
Gives the variable a new value.
Select list entry
Picks a specific entry from the linked list.
Next list entry
Moves forward one entry in the list and can wrap back to the start after the last one.
Previous list entry
Moves back one entry in the list.
Increase variable
Adds an amount to the number, within the set limits.
Decrease variable
Subtracts an amount from the number, within the set limits.
Toggle variable
Switches yes to no, or no to yes.
Reset variable
Gives the variable its default value back.
Change variables and run command
Applies up to 16 changes, then runs a Foundry command.
  • Three ways to define a variable: a stored value, a selection from a list, or a calculated value. A calculation can use other variables and the fields of a document, such as a character’s inspiration.
  • Thirteen value types: number, text, yes or no, actor, token, scene, journal, journal page, macro, playlist, audio track, roll table and combat.
  • Personal variables for your own keys, or variables shared by the whole table and managed by the GM.
  • In each field of a command, the value can come from a variable, from a text made of fixed parts and variables, from the character assigned to a player or from the selected token.
  • Arguments for your script macros: up to 16 values declared per macro, filled in differently on each key.

Variables are saved in Foundry’s settings, not in the browser.

game.settings flags.jdr-ninja.arguments

See the examples

Foundry VTT commands

Each command calls a Foundry VTT function, shown under its name: Foundry does the work, with its own rules and your permissions.

Actors and macros

  • Open actor

    Actor#sheet.render()
  • Execute macro

    Macro#execute()

Scenes

  • View scene

    Scene#view()
  • Activate scene GM

    Scene#activate()
  • Preload scene GM

    game.scenes.preload()
  • Set darkness GM

    Scene#update({ darknessLevel })

Journals

  • Open journal page

    JournalEntry#sheet.render()
  • Share journal page GM

    Journal.show()

Music and sounds

  • Play or stop sound GM

    Playlist#playSound() / stopSound()
  • Next or previous track GM

    Playlist#playNext()
  • Stop playlist GM

    Playlist#stopAll()
  • Set volume GM

    PlaylistSound#update({ volume })

Game and interface

  • Pause or resume GM

    game.togglePause()
  • Open sidebar tab

    ui.sidebar.changeTab()
  • Select tool

    ui.controls.activate()

Dice, tables and chat

  • Roll dice

    Roll#toMessage()
  • Draw from table

    RollTable#draw()
  • Send chat message

    ChatMessage.create()

Tokens and conditions

  • Select token

    Token#control()
  • Target token

    Token#setTarget()
  • Hide or reveal token GM

    TokenDocument#update({ hidden })
  • Adjust token resource

    Actor#modifyTokenAttribute()
  • Apply or remove condition

    Actor#toggleStatusEffect()

Combat

  • Start combat GM

    Combat#startCombat()
  • End combat GM

    DialogV2.confirm() + Combat#delete()
  • Next turn GM

    Combat#nextTurn()
  • Previous turn GM

    Combat#previousTurn()
  • Next round GM

    Combat#nextRound()
  • Roll initiative GM

    Combat#rollAll()

Overlay

  • Test overlay

    JDR Ninja server, Premium access

“Adjust token resource” only changes the token’s resource bar: it does not handle damage or healing according to each system’s rules. “End combat” asks for confirmation in Foundry.

What it looks like

These captures show module settings in a real Foundry browser and the plugin development inspector. They illustrate local configuration and do not certify physical Stream Deck hardware. The temporary port in the captures differs from the guide’s default port 19114.

Enable the connection in Foundry

In the module’s “Stream Deck” window, enter the connection address and the pairing key, then click “Save and enable”.

JDR Ninja module Stream Deck settings in Foundry: active local connection, French interface.

Configure a key

The command and its input fields depend on the selected session and Foundry user's permissions.

JDR Ninja development inspector: Foundry command and configuration fields, French interface.

How Stream Deck communicates with Foundry

  1. Stream Deck plugin
  2. JDR Ninja module in the Foundry browser

The Stream Deck plugin sends your commands to the JDR Ninja module over a local connection, in the Foundry browser you chose. Foundry executes the commands and checks the permissions of the signed-in user. That browser must stay open on the same computer as Stream Deck, but the Foundry server can be hosted elsewhere. The local connection uses its own pairing key: it asks for no JDR Ninja account token and does not replace any Foundry permission.

Each key stays tied to the world, user and browser you chose. The plugin distinguishes a completed command from a refused one or one with an uncertain outcome. If the outcome is uncertain, check Foundry before pressing again.

What you need

You need Foundry V14 or later with the JDR Ninja module enabled, the Stream Deck application with the JDR Ninja plugin, and Node.js 24 for the local connection. Each key must explicitly target a session.

Install the Foundry module

Permissions and access

Common.Free

Commands respect the Foundry permissions of the selected session. Overlay test carries a Premium marker and requires account connection, overlay enablement and server access verification. Other module features have separate conditions. No general subscription tier has been announced for local commands.

Frequently asked questions

What are variables for?

They store a value in Foundry: the chosen NPC, the current clue, a counter or a bonus. A key uses the value of the moment, and the “Change variables and run command” command changes it and then acts in Foundry.

Can the Foundry server be remote?

Yes. The browser that opens the game must still run on the same computer as Stream Deck.

Do keys work after closing Foundry?

No. They only work if a Foundry browser is open, connected to the game and ready to receive commands. If you close that browser, the session ends.

What happens after Foundry reconnects?

Select the session again on your keys. Each new Foundry connection gets a new identity. Reconnecting only the plugin can rediscover a Foundry session that stayed connected.

Can a player use these commands?

Available actions depend on the signed-in Foundry user's permissions. A key grants no additional rights and never automatically switches users.

Is a JDR Ninja subscription required?

Overlay test requires Premium access verified in Foundry. No general subscription requirement has been announced for local commands. Generators and other module features have their own access conditions.

Which devices and platforms are verified?

Development tests use a real Foundry browser and a simulated Elgato host. Physical Stream Deck hardware, Windows/macOS installation and trusted-certificate wss still await acceptance. No general hardware compatibility claim is made.

Can I edit any field of a character sheet?

Yes, if Foundry lets you edit that document: the GM can edit anything, a player only what belongs to them. The field path depends on the game system and the module does not check it. Foundry ignores a field that does not exist, and an increase or a toggle on that field is reported on the key.

Prepare your first command

Follow the guide to connect the three components and test a simple command.

The JDR Ninja module for Foundry