Skip to content

Latest commit

 

History

History
205 lines (132 loc) · 5.97 KB

README.md

File metadata and controls

205 lines (132 loc) · 5.97 KB
Raw

pyvjoystick

pyvjoystick is a set of python binding for different virtual devices. Currently vJoy and ViGEm are supported.

vJoy(on github from jshafer817 and njz3). The implementation of vjoy bindings are inspired on pyvjoy's package.

ViGEm bindings are inspired on vgamepad's package.

Requirements

To be able to use vJoy device install vJoy from sourceforge or github. It is recommended to also install the vJoy Monitor and Configure vJoy programs. These should be an option during installation.

To be able to use ViGem device install release. This package ships with a ViGemClient binaries.

Installation

Simple! This package is installable by pip

pip install pyvjoystick

Usage

vJoy example

With this library you can easily set Axis and Button values on any vJoy device. Low-level bindings are provided in pyvjoy._sdk.

from pyvjoystick import vjoy

# Pythonic API, item-at-a-time
j = vjoy.VJoyDevice(1)

# turn button number 15 on
j.set_button(15, 1)

# Notice the args are (buttonID,state) whereas vJoy's native API is the other way around.


# turn button 15 off again
j.set_button(15, 0)

# Set X axis to fully left
j.set_axis(vjoy.HID_USAGE.X, 0x1)

# Set X axis to fully right
j.set_axis(vjoy.HID_USAGE.X, 0x8000)

# Also implemented:

j.reset()
j.reset_buttons()
j.reset_povs()


# The 'efficient' method as described in vJoy's docs - set multiple values at once

print(j._data)
# >> > <pyvjoystick.vjoy._sdk._JOYSTICK_POSITION_V2 at 0x.... >


j._data.lButtons = 19  # buttons number 1,2 and 5 (1+2+16)
j._data.wAxisX = 0x2000
j._data.wAxisY = 0x7500

# send data to vJoy device
j.update()


# Lower-level API just wraps the functions in the DLL as thinly as possible, with some attempt to raise exceptions instead of return codes.

XBox360 gamepad

The following python script creates a virtual XBox360 gamepad:

from pyvjoystick import vigem as vg

gamepad = vg.VX360Gamepad()

As soon as the VX360Gamepad object is created, the virtual gamepad is connected to your system via the ViGEmBus driver, and will remain connected until the object is destroyed.

Buttons can be pressed and released through press_button and release_button:

gamepad.press_button(button=vg.XUSB_BUTTON.XUSB_GAMEPAD_A)  # press the A button
gamepad.press_button(button=vg.XUSB_BUTTON.XUSB_GAMEPAD_DPAD_LEFT)  # press the left hat button

gamepad.update()  # send the updated state to the computer

# (...) A and left hat are pressed...

gamepad.release_button(button=vg.XUSB_BUTTON.XUSB_GAMEPAD_A)  # release the A button

gamepad.update()  # send the updated state to the computer

# (...) left hat is still pressed...

All available buttons are defined in XUSB_BUTTON

To control the triggers (1 axis each) and the joysticks (2 axis each), two options are provided by the API.

It is possible to input raw integer values directly:

gamepad.left_trigger(value=100)  # value between 0 and 255
gamepad.right_trigger(value=255)  # value between 0 and 255
gamepad.left_joystick(x_value=-10000, y_value=0)  # values between -32768 and 32767
gamepad.right_joystick(x_value=-32768, y_value=15000)  # values between -32768 and 32767

gamepad.update()

Or to input float values:

gamepad.left_trigger_float(value_float=0.5)  # value between 0.0 and 1.0
gamepad.right_trigger_float(value_float=1.0)  # value between 0.0 and 1.0
gamepad.left_joystick_float(x_value_float=-0.5, y_value_float=0.0)  # values between -1.0 and 1.0
gamepad.right_joystick_float(x_value_float=-1.0, y_value_float=0.8)  # values between -1.0 and 1.0

gamepad.update()

Reset to default state:

gamepad.reset()

gamepad.update()

DualShock4 gamepad

Using a virtual DS4 gamepad is similar to X360:

from pyvjoystick import vigem as vg

gamepad = vg.VDS4Gamepad()

Press and release buttons:

gamepad.press_button(button=vg.DS4_BUTTONS.DS4_BUTTON_TRIANGLE)
gamepad.update()

# (...)

gamepad.release_button(button=vg.DS4_BUTTONS.DS4_BUTTON_TRIANGLE)
gamepad.update()

Available buttons are defined in DS4_BUTTONS

Press and release special buttons:

gamepad.press_special_button(special_button=vg.DS4_SPECIAL_BUTTONS.DS4_SPECIAL_BUTTON_PS)
gamepad.update()

# (...)

gamepad.release_special_button(special_button=vg.DS4_SPECIAL_BUTTONS.DS4_SPECIAL_BUTTON_PS)
gamepad.update()

Special buttons are defined in DS4_SPECIAL_BUTTONS

Triggers and joysticks (integer values):

gamepad.left_trigger(value=100)  # value between 0 and 255
gamepad.right_trigger(value=255)  # value between 0 and 255
gamepad.left_joystick(x_value=0, y_value=128)  # value between 0 and 255
gamepad.right_joystick(x_value=0, y_value=255)  # value between 0 and 255

gamepad.update()

Triggers and joysticks (float values):

gamepad.left_trigger_float(value_float=0.5)  # value between 0.0 and 1.0
gamepad.right_trigger_float(value_float=1.0)  # value between 0.0 and 1.0
gamepad.left_joystick_float(x_value_float=-0.5, y_value_float=0.0)  # values between -1.0 and 1.0
gamepad.right_joystick_float(x_value_float=-1.0, y_value_float=0.8)  # values between -1.0 and 1.0

gamepad.update()
  • Note: The Y axis on joysticks is inverted for consistency with the X360 API.

Directional pad (hat):

gamepad.directional_pad(direction=vg.DS4_DPAD_DIRECTIONS.DS4_BUTTON_DPAD_NORTHWEST)
gamepad.update()

Directions for the directional pad are defined in DS4_DPAD_DIRECTIONS

Reset to default state:

gamepad.reset()

gamepad.update()