Trigger Vfinity from your own app

Fire an event from Stream Deck, a script or a game by sending one JSON message over WebSocket.

The trigger API lets anything you can write code for make your model react. Stream Deck plugins, Python scripts, Node servers, a game mod: if it can serve a WebSocket, it can drive Vfinity.

The part that surprises people

Vfinity is the client. It connects out to a server that you run. It does not listen for connections.

So the work is: run a WebSocket server, tell Vfinity where it is, and push messages to Vfinity when you want something to happen.

Run a server

Here is one that fires jump_scare five seconds after Vfinity connects.

// npm install ws
import { WebSocketServer } from 'ws';

const server = new WebSocketServer({ port: 8080 });

server.on('connection', (socket) => {
  console.log('Vfinity connected');

  setTimeout(() => {
    socket.send(JSON.stringify({ type: 'trigger', name: 'jump_scare' }));
  }, 5000);
});

# pip install websockets
import asyncio
import json
import websockets

async def handler(socket):
    print('Vfinity connected')
    await asyncio.sleep(5)
    await socket.send(json.dumps({'type': 'trigger', 'name': 'jump_scare'}))

async def main():
    async with websockets.serve(handler, 'localhost', 8080):
        await asyncio.Future()

asyncio.run(main())

Point Vfinity at it

In SettingsConnections, on the Trigger API card:

Set WebSocket Host to localhost if the server runs on the same machine.
Set WebSocket Port to 8080, or whatever port your server listens on.
Click Connect API.

The status turns green when the socket is open.

Make a mapping that listens for it

On the Events tab, click New Event:

Set Event Type to API trigger.
Set Trigger Name to jump_scare. This has to match the name field in your message, and it is matched case-insensitively.
Choose an action as you would for any other mapping.
Click Add Mapping.

Run it

Start your server, then watch the Event Log on the Dashboard. Five seconds after Vfinity connects, the trigger arrives and the action runs.

The message format

{
  "type": "trigger",
  "name": "EVENT_NAME",
  "data": {}
}

Field	Type	Required	Meaning
`type`	string	Yes	Always `"trigger"`
`name`	string	Yes	Matched against Trigger Name on your API mappings, case-insensitively
`data`	object	No	Reserved. Vfinity accepts it and does not read it yet

Messages are text JSON. The channel is receive-only: Vfinity listens, and does not send anything back.

If a trigger does nothing

The socket is not connected. Check the Trigger API card is green, and that your server is running.
The names do not match. jump_scare and jumpscare are different triggers. Case does not matter; anything else does.
The mapping is off. Check its toggle on the Events tab.
The JSON is malformed. Turn on Verbose logging in SettingsPreferences and data and open the debug console from the title bar to see the raw frames.

Trigger API reference

The protocol on its own, without the tutorial.

Ports

Every port Vfinity uses and what listens on it.

Trigger Vfinity from your own app

Trigger API reference

Ports

On this page