Configurare Stream Deck con Foundry VTT

Requisiti

Prepari Foundry V14 o successivo, il modulo JDR Ninja attivo, l’applicazione Stream Deck, il plugin JDR Ninja e Node.js 24. Il server può essere remoto, ma il browser Foundry deve funzionare sul computer di Stream Deck e del companion.

Installare il modulo Foundry

Installare il plugin e il companion

La distribuzione pubblica è in preparazione. Se dispone di una versione di sviluppo, installi il file .streamDeckPlugin nell’applicazione Stream Deck. Per il companion apra un terminale nella cartella stream-deck dei sorgenti e installi le dipendenze con il comando seguente.

npm ci

Se ha ricevuto l’archivio di esecuzione .tgz del companion, lo estragga, apra un terminale nella cartella e usi questo comando. Node.js 24 si installa separatamente.

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

Il companion funziona nel terminale. Non include avvio automatico, applicazione nella barra di sistema o installer di Node.js. Mantenga la finestra aperta durante la partita.

Preparare la connessione locale

Avvii l’inizializzazione. Inserisca l’origine esatta del browser Foundry, per esempio http://localhost:30000 o https://foundry.example.net, senza percorso né barra finale. Conservi la chiave generata per entrambi i client, poi avvii il companion.

npm run companion:init
npm run companion

La configurazione resta nel profilo privato, nei percorsi seguenti. L’inizializzazione non sovrascrive file esistenti. Per cambiare origine, porta o chiave, arresti il companion, modifichi il file e lo riavvii. Se cambia la chiave, aggiorni entrambi i client.

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

Collegare Foundry al companion

Nelle impostazioni Stream Deck del modulo JDR Ninja in Foundry inserisca l’indirizzo seguente e la chiave. Salvi, poi attivi esplicitamente l’integrazione in questo browser. Verifichi la connessione al companion.

ws://127.0.0.1:19114/jdr-ninja

Collegare il plugin Stream Deck

Aggiunga l’azione di controllo Foundry a un tasto. L’inspector non ha una traduzione italiana e usa l’inglese: inserisca l’indirizzo seguente in « Companion address », la stessa chiave in « Pairing key » e scelga « Connect ». Le impostazioni sono condivise tra i tasti; il campo della chiave si svuota dopo il salvataggio.

ws://127.0.0.1:19114/stream-deck

La chiave collega i client al companion locale. È diversa dal token di connessione Atlas e dalle credenziali dell’account JDR Ninja. Non inserisca queste altre credenziali nel campo di abbinamento.

Scegliere la sessione Foundry

In « Foundry world and browser » scelga mondo, utente e browser desiderati. Attenda « Ready » e l’elenco dei comandi e documenti autorizzati. Ogni tasto memorizza sessione, comando e parametri propri. Non cambia automaticamente mondo, utente o browser.

Creare e provare il primo tasto

In « Command » scelga « Open actor » e un attore di cui può aprire la scheda. Prema il tasto una volta. Verifichi la scheda in Foundry e il risultato « Completed. » nell’inspector. Un comando ammesso può ancora attendere l’esecuzione.

Un risultato incerto può mostrare brevemente « ? » sul tasto. Controlli cosa è successo in Foundry prima di premere di nuovo. Poi aggiunga comandi di scena, musica o combattimento secondo esigenze e permessi.

Dopo una riconnessione

Ogni nuova connessione Foundry riceve una nuova identità di sessione. La selezioni di nuovo sui tasti interessati, anche dopo il riavvio del companion. La riconnessione del solo plugin può ritrovare una sessione ancora connessa. Ctrl+C arresta il companion e chiude le connessioni.

Opzioni avanzate

Inizi con valori fissi. Per un contatore personale crei in Foundry una variabile numerica modificabile. Nell’inspector scelga « Increase variable », la variabile e un incremento fisso di 1. Verifichi il risultato in Foundry. Le variabili calcolate possono fornire valori ma non essere modificate dal comando.

Liste e argomenti delle macro sono facoltativi. Scelga variabili compatibili e una macro che dichiara gli argomenti in Foundry. Ogni pressione verifica sessione, valori e permessi. Un comando combinato può salvare variabili prima che un’azione fallisca: verifichi entrambi i risultati prima di riprovare.

Il modulo JDR Ninja per Foundry

Risoluzione dei problemi

• Nessuna connessione: verifichi che il companion sia attivo, gli indirizzi usino 127.0.0.1 con i percorsi corretti e i client abbiano la stessa chiave.
• Foundry assente o rifiutato: verifichi l’origine esatta consentita in companion.json e l’attivazione nel browser. Un diverso indirizzo del server cambia l’origine.
• Foundry in HTTPS: il browser può richiedere wss e un certificato locale attendibile. Configuri tlsCert e tlsKey con percorsi assoluti a file PEM, poi usi wss in entrambi i client. Il certificato deve coprire l’indirizzo locale ed essere attendibile per entrambi i browser. Il companion non lo installa.
• Sessione assente o in sincronizzazione: attenda che sia pronta e selezioni di nuovo mondo, utente e browser sul tasto.
• Comando rifiutato o documento assente: verifichi i permessi dell’account Foundry e il documento scelto. La selezione della sessione non concede diritti aggiuntivi.
• Test dell’overlay non disponibile: verifichi collegamento dell’account JDR Ninja, attivazione dell’overlay e verifica Premium in Foundry. La chiave locale non conferma questo accesso.
• Risultato incerto o parziale: controlli scheda, scena, variabili o combattimento interessati in Foundry prima di premere di nuovo. Un’interruzione può avvenire dopo l’esecuzione. Il plugin non ripete automaticamente il comando.