Macros, scenes and pause
Run an authorized macro, view or activate a scene, adjust darkness and pause the game.
The JDR Ninja module for Foundry
Control Foundry VTT with Stream Deck
Run macros, change scenes and control music from Stream Deck. The JDR Ninja plugin sends commands to Foundry VTT through a companion running on your computer.
At a glance
Three components connect your keys to the selected Foundry browser: the Stream Deck plugin, the local companion and the JDR Ninja module. Foundry executes commands and checks the signed-in user's permissions. Its browser must stay open on the same computer as the companion.
Keep controls close
Bind a key to a macro, scene or sound already in your world.
Choose the right session
Each key keeps the world, user and browser you explicitly selected.
See execution feedback
The plugin distinguishes completed commands from refused commands and uncertain outcomes.
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 module settings, save the companion address and local key, then explicitly enable Stream Deck in this Foundry browser.
Configure a key
The command and its input fields depend on the selected session and Foundry user's permissions.
How the components connect
- Stream Deck plugin
- Local companion
- JDR Ninja module in the Foundry browser
The companion relays commands between the two clients on your computer. Your Foundry server may be hosted elsewhere. The local pairing key requires no JDR Ninja account token and grants no additional Foundry permissions.
Controls in the current version
Music and documents
Play or stop a sound, switch tracks and adjust volume. Open an actor sheet or journal page, share a page with selected recipients and draw from a roll table.
Tokens and combat
Select, target or hide tokens, adjust their core resource bars and advance combat turns within your permissions. Core bars do not provide system-specific damage or healing rules.
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 companion. Keep the Foundry browser and companion running on the Stream Deck computer. Each key must explicitly target a session.
Variables, lists and macro arguments
Ordinary commands work with fixed values. Advanced options let you select a compatible variable, browse a list and supply arguments to a macro that declares them in Foundry. Values and permissions are checked on every press.
Permissions and access
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 does the companion do?
It relays commands between the Stream Deck plugin and authorized Foundry browsers on your computer. Foundry executes actions and checks permissions.
Can the Foundry server be remote?
Yes. The browser opening the game must still run on the same computer as the companion and Stream Deck.
Do keys work after closing Foundry?
Commands need an open Foundry browser connected to the companion and ready to receive them. Closing that browser ends its session.
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.
Prepare your first key
Follow the guide to connect the three components and test a simple command.