-
Notifications
You must be signed in to change notification settings - Fork 6
/
README.rml
160 lines (122 loc) · 6.94 KB
/
README.rml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
[title]XInput-Python[/title]
[subtitle]A simple to use interface to the XInput API for Python.[/subtitle]
[b]XInput-Python[/] provides a few simple methods that can be used to query controller information.
[s1]Tiny Documentation[/]
[i]XInput is Windows only[/]
[s2]Installation[/]
XInput-Python is available from the [url=https://pypi.org]PyPI[/] using
[code]pip install XInput-Python[/code]
It can be inmported like this:
[code]import XInput[/code]
[s2]Using XInput-Python[/]
XInput-Python provides a few functions:
[code]get_connected() -> (bool, bool, bool, bool)[/code] Query which controllers are connected (note: don't query each frame)
[code]get_state(user_index) -> State[/code] Gets the State of the controller [code]user_index[/code]
[code]get_button_values(state) -> dict[/code] Returns a dictionary, showing which buttons are currently being pressed.
[code]get_trigger_values(state) -> (LT, RT)[/code] Returns a tuple with the values of the left and right triggers in range [code]0.0[/] to [code]1.0[/]
[code]get_thumb_values(state) -> ((LX, LY), (RX, RY))[/code] Returns the values of the thumb sticks, expressed in X and Y ranging from [code]0.0[/] to [code]1.0[/]
[code]set_vibration(user_index, left_speed, right_speed) -> bool (Success)[/code] Sets the vibration of the left and right motors of [code]user_index[/] to values between [code]0[/] and [code]65535[/] or in range [code]0.0[/] to [code]1.0[/] respectively.
[code]get_battery_information(user_index) -> (<type>, <level>)[/] Returns the battery information for [code]user_index[/]
[code]set_deadzone(deadzone, value) -> None[/] Sets the deadzone values for left/right thumb stick and triggers.
The following deadzones exist:
[code]XInput.DEADZONE_LEFT_THUMB[/] - (range 0 to 32767) Left thumb stick deadzone (default is 7849)
[code]XInput.DEADZONE_RIGHT_THUMB[/] - (range 0 to 32767) Right thumb stick deadzone (default is 8689)
[code]XInput.DEADZONE_TRIGGER[/] - (range 0 to 255) Trigger deadzone (default is 30)
[s3]Using Events[/]
You can also use the Event-system:
[code]events = get_events()[/code]
[code]get_events[/code] will return a generator that yields instances of the [code]Event[/code] class.
The [code]Event[/code] class always has the following members:
[code]Event.user_index[/code] (range 0 to 3) - the id of the controller that issued this event
[code]Event.type[/code] - which type of event was issued
The following events exist:
[code]XInput.EVENT_CONNECTED == 1[/code] - a controller with this [code]user_index[/code] was connected (this event will even occur if the controller was connected before the script was started)
[code]XInput.EVENT_DISCONNECTED == 2[/code] - a controller with this [code]user_index[/code] was disconnected
[code]XInput.EVENT_BUTTON_PRESSED == 3[/code] - a button was pressed on the controller [code]user_index[/code]
[code]XInput.EVENT_BUTTON_RELEASED == 4[/code] - a button was released on the controller [code]user_index[/code]
[code]XInput.EVENT_TRIGGER_MOVED == 5[/code] - a trigger was moved on the controller [code]user_index[/code]
[code]XInput.EVENT_STICK_MOVED == 6[/code] - a thumb stick was moved on the controller [code]user_index[/code]
[b]Button Events[/]
All button related Events have the following additional members:
[code]Event.button_id[/code] - the XInput numerical representation of the button
[code]Event.button[/code] - a literal representation of the button
The following buttons exist:
[code]"DPAD_UP" == 1
"DPAD_DOWN" == 2
"DPAD_LEFT" == 4
"DPAD_RIGHT" == 8
"START" == 16
"BACK" == 32
"LEFT_THUMB" == 64
"RIGHT_THUMB" == 128
"LEFT_SHOULDER" == 256
"RIGHT_SHOULDER" == 512
"A" == 4096
"B" == 8192
"X" == 16384
"Y" == 32768
[/code]
[b]Trigger Events[/]
All trigger related Events have the following additional members:
[code]Event.trigger[/code] (either [code]XInput.LEFT == 0[/code] or [code]XInput.RIGHT == 1[/code]) - which trigger was moved
[code]Event.value[/code] (range 0.0 to 1.0) - by how much the trigger is currently pressed
[b]Stick Events[/]
All thumb stick related Events have the following additional members:
[code]Event.stick[/code] (either [code]XInput.LEFT == 0[/code] or [code]XInput.RIGHT == 1[/code]) - which stick was moved
[code]Event.x[/code] (range -1.0 to 1.0) - the position of the stick on the X axis
[code]Event.y[/code] (range -1.0 to 1.0) - the position of the stick on the Y axis
[code]Event.value[/code] (range 0.0 to 1.0) - the distance of the stick from it's center position
[code]Event.dir[/code] (tuple of X and Y) - the direction the stick is currently pointing
[s2]Callback events and threading[/]
With the [code]GamepadThread[/code] class it is possible to handle asynchronous events.
To use this feature, extend the [code]EventHandler[/code] to create one or multiple handlers and add them to the thread.
The library will automatically check the status of the gamepad and use the appropriate callback for the triggering event.
It is also possible to filter the inputs for every single handler.
In case of multiple handlers it is possible to use a list of handlers as argument, as well as the [code]add_handler()[/code] method and the [code]remove_handler()[/code] method to remove them.
Filters can be applied to select events of only certain buttons, trigger or stick. Also a "pressed-only" and "released-only" filter is available for buttons.
The available filters are:
[code]
BUTTON_DPAD_UP
BUTTON_DPAD_DOWN
BUTTON_DPAD_LEFT
BUTTON_DPAD_RIGHT
BUTTON_START
BUTTON_BACK
BUTTON_LEFT_THUMB
BUTTON_RIGHT_THUMB
BUTTON_LEFT_SHOULDER
BUTTON_RIGHT_SHOULDER
BUTTON_A
BUTTON_B
BUTTON_X
BUTTON_Y
STICK_LEFT
STICK_RIGHT
TRIGGER_LEFT
TRIGGER_RIGHT
FILTER_PRESSED_ONLY
FILTER_RELEASED_ONLY
[/code]
The filters can be combined by adding them together:
[code]filter1 = STICK_LEFT + STICK_RIGHT + BUTTON_DPAD_DOWN + BUTTON_DPAD_UP
filter2 = BUTTON_Y + BUTTON_X + FILTER_PRESSED_ONLY[/code]
The filter can be applied using add_filter:
[code]handler.add_filter(filter)[/code]
[b]Example[/]
[code]class MyHandler(EventHandler):
def process_button_event(self, event):
# put here the code to parse every event related only to the buttons
def process_trigger_event(self, event):
# event reserved for the two triggers
def process_stick_event(self, event):
# event reserved for the two sticks
def process_connection_event(self, event):
# event related to the gamepad status
filter = STICK_LEFT + STICK_RIGHT
my_handler = MyHandler()
my_handler.add_filter(filter)
my_gamepad_thread = GamepadThread(my_handler)[/code]
The thread will start automatically upon creation. It is possible to stop and start it again if necessary with the two methods [code]start()[/code] and [code]stop()[/code]
[s2]Demo[/]
Run [code]XInputTest.py[/code] to see a visual representation of the controller input.
Run [code]XInputThreadTest.py[/code] to test the visual representation using the asynchronous callbacks.