Stream Deck mit Foundry VTT einrichten

Voraussetzungen

Bereiten Sie Foundry V14 oder neuer, das aktivierte JDR-Ninja-Modul, die Stream-Deck-Anwendung, das Plugin und Node.js 24 vor. Der Server darf entfernt sein; der Foundry-Browser muss auf dem Computer von Stream Deck und Companion laufen.

Foundry-Modul installieren

Plugin und Companion installieren

Die öffentliche Verteilung wird vorbereitet. Falls Sie einen Entwicklungsbuild besitzen, installieren Sie dessen .streamDeckPlugin-Datei in der Stream-Deck-Anwendung. Öffnen Sie für den Companion ein Terminal im Quellordner stream-deck und installieren Sie die Abhängigkeiten mit dem folgenden Befehl.

npm ci

Falls Sie das .tgz-Laufzeitarchiv des Companions erhalten haben, entpacken Sie es und verwenden Sie im entpackten Ordner diesen Befehl. Node.js 24 wird separat installiert.

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

Der Companion läuft im Terminal. Autostart, Tray-Anwendung und Node.js-Installer sind nicht enthalten. Lassen Sie das Fenster während des Spiels geöffnet.

Lokale Verbindung vorbereiten

Starten Sie die Initialisierung. Geben Sie den exakten Ursprung des Foundry-Browsers an, etwa http://localhost:30000 oder https://foundry.example.net, ohne Pfad oder abschließenden Schrägstrich. Bewahren Sie den erzeugten Kopplungsschlüssel für beide Clients auf und starten Sie den Companion.

npm run companion:init
npm run companion

Die Konfiguration liegt im privaten Profil an den folgenden Pfaden. Die Initialisierung überschreibt keine vorhandene Datei. Halten Sie den Companion vor Änderungen an Ursprung, Port oder Schlüssel an, bearbeiten Sie die Datei und starten Sie ihn neu. Aktualisieren Sie bei geändertem Schlüssel beide Clients.

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

Foundry mit dem Companion verbinden

Tragen Sie in den Stream-Deck-Einstellungen des JDR-Ninja-Moduls in Foundry die folgende Adresse und den Schlüssel ein. Speichern Sie und aktivieren Sie die Integration ausdrücklich für diesen Browser. Prüfen Sie anschließend die Verbindung zum Companion.

ws://127.0.0.1:19114/jdr-ninja

Stream-Deck-Plugin verbinden

Fügen Sie die Foundry-Steuerungsaktion einer Taste hinzu. Tragen Sie im Inspektor die folgende « Companion-Adresse » und denselben « Kopplungsschlüssel » ein und wählen Sie « Verbinden ». Verbindungseinstellungen gelten für alle Tasten. Das Schlüsselfeld wird nach dem Speichern geleert.

ws://127.0.0.1:19114/stream-deck

Dieser Schlüssel koppelt Clients an den lokalen Companion. Er unterscheidet sich vom Atlas-Verbindungstoken und den Zugangsdaten Ihres JDR-Ninja-Kontos. Tragen Sie diese anderen Zugangsdaten nicht in das Kopplungsfeld ein.

Foundry-Sitzung wählen

Wählen Sie unter « Foundry-Welt und Browser » die gewünschte Welt, den Benutzer und Browser. Warten Sie auf « Bereit » und die erlaubten Befehle und Dokumente. Jede Taste speichert ihre eigene Sitzung, ihren Befehl und ihre Parameter und wechselt das Ziel nie automatisch.

Erste Taste erstellen und testen

Wählen Sie unter « Befehl » die Option « Akteur öffnen » und einen zugänglichen Akteur. Drücken Sie die Taste einmal. Prüfen Sie den geöffneten Bogen in Foundry und « Abgeschlossen. » im Inspektor. Ein angenommener Befehl kann noch auf seine Ausführung warten.

Ein unbestätigtes Ergebnis kann kurz « ? » auf der Taste anzeigen. Prüfen Sie vor erneutem Drücken, was in Foundry passiert ist. Ergänzen Sie anschließend Szenen-, Musik- oder Kampfbefehle nach Bedarf und Berechtigung.

Nach einer erneuten Verbindung

Jede neue Foundry-Verbindung erhält eine neue Sitzungsidentität. Wählen Sie diese auf jeder betroffenen Taste erneut, auch nach einem Companion-Neustart. Verbindet sich nur das Plugin neu, kann es eine bestehende Foundry-Sitzung wiederfinden. Ctrl+C beendet Companion und Verbindungen.

Erweiterte Optionen

Beginnen Sie mit festen Werten. Erstellen Sie für einen persönlichen Zähler eine beschreibbare Zahlenvariable in Foundry. Wählen Sie im Inspektor « Variable erhöhen », diese Variable und einen festen Betrag von 1. Prüfen Sie das Ergebnis in Foundry. Berechnete Variablen liefern Werte, können aber nicht mit diesem Befehl geändert werden.

Listen und Makroargumente sind optional. Wählen Sie passende Variablen und ein Makro mit in Foundry deklarierten Argumenten. Jeder Tastendruck prüft Sitzung, Werte und Rechte. Ein kombinierter Befehl kann Variablen speichern, bevor die Aktion scheitert. Prüfen Sie beide Ergebnisse vor einem weiteren Versuch.

Das JDR-Ninja-Modul für Foundry

Fehlerbehebung

• Keine Verbindung: Prüfen Sie den laufenden Companion, 127.0.0.1 mit korrekten Pfaden und denselben Schlüssel in beiden Clients.
• Foundry fehlt oder wird abgelehnt: Prüfen Sie den exakten erlaubten Ursprung in companion.json und die Aktivierung in diesem Browser. Eine andere Serveradresse ändert den Ursprung.
• Foundry über HTTPS: Der Browser kann wss und ein vertrauenswürdiges lokales Zertifikat verlangen. Setzen Sie tlsCert und tlsKey auf absolute PEM-Pfade und nutzen Sie wss in beiden Clients. Das Zertifikat muss zur lokalen Adresse passen und in beiden Browsern vertrauenswürdig sein. Der Companion installiert es nicht.
• Fehlende oder synchronisierende Sitzung: Warten Sie auf Bereitschaft und wählen Sie Welt, Benutzer und Browser auf der Taste erneut.
• Abgelehnter Befehl oder fehlendes Dokument: Prüfen Sie Foundry-Rechte und Zieldokument. Die Sitzungswahl verleiht keine zusätzlichen Rechte.
• Overlay-Test nicht verfügbar: Prüfen Sie JDR-Ninja-Kontoverbindung, Overlay-Aktivierung und Premium-Prüfung in Foundry. Der lokale Schlüssel bestätigt diesen Zugang nicht.
• Unbestätigtes oder teilweises Ergebnis: Prüfen Sie betroffene Bögen, Szenen, Variablen oder Kämpfe in Foundry vor erneutem Drücken. Eine Unterbrechung kann nach der Ausführung auftreten. Das Plugin wiederholt Befehle nicht automatisch.