Joystick basics

Vizard includes a plug-in for accessing data from any DirectInput compatible gamepad and joystick device. (Check out the hardware section for details about specific user interface devices.)

We recommend installing the manufacturer provided drivers for your joystick in order to enable full functionality. Also, you should calibrate your joystick upon installation using the Game Controllers dialog in the Windows Control Panel.

Add device

Adding joystick functionality to your worlds is extremely easy. Simply connect your device, load the DirectInput.dle extension, and use it to add the first detected joystick.

# Load DirectInput plug-in
dinput = viz.add('DirectInput.dle')

# Add first available joystick
joy = dinput.addJoystick()

Gathering input

Joystick objects support the standard extension sensor interface for providing position and button values. They also provide the following methods to access additional data:

Xbox controller objects are accessed using the <dinput>.getXboxControllerList() command mentioned above. They support the above methods in order to provide a consistent interface. However, the following additional methods are provided specifically for Xbox controllers:

Joystick objects will trigger the standard sensor button events (viz.SENSOR_DOWN_EVENT and viz.SENSOR_UP_EVENT) when a joystick button is pressed or released. In addition, they will also trigger the following events when a hat or slider value has changed.

To use joystick functionality in your world you can register a timer function to monitor the joystick values or register a callback to handle button, hat, or slider events. Here is a simple example:

import viz
import vizact
viz.go()

# Add environment model
viz.addChild('maze.osgb')

# Load DirectInput plug-in
dinput = viz.add('DirectInput.dle')

# Add first available joystick
joy = dinput.addJoystick()

# Set dead zone threshold so small movements of joystick are ignored
joy.setDeadZone(0.2)

# Register callbacks to handle input state

def onSensorDown(e):
    print('Button',e.button,'is down')
viz.callback(viz.SENSOR_DOWN_EVENT, onSensorDown)

def onSensorUp(e):
    print('Button',e.button,'is up')
viz.callback(viz.SENSOR_UP_EVENT, onSensorUp)

def onSliderChange(e):
    print('Slider',e.slider,'changed to',e.value)
viz.callback(dinput.SLIDER_EVENT, onSliderChange)

def onHatChange(e):
    print('Hat',e.hat,'changed to',e.value)
viz.callback(dinput.HAT_EVENT, onHatChange)

def UpdateMovement():

    elapsed = viz.elapsed()

    # Get the joystick position
    x,y,z = joy.getPosition()

    # Get the twist of the joystick
    twist = joy.getTwist()

    # Move the viewpoint based on xy-axis value
    move_amount = 5 * elapsed
    viz.MainView.move([x*move_amount,0,y*move_amount], viz.BODY_ORI)

    # Turn the viewpoint left/right based on twist value
    turn_amount = 90 * elapsed
    viz.MainView.setEuler([twist*turn_amount,0,0], viz.BODY_ORI, viz.REL_PARENT)

vizact.ontimer(0, UpdateMovement)

Force feedback

It is possible to apply force feedback. This command will set the auto center mode of the joystick (only available on joysticks with force feedback) and when auto centering is enabled, there will always be a constant force applied to the joystick in the direction of the center.

Method	Description
<dinput>.addJoystick(device=None)	Returns a joystick sensor. If device is None, the next available device will be returned. If device is an object from the <dinput>.getJoystickDevices() list, then the specified device will be returned.
<dinput>.getJoystickDevices()	Return a list of connected joystick device information. Each item in the list contains the following attributes: productName: Product name of the device instanceName: Instance name of the device (typically the same as product name) guid: The globally unique identifier of the device isXboxController: True/False value indicating whether the device is also recognized as an Xbox controller. To use the Xbox specific interface, you must access the object using the <dinput>.getXboxControllerList() command below.
<dinput>.getXboxControllerList()	Returns a list of connected Xbox controller devices.
<dinput>.XBOX_BUTTON_DPAD_UP <dinput>.XBOX_BUTTON_DPAD_DOWN <dinput>.XBOX_BUTTON_DPAD_LEFT <dinput>.XBOX_BUTTON_DPAD_RIGHT <dinput>.XBOX_BUTTON_START <dinput>.XBOX_BUTTON_BACK <dinput>.XBOX_BUTTON_LEFT_THUMB <dinput>.XBOX_BUTTON_RIGHT_THUMB <dinput>.XBOX_BUTTON_LEFT_SHOULDER <dinput>.XBOX_BUTTON_RIGHT_SHOULDER <dinput>.XBOX_BUTTON_A <dinput>.XBOX_BUTTON_B <dinput>.XBOX_BUTTON_X <dinput>.XBOX_BUTTON_Y	Button codes for Xbox controllers.

Method	Description
<joy>.getButtonCount()	Returns the number of buttons on the joystick.
<joy>.getHatCount()	Returns the number of hats on the joystick.
<joy>.getSliderCount()	Returns the number of sliders on the joystick.
<joy>.hasForceFeedback()	Returns whether the joystick supports force feedback
<joy>.hasPositionAxis(axis)	Return whether the joystick provides position data for the specified axis (0-2).
<joy>.hasRotationAxis(axis)	Return whether the joystick provides rotation data for the specified axis (0-2).
<joy>.getPosition()	Return the position along the [x,y,z] axes.
<joy>.getRotation()	Return the rotation about the [x,y,z] axes.
<joy>.getTwist()	Returns the rotation around the Z axis.
<joy>.getButtonState()	Returns the state of all the buttons as a bit flag.
<joy>.isButtonDown(button)	Returns whether the specified button is currently down. Button IDs start at 0.
<joy>.getSlider(index=0)	Return value of slider at specified index.
<joy>.getHat(index=0)	Return value of hat at specified index.
<joy>.setInvertAxis(axis, invert)	Set whether to invert position data on specified axis.
<joy>.getInvertAxis(axis)	Get whether position data on specified axis is inverted.
<joy>.setDeadZone(value)	Set the dead zone threshold for analog values (i.e. position, rotation, and slider). When the absolute value is below the specified dead zone value, then the analog value will be reported as 0. This helps prevent very small motions in the joystick from being reported.
<joy>.getDeadZone()	Get the dead zone threshold for analog values (i.e. position, rotation, and slider).
<joy>.setForce(vector)	Set the [x,y] force feedback vector.
<joy>.setAutoCenter(mode)	Set auto center mode for force feedback device. Can be either True or False.

Method	Description
<xbox>.getControllerID()	Returns the controller ID (0-3).
<xbox>.getConnected()	Returns whether the controller is connected.
<xbox>.getLeftStick()	Returns the left stick position value.
<xbox>.getRightStick()	Returns the right stick position value.
<xbox>.getLeftTrigger()	Returns the left trigger value (0-1).
<xbox>.getRightTrigger()	Returns the right trigger value (0-1).
<xbox>.setInvertLeftStick(value)	Set [x,y] invert flag for left stick.
<xbox>.getInvertLeftStick()	Get [x,y] invert flag for left stick.
<xbox>.setInvertRightStick(value)	Set [x,y] invert flag for right stick.
<xbox>.getInvertRightStick()	Get [x,y] invert flag for right stick
<xbox>.setVibration(value)	Set the [left,right] vibration amount (0-1).
<xbox>.getVibration()	Get the [left,right] vibration amount (0-1).

Joystick basics

Add device

Gathering input

Force feedback

See also

In this section:

Other sections:

Example scripts: