Scripts
A macro can contain one or more script commands. When a macro is triggered, each script command is executed in order from top to bottom. Script commands typically send joystick button presses, keyboard key presses, mouse button presses and mouse axis data to the game.
Some script commands don’t send anything to the game and are used to pause, create loops, run other macros, change curve groups, run a batch file, play a sound or even send data via network UDP to another app.
Here’s a script with all possible script commands used, for illustrative purposes only.
You can have as many commands as you like as there is no upper limit on how long a script can be. The following is a complex script that opens a game menu, does a series of mouse clicks and then closes the game menu.
If you right-click on script list, or click on the script add button, or click on the Script menu, you will see the following menu.
Joystick Buttons
Before you use joystick button script commands, you should define your joystick buttons in the joystick button list, which is located under Joystick in the sidebar. Just double-click on the joystick button needed and type in the name.
Now when you select a joystick button for this script, it is labeled ‘Landing Lights’ instead of just appearing as ‘1’. You can configure up to 128 joystick buttons, although some games may support fewer.
- Joystick Button [DOWN/UP] – Adds joy_button_down, pause 100 milliseconds and joy_button_up commands to the script list. In this example, we would set the in-game control configuration to toggle the landing lights when joystick button #1 is pressed. When this macro is run, joystick #1 button down and up commands will be sent to the game, with a short pause in-between. Most games require a pause and 100 ms is usually adequate, although you may need to change the pause for your game. If the pause is too short, it seems some games just don’t notice the following command (up, in this case). Here is where you select the joystick button and the resulting script.
- Joystick Button [DOWN] – Adds a joy_button_down only.
- Joystick Button [UP] – Adds a joy_button_up only.
Keyboard Keys
You can send individual keyboard_down and keyboard_up commands to the game. You will need to keep track of which up and down commands you are sending.
If you were to send a keyboard_down and don’t send a corresponding keyboard_up, the operating system will still think that key is still pressed and some apps will act a bit odd. To fix it, just physically press and release the key on keyboard.
You can also send a string of text to the game such as might be used in a chat window by using the keyboard_text command.
- Keyboard Text – Adds a string of text with a configurable delay for each key press (down delay) and the delay between each character (interkey delay). For special keys on the left panel, double-click on them to add them to your text string.
Tutorial video showing how to send text.
Some games, although you map for example the key ‘P’, really will only respond to a scripted lower-case ‘p’. So try different cases if it doesn’t seem to be working. Some keys can’t be sent to games, and some games will only recognize certain keys, so you need to experiment to find the right setting for your game.
- Keyboard [DOWN] – Adds a keyboard_down only. Select the key that you want to send by double-clicking the desired key in the list.
- Keyboard [UP] – Adds a keyboard_up only. Select the key that you want to send by double-clicking the desired key in the list.
Mouse Buttons
You can send mouse button down and up commands to the game. If you do the down/up combo, the down delay is built-in and determined by the operating system. If you do just a down, then you will need to add a pause before issuing the up. If you issue a down, but not an up, the game and other apps could act as if the button is still pressed and act strangely. To fix, just physically press and release the mouse button.
- Mouse Button LEFT [DOWN/UP] – Adds a mouse left button down, followed by an operating system determined delay, followed by a mouse left button up.
- Mouse Button LEFT [DOWN] – Adds a mouse left button down only. You will need to add a pause and up.
- Mouse Button LEFT [UP] – Adds a mouse left button up only.
- Mouse Button MIDDLE [DOWN/UP] – Adds a mouse middle button down, followed by an operating system determined delay, followed by a mouse middle button up.
- Mouse Button MIDDLE [DOWN] – Adds a mouse middle button down only. You will need to add a pause and up.
- Mouse Button MIDDLE [UP] – Adds a mouse middle button up only.
- Mouse Button RIGHT [DOWN/UP] – Adds a mouse right button down, followed by an operating system determined delay, followed by a mouse right button up.
- Mouse Button RIGHT [DOWN] – Adds a mouse right button down only. You will need to add a pause and up.
- Mouse Button RIGHT [UP] – Adds a mouse right button up only.
- Mouse ABSOLUTE – Moves the mouse pointer to an absolute x,y position on the screen. 0, 0 is upper left. 65535, 65535 is lower right. (32767, 32767 is the center of the screen).
- Mouse RELATIVE – Moves the mouse pointer relative to it’s current position. Enter x,y pixels to move from current cursor position. Moving right or down is a positive value. (100, 0 moves to the right 100 pixels).
Commands Not Sent to the Game
- Pause – Adds a pause in milliseconds. So a pause of 1000 ms is one second. Most often used between joystick, keyboard or mouse down/up commands. Defaults to 100 ms which is usually adequate.
- Comment – Adds a comment line so that you can document your script to make it easier to understand later.
- Play Sound – Plays a .wav file that you select. Only .wav files are supported. If you have one .wav file playing, and start playing another .wav file, the first .wav file will be stopped. So, the .wav files cannot mix and overlay one another. The .wav files will mix properly with a music player or the game sounds though. If you have a long-running .wav file, the only way to stop playing it is to use the ‘Stop All Running Macros’ script command.
- Curve Groups – Allows you change the active axis curve group. an axis curve is used by each 3Dconnexion controller axis to adjust the axis sensitivity before the axis data is passed to the joystick driver. The curves for all six axis is called a Curve Group. You can create additional curve groups; perhaps one for landing, another one for combat, and another one for mining because these phases of gameplay would normally require unique curves. You can create curve groups in the 3DxWare sidebar panel.
- Repeat START – Adds a ‘start of loop’ marker to the script. You can select how many loop iterations to perform. Loops cannot be nested, which means that you can’t have a loop within a loop. You can get around this limitation by running a Macro SYNCH command within a loop.
- Repeat END – Adds a ‘end of loop’ marker to the script. The commands between the start and end markers will be repeated until the iteration limit you set is finished. Here is an example of a three iteration loop that plays a sound every two seconds. Also shown is the log.
- Macro SYNCH – Adds another script to the current script. This allows you to make a script that calls other scripts but runs them sequentially. The SYNCH parts stands for Synchronous, which means that if this command is encountered, the script that it references will be run in-line with the currently running script. It will all run on the same thread. Use this if you want things to happen serially (in order). You can only add one script to a script.
- Macro ASYNC – Adds another script to the current script. This allows you to make a script that calls other scripts, but runs then simultaneously. The ASYNCH parts stands for Asynchronous, which means that if this command is encountered, the script that it references will be run in-line immediately in it’s own thread and will be running at the same time as the calling macro. Use this if you want a bunch of things to happen at the same time. You can only add one script to a script.
- Run File – Adds a command that will run a DOS batch file. So, if some reason you wanted to toggle the ship lights and transfer a file to another folder, you could do it. It is more of a integration-kind-of-command. You can also use it to open up other apps, like notepad etc.
- Send UDP – Adds a command that sends data via network UDP to another app somewhere on the network. So if you wanted to have a macro that toggle the ship lights and also turned on some real physical lights in your gaming room, you could do this with a clever combination of this command, another app that you create and an interface to the lights, perhaps via Arduino or some other micro-controller. You could also send data to an app on your phone. You can experiment with this command by using the ‘Script Send UDP Receiver’ app that under the Tools menu where you will find more instructions on how to set it all up. Here’s the dialog where you select the destination address, port and data you want to send.
- Stop Running All Macros – Adds a command that will cause all macros to stop running. This is useful if you have some complex macros, especially long-running macros that call other macros. Having a macro that only calls this command is really handy.
- Change Profile – You can select another profile to switch to. This should always be the final command in the script.
- Delete – Removes the currently selected script command. You cannot undo a delete.
- Up – Moves the currently selected script command up in the list so that it is executed earlier.
- Down – Moves the currently selected script command down in the list so that it is executed later.
- Edit – Allows the editing of the currently selected script command.