Using VoiceAttack to control a virtual joystick

[Gary]

Edit - May 21st, 2017 -  Updated for latest version of vJoy, updated for VA plugin interface v4 (VA version v1.6.2+).
Edit - May 25th, 2019 -  Fixed multiple joystick issue and merged vJoyInterfaceWrap.dll.
Edit - August 25th, 2019 - Update for latest vJoy.  Turns out this only really needed the vJoyInterface.dll that is provided by vJoy.
Edit - January 20th, 2020 - Added 64-bit plugin downloads for 64-bit versions of VA.
Edit by Pfeil  - June 12th, 2021 - Updated vJoy link
Edit by Pfeil - September 10th, 2022 - Updated information regarding bitness

VoiceAttack has long been able to accept input from joysticks (that is, the user presses one or two joystick buttons on one or two sticks) and execute a command.  VoiceAttack can also, with some legwork, interact with a virtual joystick to simulate joystick events on your PC.  I've updated the plugin pack and have provided it as an attachment here.  I've also attached the demo profile for you to try out.

The instructions below are from the old VoiceAttack Google group, where the full thread still resides:  https://groups.google.com/forum/#!topic/voiceattack/eOkWVHK8yy8


VoiceAttack Joystick Output Plugin

What's it for?  Well, this is a plugin approach to adding joystick OUTPUT to VoiceAttack.  Since having this kind of functionality requires its own driver and maximum dependency on third-party software, it is better that it exists outside the main application.  The hope is to have a plugin that can push buttons and set sliders, stick axes and pov/hat positions all controlled by your voice (or key press... or even another joystick button (lol)).


Disclaimer :  I am not responsible for anything you do to your pc.  If this is bothersome, it's time to bail out now

How to install this stuff...

First, you will need at least VoiceAttack v1.6.2. 

Next, go and download the very fine application/driver package called, 'vJoy' (this plugin will not work without the supplied driver it installs).

vJoy can be found here -   https://sourceforge.net/projects/vjoystick/.

Go to downloads and then click the big, green, 'download' button in the middle of the page.  Run the executable that comes down. 
It's safe... I've been using it for a long time.  Just select all the companion applications.  You really only need the, 'vJoy Configuration application', but the other two will be really handy when setting up your profiles.

You may or may not get a Windows Security message at this point stating that the driver has not been signed/cant verify publisher/etc.  It's OK to click, 'Install the driver software anyway'.  If you are going to use the plugin, you're going to need it.  If this bothers you, it's time to bail out.  For the rest of you, this software has been around for a long time and I trust it enough to just plow on through.  The vJoy author is working on getting the driver all signed and shiny.  You should get a success message at this point plus a little Windows sound effect indicating a device was added.

So, why did we do this?  Well, we need *something* to show up in the device list to control.  vJoy installs a virtual, 'joystick' that we can talk to through the plugin.  Your game should see the vJoy device as an actual joystick.


Next, we want to go ahead and put in the plugin so that VoiceAttack can use it.

If you are using the 64-bit version of VA (version v1.10 and newer are 64-bit), go here to get the plugin .zip - https://voiceattack.com/FileSend.aspx?id=VAJoystickOutput64Bit_v6.zip   (note you can also download this from the attachments below).

If you are using the older 32-bit version of VA (v1.8.9 or earlier), go here to get the plugin .zip - https://voiceattack.com/FileSend.aspx?id=VAJoystickOutput_v6.zip   (note you can also download this from the attachments below).

What you are downloading is a zipped folder with two files in it: VAJoystickOutput.dll and vJoyInterface.dll.  VAJoystickOutput.dll is the plugin and vJoyInterface.dll is provided by vJoy that talks to the driver (the plugin depends on this).

Go into your VoiceAttack installation directory (usually C:\Program Files\VoiceAttack, or C:\Program Files (x86)\VoiceAttack if you updated from a version before v1.10) and then go into the Apps directory (or wherever you have indicated where your VoiceAttack Apps folder is located).  Copy the folder in the zip file into the Apps directory.  You should now have a folder here (usually) : C:\Program Files\VoiceAttack\Apps\VAJoystickOutput with the two files in it.

