Configurer Stream Deck avec Foundry VTT

Ce qu’il vous faut

Préparez Foundry V14 ou ultérieur, le module JDR Ninja activé, l’application Stream Deck, son plugin JDR Ninja et Node.js 24. Le serveur Foundry peut être distant, mais ouvrez son navigateur sur l’ordinateur où fonctionneront Stream Deck et le compagnon.

Installer le module Foundry

Installer le plugin et le compagnon

La distribution publique est en préparation. Si vous disposez d’une version de développement, installez le fichier .streamDeckPlugin dans l’application Stream Deck. Pour le compagnon, ouvrez un terminal dans le dossier stream-deck des sources et installez les dépendances avec la commande suivante.

npm ci

Si vous avez reçu l’archive d’exécution .tgz du compagnon, extrayez-la, ouvrez un terminal dans son dossier et utilisez cette commande à la place. Node.js 24 doit être installé séparément.

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

Le compagnon fonctionne dans le terminal. Il n’inclut ni lancement automatique, ni application de barre des tâches, ni installation de Node.js. Gardez cette fenêtre ouverte pendant la partie.

Préparer la connexion locale

Lancez l’initialisation. Indiquez l’origine exacte du navigateur Foundry, par exemple http://localhost:30000 ou https://foundry.example.net, sans chemin ni barre oblique finale. Copiez la clé de jumelage générée et conservez-la pour les deux clients. Démarrez ensuite le compagnon.

npm run companion:init
npm run companion

La configuration reste dans votre profil privé, aux emplacements ci-dessous. L’initialisation ne remplace pas un fichier existant. Pour changer l’origine, le port ou la clé, arrêtez le compagnon, modifiez ce fichier puis redémarrez-le. Si la clé change, mettez les deux clients à jour.

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

Connecter Foundry au compagnon

Dans les paramètres Stream Deck du module JDR Ninja dans Foundry, saisissez l’adresse ci-dessous et la clé de jumelage. Enregistrez, puis activez explicitement l’intégration dans ce navigateur. Vérifiez que la connexion au compagnon est établie.

ws://127.0.0.1:19114/jdr-ninja

Connecter le plugin Stream Deck

Ajoutez l’action « Piloter Foundry » à une touche. Dans son inspecteur, renseignez « Adresse du companion » avec l’adresse ci-dessous, collez la même « Clé de jumelage » et choisissez « Connecter ». Ces paramètres de connexion sont communs aux touches. Le champ de clé est vidé après l’enregistrement.

ws://127.0.0.1:19114/stream-deck

Cette clé relie les clients au compagnon local. Elle est différente du jeton de connexion Atlas et des identifiants de votre compte JDR Ninja. Ne collez aucun de ces autres identifiants dans le champ de jumelage.

Choisir la session Foundry

Dans « Partie et navigateur Foundry », choisissez le monde, l’utilisateur et le navigateur voulus. Attendez l’état « Prêt » et l’apparition des commandes et documents autorisés. Chaque touche enregistre sa propre session, sa commande et ses paramètres. Elle ne bascule jamais automatiquement vers un autre monde, utilisateur ou navigateur.

Créer et tester une première touche

Dans « Commande », choisissez « Ouvrir un acteur », puis sélectionnez un acteur dont vous pouvez ouvrir la fiche. Appuyez une fois sur la touche. Vérifiez l’ouverture de la fiche dans Foundry et le résultat « Terminé. » dans l’inspecteur. Une commande acceptée peut encore attendre son exécution.

Si un résultat est incertain, la touche peut afficher brièvement « ? ». Vérifiez ce qui s’est passé dans Foundry avant un nouvel appui. Ajoutez ensuite vos commandes de scène, de musique ou de combat selon vos besoins et vos permissions.

Après une reconnexion

Une nouvelle connexion Foundry reçoit une nouvelle identité de session. Sélectionnez-la à nouveau sur chaque touche concernée, y compris après un redémarrage du compagnon. Si seul le plugin se reconnecte, il peut retrouver une session Foundry restée connectée. Ctrl+C arrête le compagnon et interrompt ses connexions.

Options avancées

Commencez avec des valeurs fixes. Pour un compteur personnel, créez dans Foundry une variable de type Nombre que vous pouvez modifier. Dans l’inspecteur, choisissez « Augmenter une variable », cette variable et une variation fixe de 1. Vérifiez le résultat dans Foundry. Les variables calculées peuvent fournir une valeur, mais ne peuvent pas être modifiées par cette commande.

Les listes et les arguments de macro sont facultatifs. Choisissez des variables compatibles et une macro qui déclare ses arguments dans Foundry. Chaque appui vérifie la session, les valeurs et les permissions. Une commande combinée peut enregistrer les variables avant l’échec d’une action : vérifiez les deux résultats avant de recommencer.

Le module JDR Ninja pour Foundry

En cas de problème

• Aucune connexion : vérifiez que le compagnon fonctionne, que les adresses utilisent 127.0.0.1 avec les bons chemins et que les deux clients ont la même clé.
• Foundry refusé ou absent : vérifiez l’origine exacte autorisée dans companion.json et l’activation de Stream Deck dans ce navigateur. Une adresse de serveur différente change l’origine.
• Foundry en HTTPS : le navigateur peut exiger wss et un certificat local approuvé. Configurez tlsCert et tlsKey avec des chemins absolus vers des fichiers PEM, puis utilisez wss dans les deux clients. Le certificat doit couvrir l’adresse locale et être approuvé par les deux navigateurs. Le compagnon ne l’installe pas.
• Session disparue ou en synchronisation : attendez qu’elle soit prête, puis sélectionnez à nouveau le monde, l’utilisateur et le navigateur sur la touche.
• Commande refusée ou document absent : vérifiez les permissions du compte Foundry et le document ciblé. Le choix d’une session ne donne aucun droit supplémentaire.
• Test de l’overlay indisponible : vérifiez la connexion du compte JDR Ninja, l’activation de l’overlay dans Foundry et le résultat de la vérification Premium. La clé locale ne confirme pas cet accès.
• Résultat incertain ou partiel : inspectez la fiche, la scène, les variables ou le combat concernés dans Foundry avant un nouvel appui. Une interruption peut survenir après l’exécution. Le plugin ne relance pas la commande automatiquement.