VConnect

markdown View As Markdown

Getting Started

VConnect is a streaming overlay and automation tool built around a visual node editor. Connecting it lets your commands fire VConnect triggers and send custom messages into a graph, and lets anything happening in VConnect run a command here. To connect the service:

• Open VConnect and turn on the WebSocket server in its WebSocket settings
• Head to the Services page inside Mix It Up
• Enter the port VConnect is serving on, which is 39542 unless you have moved it
• Select Connect under the VConnect section

VConnect’s protocol does not name the path its WebSocket server listens on, so Mix It Up tries /websocket first and the bare root second, and keeps whichever one answers for the rest of the session. Once connected, the service shows the address it landed on, which is the first thing worth checking if something looks wrong.

Nothing in VConnect’s protocol identifies the server, so after the handshake Mix It Up asks for the trigger list as proof that whatever is on that port really is VConnect. A port with something else on it connects and is then dropped rather than sitting there looking connected.

Closing VConnect’s WebSocket server is a clean close rather than a dropped connection, so Mix It Up checks the socket every couple of seconds instead of waiting to be told. A connection that goes away is retried on its own.

To interact with VConnect, you would add a VConnect Action to your command.

Actions

VConnect actions allow you to drive VConnect from within your commands. This action supports the following options:

• Activate Trigger: Fires one of the triggers in your active VConnect profile, picked from a list read out of VConnect.
• Send Custom Message: Sends a channel name and a set of arguments to the On WebSocket Receive nodes listening on that channel, one argument per line.
• Look Up Asset: Finds an asset by name or by uid and fills in special identifiers for the actions after it.

The trigger and asset lists in the action editor are read from VConnect while it is connected, and are reused for up to 30 minutes before being asked for again. Use the refresh button in the action editor after adding or renaming something in VConnect.

A trigger or asset you have already picked is kept even if you open and save the command while VConnect is closed, so editing an unrelated part of a command does not lose the selection.

Custom Message Arguments

Arguments are entered one per line and sent in that order. A line that is valid JSON on its own is sent as that value, so 42 arrives at the graph as a number and true as a flag. Everything else is sent as text.

Asset Lookup

The lookup takes either the asset picked from the list or a name typed in, and fills in the following Special Identifiers for the actions that follow it:

• $vconnectassetuid = The uid of the asset that was found (EX: d1a7f8d2-1e2f-4b3c-9a4d-5e6f7a8b9c0d)
• $vconnectassetname = The name of the asset that was found (EX: banana)
• $vconnectassettype = The type of the asset that was found (EX: PNG)
• $vconnectassetscreenshotfilepath = Where the asset’s preview image was saved, or empty when no path was set
• $vconnectassetsuccess = Whether the asset was found (EX: True)

All five are filled in even when nothing is found, so a failed lookup leaves blanks rather than raw $vconnect... text in whatever runs next.

The Screenshot File Path field is optional. Leave it empty to look the asset up without its preview image. With a path set, the preview is saved there as a PNG. VConnect only renders previews for 3D, VRM, and PNG assets.

Events

The VConnect service also provides Events that run when something happens inside VConnect itself:

• Trigger Activated: Runs when a trigger fires in VConnect, whether Mix It Up fired it or something else did. Provides the following additional Special Identifiers:
  • $vconnecttriggeruid = The uid of the trigger (EX: a0ce3831-3c3e-4474-b4e4-19ab98dc73dd)
  • $vconnecttriggername = The name of the trigger (EX: New Follow)
• Trigger Ended: Runs when a trigger finishes. Provides those same identifiers plus:
  • $vconnecttriggersuccess = Whether the trigger finished successfully (EX: True)
  • $vconnecttriggererror = The error VConnect reported, or empty when there was none
• Asset Spawned: Runs when an asset appears in the scene. Provides the following additional Special Identifiers:
  • $vconnectassetuid = The uid of the asset (EX: d1a7f8d2-1e2f-4b3c-9a4d-5e6f7a8b9c0d)
  • $vconnectassetname = The name of the asset (EX: banana)
  • $vconnecttriggeruid = The uid of the trigger that spawned it (EX: ebb7170b-40e6-4832-8b05-bc6c809d79f1)
  • $vconnecttriggernodeuid = The uid of the graph node that spawned it (EX: 3fa2c1d4-5b6e-4f70-8192-a3b4c5d6e7f8)
• Asset Despawned: Runs when an asset is removed from the scene, with those same identifiers.
• Asset Hit: Runs when an asset collides with something. Provides those same identifiers plus the collision details below.
• Custom Message Received: Runs when a Send WebSocket Message node in your graph sends something out. Provides the identifiers listed under Custom Messages below.

Asset Hit Details

In addition to the asset identifiers, the Asset Hit event provides:

• $vconnecthitpointx / $vconnecthitpointy / $vconnecthitpointz = Where the collision happened (EX: 0.1)
• $vconnecthitnormalx / $vconnecthitnormaly / $vconnecthitnormalz = The direction the surface was facing at the point of collision (EX: 1)
• $vconnecthitvelocityx / $vconnecthitvelocityy / $vconnecthitvelocityz = The relative velocity at the moment of collision (EX: 0.33)
• $vconnecthitforce = VConnect’s estimate of the force of the collision (EX: 24.5)

Any of these that VConnect leaves out comes through as 0 rather than as blank text.

Custom Messages

The Custom Message Received event provides:

• $vconnectmessagechannel = The channel the message was sent on (EX: my-event)
• $vconnectmessagedata = Every argument as raw JSON (EX: [“arg1”,42,true])
• $vconnectmessageargumentcount = How many arguments came through (EX: 3)
• $vconnectmessageargument1 = The first argument (EX: arg1), then $vconnectmessageargument2 and so on for as many as were sent

An argument that is an object or an array keeps its JSON, and everything else reads as its plain value, so a text argument does not arrive wrapped in quotes.