Sofa.GamepadController

This module allows you to handle gamepad events in your SOFA scene.

Requirements

SOFA with the SofaPython3 plugin, and the inputs Python library. You can install it with pip:

python3 -m pip install inputs

Usage

There are two important classes for users: GamepadSofaController and GamepadCallbacks

GamepadSofaController needs to be fed a GamepadCallbacks object that implements callbacks for the events that you are interested into.

For example, if you just want to react to a released A button or a left stick movement:

from sofagamepadcontroller import GamepadSofaController, GamepadCallbacks

def createScene(rootnode):

    def printAReleased():
        print("You released A button!")

    def printLeftStickMoved(horizontal, vertical):
        print(f"Left stick moved: horizontal={horizontal}, vertical={vertical}")

    callbacks = GamepadCallbacks()
    callbacks.buttons.south.released = printAReleased
    callbacks.sticks.left.moved = printLeftStickMoved
    # Adds the controller to thhe SOFA scene
    rootnode.addObject(GamepadSofaController(callbacks=callbacks))

You can also run the example scene in runSofa -lSofaPython3 example.py to see how to use the module. It moves a frame in the scene using the left and right sticks. You can also click the A button to invert the axis of the sticks.

Important: The callbacks have a typed signature, check the docstring. You can use captured variables to modify objects inside the callback.

Note: On Windows, if you want to use Dualshock 4 controllers, install DS4Windows. This emulates XBox controllers and make the gamepad compatible with Windows 10+.

List of callbacks

Buttons:

• GamepadCallbacks.buttons.north.pressed()
• GamepadCallbacks.buttons.north.released()
• GamepadCallbacks.buttons.south.pressed()
• GamepadCallbacks.buttons.south.released()
• GamepadCallbacks.buttons.east.pressed()
• GamepadCallbacks.buttons.east.released()
• GamepadCallbacks.buttons.west.pressed()
• GamepadCallbacks.buttons.west.released()

Dpad:

• GamepadCallbacks.dpad.north.pressed()
• GamepadCallbacks.dpad.north.released()
• GamepadCallbacks.dpad.south.pressed()
• GamepadCallbacks.dpad.south.released()
• GamepadCallbacks.dpad.east.pressed()
• GamepadCallbacks.dpad.east.released()
• GamepadCallbacks.dpad.west.pressed()
• GamepadCallbacks.dpad.west.released()

Sticks:

• GamepadCallbacks.sticks.left.moved(horizontal: float, vertical: float)
• GamepadCallbacks.sticks.left.pressed()
• GamepadCallbacks.sticks.left.released()
• GamepadCallbacks.sticks.right.moved(horizontal: float, vertical: float)
• GamepadCallbacks.sticks.right.pressed()
• GamepadCallbacks.sticks.right.released()

Triggers:

• GamepadCallbacks.triggers.left.t()
• GamepadCallbacks.triggers.left.z(value: float)
• GamepadCallbacks.triggers.right.t()
• GamepadCallbacks.triggers.right.z(value: float)

Supported Controllers

The following controllers have been tested and are supported by the module:

• Official Microsoft XBox Series
• TurtleBeach Rematch for XBox (Windows only)
• Official Sony Dualshock 4

In the file state.py you can find the mapping of the buttons and axes for each controller. If you want to add support for a new controller, you can add the mapping in that file and submit a PR. The sticks are mapped between -1 and 1, and the triggers are mapped between 0 and 1.