dkhachatrian / xinput-pybot

XInput recording, VJoy macro playback, and simple template matching-based AI in Python 3.

XInput PyBot

A bot that can perform simple visual pattern matching and play back gamepad macros, split into:

• bot_vision, which implements a BotView class, containing some potentially useful functions for more complicated bots.
• macro_handler, which contains functionality to record macros from an XInput gamepad, convert them to VJoy-readable states, and play these converted macros back on a VJoy device.
• three instances of bot classes inheriting from the BotView class, named evaluator_bot (which implements EvaluatorBot), level_logger (which implements LevelLogger), and seed_finder (which implements SeedFinder).

And a trivial run script.

Dependencies

• VJoy 2.1.8 (and perhaps later) (http://vjoystick.sourceforge.net)
• OpenCV (https://opencv.org/)
• pywin32
• For macro recording and playback:
  • PYXInput (used to record manual XInput macros) (https://github.com/bayangan1991/PYXInput)
  • my fork of pyvjoy (allows for synchronous vjoy device update) (https://github.com/dkhachatrian/pyvjoy)
  • XOutput (wraps vjoy device as XInput device) (https://github.com/csutorasa/XOutput)

How to use

Setting up the "external tubes"

1. Install via pip (or PyPI): pywin32, opencv-python, pyxinput
2. Install VJoy (and reboot as necessary). Ensure the first virtual device has enough buttons to map all XInput buttons (16 is plenty).
3. Download XOutput -- v3.6 recommended to allow dropdown menu for vJoy buttons -- a bit less of a pain to configure. Place in separate folder. (Also install the ViGeM framework for the wrapper to work.)
   • If configuration refuses to save through the program itself, you'll have to manually adjust the settings.txt file it generates when you click "Save Configuration". And example configuration is in the example_configs folder. This example configuration should would with the current setup in macro_handler.py. (The settings.txt generated by the unpacked XOutput.exe will have an HID for the vJoy device in the parenthesis instead of an ellipsis.)
4. Place the version of pyvjoy linked above into your Python's library directory (or really anywhere in your Python's path). Also place vJoyInterface.dll (x86 or x64 depending on your OS), from the VJoy SDK, into the pyvjoy directory.

Configuring macros.

The following need only be done when first recording the macros. Once the macros are saved, the bot scripts will handle vJoy device acquisition (assuming it's free), etc.

Import macro_handler for all of this.

Changing the button mapping (optional).

Currently, the vJoy buttons are mapped according to macro_handler.build_vjoy_button_mapping(xinput_buttons), which converts the one-hot bit vector into an integer (e.g. 0x04 -> 3, since it takes three rightward bit-shifts to convert the bit-vector to zero). You can see the exact mapping by inspecting macro_handler's vjoy_buttons.

Recording macros from an XInput device.

You'll need a handle to your XInput device to record macros.

One way to test is calling macro_handler.test_controller_slot(slot_no) and seeing if the output changes when you press buttons. If it works, respond positively to the prompt and it will return a handle to the XInput device.

Let's assume it's saved to a variable reader. To record a macro, use macro_handler's record_gamepad_reader (read its docstring for specifics). This returns a dictionary. Save this macro into a dictionary of macros, giving it an intuitive name as its key (so you can refer to it more easily in your bot/playback).

Playing back macros on a vJoy device.

(All example scripts and the below discussion assume the VJoy Device being set up is in the first slot: rID = 1.)

On XOutput, set up the vJoy device's button mapping to match the settings in macro_handler.py (check the vjoy_buttons dictionary as necessary). Once the configuration is working, start the wrapper.

Acquire a vJoy device in Python via:

controller = pyvjoy.VJoyDevice(rID=1)

And run/test your macro with macro_handler.run_macro(controller, macro_dict).

Setting up the bot.

After all of this, you can create a Python script and implement a class that extends from bot_vision.BotVision, wire in what window to be looking at, and code the bot's logic. Example bots can be found in the example_bots folder. (Note that the scripts expect to be in the same directory as bot_vision.py and macro_handler.py.)

xinput-pybot's Issues

How to record and playback macros

I came across this which is exactly what I needed but I can't figure out how recording and playing back macros works. I got the test controller working and the values change when I press buttons but I can't figure out how to start recording. I assume I enter the value I got from test controller as the reader and the refresh rate of how many inputs per second but that's as much as I can figure out.
Sorry I know you haven't really done anything with this project in a year but it would be awesome if you could give me some instructions on recording and playing back macros.