Configurar Stream Deck con Foundry VTT

Requisitos

Prepare Foundry V14 o posterior, el módulo JDR Ninja activado, la aplicación Stream Deck, su plugin JDR Ninja y Node.js 24. El servidor puede ser remoto, pero abra el navegador Foundry en el ordenador donde funcionen Stream Deck y el programa complementario.

Instalar el módulo Foundry

Instalar el plugin y el programa complementario

La distribución pública está en preparación. Si dispone de una versión de desarrollo, instale el archivo .streamDeckPlugin en la aplicación Stream Deck. Para el programa complementario, abra un terminal en el directorio stream-deck de las fuentes e instale las dependencias con el siguiente comando.

npm ci

Si ha recibido el archivo de ejecución .tgz, extráigalo, abra un terminal en su carpeta y use este comando en su lugar. Node.js 24 se instala por separado.

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

El programa complementario funciona en el terminal. No incluye inicio automático, aplicación de bandeja ni instalación de Node.js. Mantenga esta ventana abierta durante la partida.

Preparar la conexión local

Ejecute la inicialización. Introduzca el origen exacto del navegador Foundry, como http://localhost:30000 o https://foundry.example.net, sin ruta ni barra final. Copie la clave generada y consérvela para ambos clientes. Después inicie el programa.

npm run companion:init
npm run companion

La configuración se guarda en su perfil privado, en las rutas siguientes. La inicialización no sustituye un archivo existente. Para cambiar origen, puerto o clave, detenga el programa, edite el archivo y reinícielo. Si cambia la clave, actualice ambos clientes.

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

Conectar Foundry al programa complementario

En los ajustes Stream Deck del módulo JDR Ninja en Foundry, introduzca la dirección siguiente y la clave. Guarde y active explícitamente la integración en este navegador. Compruebe que se ha conectado al programa complementario.

ws://127.0.0.1:19114/jdr-ninja

Conectar el plugin Stream Deck

Añada la acción de control de Foundry a una tecla. En su inspector, rellene « Dirección del companion » con la dirección siguiente, pegue la misma « Clave de vinculación » y elija « Conectar ». Los ajustes se comparten entre teclas. El campo de clave se vacía tras guardar.

ws://127.0.0.1:19114/stream-deck

Esta clave vincula los clientes al programa complementario local. Es distinta del token de conexión Atlas y las credenciales JDR Ninja. No pegue esas otras credenciales en el campo de vinculación.

Elegir la sesión Foundry

En « Mundo y navegador de Foundry », elija el mundo, usuario y navegador deseados. Espere a « Listo » y a que aparezcan los comandos y documentos autorizados. Cada tecla guarda su sesión, comando y parámetros; nunca cambia automáticamente de mundo, usuario o navegador.

Crear y probar la primera tecla

En « Comando », elija « Abrir actor » y un actor cuya ficha pueda abrir. Pulse la tecla una vez. Compruebe la ficha en Foundry y el resultado « Completado. » en el inspector. Un comando admitido puede seguir esperando su ejecución.

Un resultado incierto puede mostrar brevemente « ? » en la tecla. Compruebe qué ocurrió en Foundry antes de pulsar de nuevo. Después añada controles de escena, música o combate según sus necesidades y permisos.

Después de una reconexión

Cada nueva conexión Foundry recibe una nueva identidad de sesión. Selecciónela de nuevo en cada tecla afectada, también al reiniciar el programa complementario. Si solo se reconecta el plugin, puede recuperar una sesión Foundry aún conectada. Ctrl+C detiene el programa y sus conexiones.

Opciones avanzadas

Empiece con valores fijos. Para un contador personal, cree una variable numérica modificable en Foundry. En el inspector elija « Aumentar variable », esa variable y un ajuste fijo de 1. Compruebe el resultado en Foundry. Las variables calculadas aportan valores, pero este comando no puede modificarlas.

Las listas y los argumentos de macro son opcionales. Elija variables compatibles y una macro que declare sus argumentos en Foundry. Cada pulsación verifica sesión, valores y permisos. Un comando combinado puede guardar variables antes de fallar la acción; compruebe ambos resultados antes de repetir.

El módulo JDR Ninja para Foundry

Solución de problemas

• Sin conexión: compruebe que el programa esté abierto, las direcciones usen 127.0.0.1 con las rutas correctas y ambos clientes tengan la misma clave.
• Foundry rechazado o ausente: compruebe el origen exacto permitido en companion.json y la activación en ese navegador. Otra dirección de servidor cambia el origen.
• Foundry en HTTPS: el navegador puede requerir wss y un certificado local de confianza. Configure tlsCert y tlsKey con rutas absolutas a archivos PEM y use wss en ambos clientes. El certificado debe cubrir la dirección local y ser de confianza para ambos navegadores. El programa no lo instala.
• Sesión ausente o sincronizando: espere a que esté lista y vuelva a seleccionar mundo, usuario y navegador en la tecla.
• Comando rechazado o documento ausente: compruebe los permisos de la cuenta Foundry y el documento elegido. Seleccionar una sesión no concede más derechos.
• Prueba del overlay no disponible: compruebe la conexión de la cuenta JDR Ninja, la activación del overlay y la verificación Premium. La clave local no confirma ese acceso.
• Resultado incierto o parcial: compruebe la ficha, escena, variables o combate afectados en Foundry antes de pulsar de nuevo. Una interrupción puede ocurrir después de ejecutar. El plugin no reintenta automáticamente.