Before you start
Check your Foundry and game system versions in the world settings. The module requires Foundry 14 or later; D&D generators target exactly Foundry V14 and D&D5e 5.3.3. Atlas synchronization accepts the systems listed on the module page.
Sign in as GM for generators, Atlas synchronization and Twitch table commands. Players can configure relay of their public rolls. Stream Deck is not required for the other features.
Install and enable the module
The JDR Ninja module is published on Foundry VTT. In Foundry’s setup screen, open the modules tab, click the install button and search for “JDR Ninja”. If the module does not appear in the search, paste its manifest URL into the install window:
https://github.com/JDR-Ninja/fvtt-jdr-ninja/releases/latest/download/module.json
The module requires Foundry VTT version 14 or later, and no other module. Then open your world and enable JDR Ninja in module management.
In Foundry’s settings, the JDR Ninja section offers the “Configure connections” button. It opens the “JDR Ninja connections” window: your JDR Ninja account at the top, then one card per feature, Stream Deck and VTT Overlay, plus D&D generators and Atlas Sync for the GM.
Link your JDR Ninja account
- In the “JDR Ninja connections” window, click “Connect my account”, then “Open JDR Ninja”, and sign in to the website if needed. If the D&D generators are already enabled in this browser, their access is requested in the same authorization.
- Check the code and device name. If you want to use the D&D generators, explicitly grant that feature before approving the connection.
- Return to Foundry and wait for the account confirmation. Access is checked separately for each feature. If the request expired or was denied, start a new connection.
You can also generate a manual token on your Foundry devices page, enter it under “Advanced options” and click “Verify and save”. It is shown only once. If the “D&D generators” card shows “Authorization required”, click “Authorize on JDR Ninja” to add their access.
Manage my Foundry devices
Enable your chosen features
Connecting the account does not enable any feature. In the “JDR Ninja connections” window, each card has its own “Enable” switch, off at first. The Stream Deck, overlay and generator switches apply to this browser only; the Atlas synchronization switch applies to every GM in the world.
- D&D generators (GM): the card first shows whether your world is compatible, then the access your subscription gives. Once the generators are enabled and available, open “D&D monsters” or “D&D NPCs” from the Actors directory or the JDR Ninja settings.
- Overlay: prepare your OBS source in the website’s overlay configuration, then enable the “VTT Overlay” card. Its “Configure VTT Overlay” button opens a window that checks the overlay as soon as it opens and offers “Send test roll”; this test requires the same subscription as rolls.
- Stream Deck: install the plugin and start the local connection first. In Foundry, the “Configure Stream Deck” button on its card opens the window where you enter the address and the pairing key; “Save and enable” completes the setup. The dedicated guide explains the key and how to choose the session.
Connect your Atlas world
- On the website, open your Foundry connections and create a synchronization connection for the relevant Atlas world. Copy the token shown once. You can also create the connection from that world’s settings.
- In Foundry, enter that token on the “Atlas Sync” card of the “JDR Ninja connections” window, then click “Verify and save”. Check the world name and synchronization access. This token is separate from the account connection and Stream Deck key.
- Enable the “Atlas Sync” card for this Foundry world, open its window with the “Atlas” button in the Actors directory and select the campaign. Link an actor to an existing character or create the character in Atlas, then start synchronization. Check the sheet in Atlas.
Prepare values and lists
The module can save values to reuse: a counter, a bonus, a chosen actor or page. Open “Variables and lists (advanced)” in the module settings, or “Variables and lists” in the module’s “Stream Deck” window. The “Variables” tab holds the values; the “Value lists” tab holds documents sorted in the order of your choice, for example your NPCs or your clues. These settings require neither Stream Deck nor a subscription.
Choose “Personal” for your own values: each user edits their own. A “World” value is shared by all users in the world, but only the GM named in “World variable controller” can change it.
A variable has a “Default value” and a “Current value”. The variable list shows the current value of each one, and “Change current value” lets you change it by hand or reset it to the default value. A “List selection” starts with no current value: after saving it, apply “Reset to default”. A “Computed value” is derived from other variables and cannot be changed directly.
In the “Calculation expression” field, write a variable as @{Name}. After a document variable, add the path of a piece of data as in an Active Effect: if “Spotlight hero” refers to a character, @{Spotlight hero}.system.attributes.inspiration tells whether they have inspiration. The path depends on the game system, and the data is read only if you can see the document.
To pass values to a script macro, declare its arguments in “Compatible macros (advanced)”. This window does not modify the script: the macro must read these arguments and confirm when its execution is finished.
Check your first use
Once a feature is enabled, run a full first test before the game.
Create a first creature
Open Monsters from the JDR Ninja settings or the Actors directory, choose a simple profile and start a generation. Review the preview, create the actor, then open its sheet in Foundry to check the result. Each new generation counts toward your account limits.
Update a character in Atlas
Edit a linked character in Foundry, then send its sheet from the Atlas window. Open its sheet in Atlas to check the change before sending the whole list. Changes made in Atlas do not come back to Foundry.
See a public roll in OBS
Make a public roll containing dice in Foundry and compare the result in the chat and in the OBS source. Private, blind and whispered rolls are never forwarded.
Test a Stream Deck key
Start with a key that opens a sheet, then prepare the keys for a scene: activation, ambient sound and darkness, each command on its own key. The Stream Deck guide then offers examples for play.
If you use the old modules
Disable Atlas Character Sync or the old VTT Overlay module: while it is active, the matching integration of the JDR Ninja module stays unavailable. When a GM opens the world, the module picks up the token, address and campaign from Atlas Character Sync; then enable Atlas synchronization in the “JDR Ninja connections” window. Nothing is carried over from the old overlay module: connect your account again.
Successful Atlas synchronization can adopt existing actor links. A local disconnect clears the token saved in the module but does not revoke it on the website. Use the management pages to revoke a device or connection.
Troubleshooting
The connection expired or was denied
Restart pairing in Foundry and use the new code. Check that you approve the correct device and account. A cancelled or expired request cannot be reused.
My account is linked, but a feature remains unavailable
Check the message for that feature: device permission, subscription, GM permissions, compatibility and enablement are separate requirements. An Atlas token does not grant D&D generator access. If the token was revoked, pair the device again.
The generators reject my Foundry or D&D5e version
The current target is Foundry V14 with D&D5e 5.3.3. The module’s loading minimum and the systems accepted by Atlas do not change this requirement. Check compatibility in the generator window.
Atlas synchronization does not start
Check your GM role, the world’s Atlas switch, game system, correct world token and synchronization access. Disable the old Atlas Character Sync module if it is still active. The account linked for the overlay does not replace the Atlas connection.
Dice do not appear in OBS
Check the switch on the “VTT Overlay” card in this browser, the active website overlay, the OBS browser source and your subscription. Make a public roll containing dice. Private rolls are never forwarded. Check the “Diagnostics” section of the “VTT Overlay” window and disable the old overlay module if active.
Stream Deck cannot find the Foundry session
Check that the local connection is started on the same computer as the Foundry browser and the Stream Deck app, and that it is enabled in Foundry. Once Foundry has reconnected, select the session again on the affected keys. The Stream Deck guide explains the pairing key and the allowed addresses.