You will need to go into the Options screen and make sure the, 'Enable Plugin Support' check box is checked (you'll have to restart VoiceAttack if you just now turned that on).  When VoiceAttack loads, you should see, 'Plugin 'VoiceAttack Joystick Output Plugin' initialized.' if everything is working as expected.


What we want to do now is go ahead and configure a stick.  You can have up to 16 virtual sticks with vJoy for all of your 16 virtual hands, but we're going to just start with one.  Go into your Windows start menu and find the vJoy folder.  Run the, 'Configure vJoy' application.  On the screen, you'll see that virtual joystick 1 is already added for you (from here out, we'll keep referring to this as, 'stick 1').  You'll notice stick 1 has all the axes selected (I just leave them all selected).  The number of buttons is probably set to 8.  You can have up to 128 buttons per stick.  For this setup, I'm just leaving at 8 for no particular reason.  You can choose up to four POV/hat controls. This is set to zero by default, so I set mine to 1.  You can choose either 4 directions or continuous.  I selected, 'continuous'.  Click the, 'Apply' button and you'll hear the device drop/add sounds.  Stick 1 is now recognized by Windows as you've configured it.  Close this app.


Go back to the start menu and open up the, 'Monitor vJoy' app.  This app can be used to test the plugin.  You'll see that it has stick 1 selected, with 1 POV/hat, all the axes and 8 buttons enabled (just like we set up).  Just let it run for now, we'll be using it shortly.

To take away some of the pain of creating a profile with commands, I created a sample one for you to import if you would like to.  Otherwise, you can skip on down to the instructions on how to use the plugin.  You can download the sample profile here -  http://voiceattack.com/FileSend.aspx?id=JoystickOutput.vap (also attached here).

Download and import the profile like you normally would.  If you edit the profile, you will see a command to test each control on stick 1.  There is one main command called, 'test stick' that will execute all the commands one after the next.  You can either speak, 'test stick' or press ALT + T.  If you are watching the Monitor vJoy app, you'll see each control turn red as each button/axis/pov is modified.  This is an indication that you've set everything up right and are ready to start using the plugin (see below for information on how to use the plugin).  ***This command just goes into an endless loop, so if you want to stop the test, just speak, 'stop test' or press ALT + S.

If this all works out for you, make sure to send a letter of thanks to the vJoy developer (Shaul Eizkovich).  I tried to get him to put up a donation page, but he just won't have it.  Nice guy, worthy of praise

Something to note is that if you have concurrent commands running and beating the snot out of the plugin against vJoy (acquiring without releasing), you might make it break and have to restart VoiceAttack.  You have to beat it up a lot, but it can happen.  Also, this is a first-pass effort... any feedback would be great!



How to use the plugin.

If you are not familiar with VoiceAttack plugin execution, make sure you check out the VoiceAttackHelp.pdf document that is in your VoiceAttack installation directory (and available from the start menu).

To execute a plugin function, you must first add an, 'Execute External Plugin Function' action to your command.  On the setup screen for this action, you'll want to make sure that you choose, 'VoiceAttack Joystick Output Plugin' as the plugin.  If it is not available, then you have not installed it properly (see above).

You will need to specify a context, since you can do several things with this plugin.  You can press and release a button, change an axis and change a POV/hat position.


To press or release a virtual joystick button, you will use the, 'button' context.  What you will by typing in the context box will look like this:  button;1;5;down

button;{stick number};{button number};down or up

For button press/release, you always start with the word, 'button' followed by a semicolon.  Next you'll type in the stick number.  In this case it's one... followed by another semicolon.  The next value is the button number.  We've indicated button 5, and then one last semicolon.  The last part is either, 'down' or 'up' (no quotes).  'down' presses the button, 'up' releases.

Note... as I usually point out with other things, make sure your button down and up have some sort of pause between them, so that the game will have a chance to poll for button state.


For initialization and cleanup, there is a context called, 'allbuttons'.  What you type will look like this:  allbuttons;1;up

allbuttons;{stick number};down or up

As you can probably tell, its used to set all available buttons on a certain stick to either down or up.  Works mostly like the, 'button' context, except there are only three values.  For this example, we're releasing all the available buttons on stick 1.



The next context is the, 'axis' context.  This will let you set a value to any one of the various axes available.  What you will be typing in will look like this: axis;X;1;15000

axis;{axis name};{stick number};{position value}

To set an axis, you always start with the word 'axis'.  The next value is the axis you want to change.  It can be 'X', 'Y', 'Z', 'RX', 'RY', 'RZ', 'SL0' or 'SL1' (without quotes).  In this instance, we are using axis, 'X'.  The next value is, of course, the stick number.  The last value is the position you want to set.  This is a value between 0 and 32767.  In this example, we are using 15000.

Like, 'allbuttons', for initialization/cleanup there is an, 'allaxis' context which will allow you to set all available axes to a value (probably zero in most cases). What you will be typing will look like this:  allaxis;1;0

allaxis;{stick number};{position value}

Pretty straight-forward.  In our example, we are setting all the axes on stick 1 to zero.


To change the POV/hat positions, you will use the 'pov' context.  What you will be typing will look something like this: pov;1;3;17000

pov;{stick number};{pov number};{position value}

To set a pov/hat position, you always start with the word, 'pov'.  The next value is the stick number.  The third value is the pov/hat controller you want to set.  This value will be between 1 and 4 (since you can have only up to four of these per stick).  In our example, we're changing the third pov/hat on the first stick.  The last value is the position value.  This value will need to be between 0 and 35900. 0 is always straight forward with values going clockwise around in a circle.  Right would be around 9000, down would be about 18000, left would be about 27000 (you get the idea).  To set pov/hat in the CENTER (neutral) position, set this value to -1 :  pov;1;3;-1.

Once again, for initialization/cleanup there is the, 'allpov' context.  What you type will look like this: allpov;1;-1

allpov;{stick number};{position value}

Again, pretty straight forward.  In our example, we are setting all available pov/hats on stick 1 to the neutral/center position (-1).


LastVAJOInvokeError text value variable
You'll notice in the sample profile, there's a lot of usage of the following block:
Begin Text Compare : [LastVAJOInvokeError] Does Not Equal ''
    Write '[Orange] {TXT:LastVAJOInvokeError}' to log
End Condition

Each time you execute the plugin, you have the oportunity to examine the LastVAJOInvokeError text value to see if everything went ok.  An empty value in this variable means nothing bad happened.  Anything else is an indication that something went wrong.  In the block above, we're just looking to see if it is not empty.  If it's not empty, we just dump the error to the log.  This is a pretty rigid approach.  Later, there will be extra context values that will allow you to specify what text value to stuff the error message into for a particular action (better for concurrent commands).   If needed, of course...  this could be everything anybody would need already.

Note: If you want to capture the last error, make sure you check the box titled, 'Wait for the plugin function to finish before continuing'...  otherwise, your macro will be long gone before the plugin returns

Hope this all makes sense.  Have fun!