Модуль Pygame для взаимодействия с джойстиками, геймпадами и трекболами.
Модуль joystick управляет джойстик-устройствами на компьютере. Устройства джойстика включают трекболы и геймпады в стиле видеоигр, и модуль позволяет использовать несколько кнопок и «шайбы». Компьютеры могут управлять несколькими джойстиками одновременно.
Каждый экземпляр класса Joystick представляет одно игровое устройство, подключенное к компьютеру. Если игровой контроллер имеет несколько джойстиков, то объект джойстика фактически может представлять несколько джойстиков на этом единственном игровом устройстве.
Для быстрого инициализации модуля джойстика и получения списка экземпляров Joystick используйте следующий код:
pygame.joystick.init()
joysticks = [pygame.joystick.Joystick(x) for x in range(pygame.joystick.get_count())]
Следующие типы событий будут генерироваться джойстиками
И в pygame 2, который поддерживает горячую замену:
JOYDEVICEADDED JOYDEVICEREMOVED
Обратите внимание, что в pygame 2 события джойстиков используют уникальный «ID экземпляра». Индекс устройства, переданный в конструктор объекта Joystick, не является уникальным после добавления и удаления устройств. Вам необходимо вызвать Joystick.get_instance_id(), чтобы найти ID экземпляра, который был назначен джойстику при открытии.
Для работы некоторых методов необходимо часто обновлять очередь событий. Поэтому регулярно вызывайте одну из функций pygame.event.get, pygame.event.wait или pygame.event.pump.
Чтобы иметь возможность получать события джойстика и обновлять объекты джойстика, когда окно не находится в фокусе, вы можете установить переменную среды SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS. Дополнительные сведения см. в разделе переменные среды.
pygame.joystick.init()
Инициализировать модуль джойстика.
init() -> None
Эта функция вызывается автоматически функцией pygame.init().
Она инициализирует модуль джойстика. Модуль должен быть инициализирован перед работой любых других функций.
Вы можете вызывать эту функцию более одного раза.
pygame.joystick.quit()
Деинициализировать модуль джойстика.
quit() -> None
Деинициализировать модуль джойстика. После вызова этой функции любые существующие объекты джойстика больше не будут работать.
Вы можете вызывать эту функцию более одного раза.
pygame.joystick.get_init()
Возвращает True, если модуль джойстика инициализирован.
get_init() -> bool
Проверить, была ли вызвана функция pygame.joystick.init().
pygame.joystick.get_count()
Возвращает количество джойстиков.
get_count() -> count
Возвращает количество устройств джойстика в системе. Количество будет 0 если в системе нет джойстиков.
При создании объектов Joystick с помощью Joystick(id), вы передаете целое число, которое должно быть меньше этого значения.
pygame.joystick.Joystick
END_OF_DOCUMENT_MARKER
Создать новый объект Joystick.
Joystick(id) -> Joystick
Создаёт новый джойстик для доступа к физическому устройству. Аргумент id должен быть значением из 0 до pygame.joystick.get_count()-1.
Джойстики инициализируются при создании и закрываются при освобождении. После инициализации устройство начинает отправлять события в очередь событий Pygame о своих входных данных.
Изменено в pygame 2.0.0: Объекты Joystick теперь открываются сразу при создании.
init()
Инициализировать джойстик.
init() -> None
Инициализирует джойстик, если он был закрыт. Безопасно вызывать даже если джойстик уже инициализирован.
Устарело начиная с pygame 2.0.0: В будущем не будет возможности повторно инициализировать закрытый объект Joystick. Будет удалено в Pygame 2.1.
quit()
Деинициализировать джойстик.
quit() -> None
Закрыть объект Joystick. После этого очередь событий Pygame больше не будет получать события от устройства.
Безопасно вызывать более одного раза.
get_init()
Проверить, инициализирован ли Joystick.
get_init() -> bool
Возвращает True, если объект Joystick в настоящее время инициализирован.
get_id()
Получить индекс устройства (устарело).
get_id() -> int
Возвращает исходный индекс устройства для этого устройства. Это то же значение, что было передано в конструктор Joystick(). Этот метод можно безопасно вызывать, когда Joystick не инициализирован.
Устарело начиная с pygame 2.0.0: Исходный индекс устройства не полезен в pygame 2. Используйте get_instance_id() вместо этого. Будет удалено в Pygame 2.1.
get_instance_id() → int
Получить идентификатор экземпляра джойстика.
get_instance_id() -> int
Получить идентификатор экземпляра джойстика. Соответствует полю instance_id, которое указывается в событиях джойстика.
Добавлена в pygame 2.0.0dev11.
get_guid() → str
Получить GUID джойстика.
get_guid() -> str
Получить строку GUID. Она идентифицирует конкретное оборудование устройства джойстика.
Добавлена в pygame 2.0.0dev11.
get_power_level() → str
Получить приблизительный статус питания устройства.
get_power_level() -> str
Получить строку, указывающую статус питания устройства.
Одна из: empty, low, medium, full, wired, max, или unknown.
Добавлена в pygame 2.0.0dev11.
get_name()
Получить системное имя джойстика.
get_name() -> string
Возвращает системное имя для этого устройства джойстика. Неизвестно, какое имя система присвоит джойстику, но оно должно быть уникальным именем, идентифицирующим устройство. Этот метод можно безопасно вызывать, когда Joystick не инициализирован.
get_numaxes()
Получить количество осей на джойстике.
get_numaxes() -> int
Возвращает количество входных осей на джойстике. Обычно две для положения. Устройства, такие как штурвалы и дроссели, считаются дополнительными осями.
События pygame.JOYAXISMOTION будут в диапазоне от -1.0 до 1.0. Значение 0.0 означает, что ось находится в центре. Устройства геймпадов обычно будут -1, 0, или 1, без значений между ними. Устаревшие аналоговые джойстики не всегда используют весь диапазон от -1 до 1, и центральное значение будет находиться в некотором диапазоне вокруг 0.
Аналоговые джойстики обычно имеют некоторое количество шума в своих осях, что генерирует много быстрых событий небольших движений.
get_axis()
Получить текущее положение оси.
get_axis(axis_number) -> float
Возвращает текущее положение оси джойстика. Значение будет в диапазоне от -1 до 1, а значение 0 будет соответствовать центру. Возможно, стоит учесть некоторую погрешность для обработки дрожания и дрейфа джойстика, который может не центрироваться на 0, или использовать весь диапазон значений положения.
Номер оси должен быть целым числом от 0 до get_numaxes()-1.
При использовании геймпадов как стики управления, так и аналоговые триггеры обычно отображаются как оси.
get_numballs()
Получить количество трекболлов на джойстике.
get_numballs() -> int
Возвращает количество устройств трекболов на джойстике. Эти устройства работают аналогично мыши, но у них нет абсолютного положения; они имеют только относительные значения перемещения.
Событие pygame.JOYBALLMOTION будет отправлено, когда трекбол прокручивается. Оно сообщит об объёме движения трекбола.
get_ball()
Получить относительное положение трекбола.
get_ball(ball_number) -> x, y
Возвращает относительное перемещение кнопки джойстика. Значение представляет собой пару x,y, содержащую относительное перемещение с момента последнего вызова get_ball.
Номер шара должен быть целым числом от 0 до get_numballs()-1.
get_numbuttons()
Получить количество кнопок на джойстике.
get_numbuttons() -> int
Возвращает количество нажимаемых кнопок на джойстике. Эти кнопки имеют булево (включено или выключено) состояние.
Кнопки генерируют события pygame.JOYBUTTONDOWN и pygame.JOYBUTTONUP при нажатии и отпускании.
get_button()
Получить текущее состояние кнопки.
get_button(button) -> bool
Возвращает текущее состояние кнопки джойстика.
get_numhats()
Получить количество регуляторов рычага на джойстике.
get_numhats() -> int
Возвращает количество рычагов на джойстике. Устройства рычага — это миниатюрные цифровые джойстики на джойстике. Каждый рычаг имеет две оси ввода.
Событие pygame.JOYHATMOTION генерируется при изменении положения рычага. Атрибут position события содержит пару значений, которые могут быть -1, 0, или 1. Положение (0,0) означает, что рычаг находится в центре.
get_hat()
Получить положение рычага джойстика.
get_hat(hat_number) -> x, y
Возвращает текущее положение рычага. Положение задается двумя значениями, представляющими положение x и y рычага. (0,0) означает центр. Значение -1 означает влево/вниз, а значение 1 означает вправо/вверх: таким образом (-1,0) означает влево; (1,0) означает вправо; (0,1) означает вверх; (1,1) означает верхний правый угол и так далее.
Это цифровое значение, i.e., каждая координата может быть -1, 0 или 1, но никогда не между ними.
Запускает вибрацию джойстика с заданной силой, изменяющейся от 0 до 1. Параметр duration определяет длительность эффекта в миллисекундах. Установка duration в 0 запустит эффект до момента его перезаписи другим эффектом или вызова метода Joystick.stop_rumble(). Если эффект уже воспроизводится, он будет перезаписан.
Возвращает True, если вибрация была успешно запущена, или False, если джойстик не поддерживает вибрацию или версия pygame.version.SDL() ниже 2.0.9.
Добавлена в pygame 2.0.2.
stop_rumble()
Остановить любую вибрацию джойстика
stop_rumble() -> None
Останавливает любой воспроизводимый эффект вибрации джойстика. Подробнее см. Joystick.rumble().
import pygame
pygame.init()
# This is a simple class that will help us print to the screen.
# It has nothing to do with the joysticks, just outputting the
# information.
class TextPrint:
def __init__(self):
self.reset()
self.font = pygame.font.Font(None, 25)
def tprint(self, screen, text):
text_bitmap = self.font.render(text, True, (0, 0, 0))
screen.blit(text_bitmap, (self.x, self.y))
self.y += self.line_height
def reset(self):
self.x = 10
self.y = 10
self.line_height = 15
def indent(self):
self.x += 10
def unindent(self):
self.x -= 10
def main():
# Set the width and height of the screen (width, height), and name the window.
screen = pygame.display.set_mode((500, 700))
pygame.display.set_caption("Joystick example")
# Used to manage how fast the screen updates.
clock = pygame.time.Clock()
# Get ready to print.
text_print = TextPrint()
# This dict can be left as-is, since pygame will generate a
# pygame.JOYDEVICEADDED event for every joystick connected
# at the start of the program.
joysticks = {}
done = False
while not done:
# Event processing step.
# Possible joystick events: JOYAXISMOTION, JOYBALLMOTION, JOYBUTTONDOWN,
# JOYBUTTONUP, JOYHATMOTION, JOYDEVICEADDED, JOYDEVICEREMOVED
for event in pygame.event.get():
if event.type == pygame.QUIT:
done = True # Flag that we are done so we exit this loop.
if event.type == pygame.JOYBUTTONDOWN:
print("Joystick button pressed.")
if event.button == 0:
joystick = joysticks[event.instance_id]
if joystick.rumble(0, 0.7, 500):
print(f"Rumble effect played on joystick {event.instance_id}")
if event.type == pygame.JOYBUTTONUP:
print("Joystick button released.")
# Handle hotplugging
if event.type == pygame.JOYDEVICEADDED:
# This event will be generated when the program starts for every
# joystick, filling up the list without needing to create them manually.
joy = pygame.joystick.Joystick(event.device_index)
joysticks[joy.get_instance_id()] = joy
print(f"Joystick {joy.get_instance_id()} connencted")
if event.type == pygame.JOYDEVICEREMOVED:
del joysticks[event.instance_id]
print(f"Joystick {event.instance_id} disconnected")
# Drawing step
# First, clear the screen to white. Don't put other drawing commands
# above this, or they will be erased with this command.
screen.fill((255, 255, 255))
text_print.reset()
# Get count of joysticks.
joystick_count = pygame.joystick.get_count()
text_print.tprint(screen, f"Number of joysticks: {joystick_count}")
text_print.indent()
# For each joystick:
for joystick in joysticks.values():
jid = joystick.get_instance_id()
text_print.tprint(screen, f"Joystick {jid}")
text_print.indent()
# Get the name from the OS for the controller/joystick.
name = joystick.get_name()
text_print.tprint(screen, f"Joystick name: {name}")
guid = joystick.get_guid()
text_print.tprint(screen, f"GUID: {guid}")
power_level = joystick.get_power_level()
text_print.tprint(screen, f"Joystick's power level: {power_level}")
# Usually axis run in pairs, up/down for one, and left/right for
# the other. Triggers count as axes.
axes = joystick.get_numaxes()
text_print.tprint(screen, f"Number of axes: {axes}")
text_print.indent()
for i in range(axes):
axis = joystick.get_axis(i)
text_print.tprint(screen, f"Axis {i} value: {axis:>6.3f}")
text_print.unindent()
buttons = joystick.get_numbuttons()
text_print.tprint(screen, f"Number of buttons: {buttons}")
text_print.indent()
for i in range(buttons):
button = joystick.get_button(i)
text_print.tprint(screen, f"Button {i:>2} value: {button}")
text_print.unindent()
hats = joystick.get_numhats()
text_print.tprint(screen, f"Number of hats: {hats}")
text_print.indent()
# Hat position. All or nothing for direction, not a float like
# get_axis(). Position is a tuple of int values (x, y).
for i in range(hats):
hat = joystick.get_hat(i)
text_print.tprint(screen, f"Hat {i} value: {str(hat)}")
text_print.unindent()
text_print.unindent()
# Go ahead and update the screen with what we've drawn.
pygame.display.flip()
# Limit to 30 frames per second.
clock.tick(30)
if __name__ == "__main__":
main()
# If you forget this line, the program will 'hang'
# on exit if running from IDLE.
pygame.quit()
Сопоставления контроллеров взяты из базовой библиотеки SDL, которую использует pygame, и они отличаются между pygame 1 и pygame 2. Ниже приведены несколько сопоставлений для трёх популярных контроллеров.
Оси и нажатия перечислены от -1 до +1.
Nintendo Switch Left Joy-Con (pygame 2.x)
У Nintendo Switch Left Joy-Con 4 оси, 11 кнопок и 0 нажатий. Значения для 4 осей никогда не меняются. Контроллер распознаётся как "Беспроводной геймпад"
Кнопки:
D-pad Up - Button 0
D-pad Down - Button 1
D-pad Left - Button 2
D-pad Right - Button 3
SL - Button 4
SR - Button 5
- - Button 8
Stick In - Button 10
Capture - Button 13
L - Button 14
ZL - Button 15
Нажатие/Джойстик:
Down -> Up - Y Axis
Left -> Right - X Axis
Nintendo Switch Right Joy-Con (pygame 2.x)
У Nintendo Switch Right Joy-Con 4 оси, 11 кнопок и 0 нажатий. Значения для 4 осей никогда не меняются. Контроллер распознаётся как "Беспроводной геймпад"
Кнопки:
A Button - Button 0
B Button - Button 1
X Button - Button 2
Y Button - Button 3
SL - Button 4
SR - Button 5
+ - Button 9
Stick In - Button 11
Home - Button 12
R - Button 14
ZR - Button 15
Нажатие/Джойстик:
Down -> Up - Y Axis
Left -> Right - X Axis
Nintendo Switch Pro Controller (pygame 2.x)
У Nintendo Switch Pro Controller 6 осей, 16 кнопок и 0 нажатий. Контроллер распознаётся как "Nintendo Switch Pro Controller".
Левый стик:
Left -> Right - Axis 0
Up -> Down - Axis 1
Правый стик:
Left -> Right - Axis 2
Up -> Down - Axis 3
Левый триггер:
Out -> In - Axis 4
Правый триггер:
Out -> In - Axis 5
Кнопки:
A Button - Button 0
B Button - Button 1
X Button - Button 2
Y Button - Button 3
- Button - Button 4
Home Button - Button 5
+ Button - Button 6
L. Stick In - Button 7
R. Stick In - Button 8
Left Bumper - Button 9
Right Bumper - Button 10
D-pad Up - Button 11
D-pad Down - Button 12
D-pad Left - Button 13
D-pad Right - Button 14
Capture Button - Button 15
XBox 360 Controller (pygame 2.x)
Карта сопоставления контроллера Xbox 360 имеет 6 осей, 11 кнопок и 1 нажатие. Контроллер распознаётся как "Xbox 360 Controller".
Левый стик:
Left -> Right - Axis 0
Up -> Down - Axis 1
Правый стик:
Left -> Right - Axis 3
Up -> Down - Axis 4
Левый триггер:
Out -> In - Axis 2
Правый триггер:
Out -> In - Axis 5
Кнопки:
A Button - Button 0
B Button - Button 1
X Button - Button 2
Y Button - Button 3
Left Bumper - Button 4
Right Bumper - Button 5
Back Button - Button 6
Start Button - Button 7
L. Stick In - Button 8
R. Stick In - Button 9
Guide Button - Button 10
Нажатие/D-пад:
Down -> Up - Y Axis
Left -> Right - X Axis
Playstation 4 Controller (pygame 2.x)
Карта сопоставления контроллера PlayStation 4 имеет 6 осей и 16 кнопок. Контроллер распознаётся как "PS4 Controller".
Левый стик:
Left -> Right - Axis 0
Up -> Down - Axis 1
Правый стик:
Left -> Right - Axis 2
Up -> Down - Axis 3
Левый триггер:
Out -> In - Axis 4
Правый триггер:
Out -> In - Axis 5
Кнопки:
Cross Button - Button 0
Circle Button - Button 1
Square Button - Button 2
Triangle Button - Button 3
Share Button - Button 4
PS Button - Button 5
Options Button - Button 6
L. Stick In - Button 7
R. Stick In - Button 8
Left Bumper - Button 9
Right Bumper - Button 10
D-pad Up - Button 11
D-pad Down - Button 12
D-pad Left - Button 13
D-pad Right - Button 14
Touch Pad Click - Button 15
XBox 360 Controller (pygame 1.x)
Карта сопоставления контроллера Xbox 360 имеет 5 осей, 10 кнопок и 1 нажатие. Контроллер распознаётся как "Controller (XBOX 360 For Windows)".
Левый стик:
Left -> Right - Axis 0
Up -> Down - Axis 1
Правый стик:
Left -> Right - Axis 4
Up -> Down - Axis 3
Левый триггер & Правый триггер:
RT -> LT - Axis 2
Кнопки:
A Button - Button 0
B Button - Button 1
X Button - Button 2
Y Button - Button 3
Left Bumper - Button 4
Right Bumper - Button 5
Back Button - Button 6
Start Button - Button 7
L. Stick In - Button 8
R. Stick In - Button 9
Нажатие/D-пад:
Down -> Up - Y Axis
Left -> Right - X Axis
Playstation 4 Controller (pygame 1.x)
Карта сопоставления контроллера PlayStation 4 имеет 6 осей, 14 кнопок и 1 нажатие. Контроллер распознаётся как "Беспроводной контроллер".
Левый стик:
Left -> Right - Axis 0
Up -> Down - Axis 1
Правый стик:
Left -> Right - Axis 2
Up -> Down - Axis 3
Левый триггер:
Out -> In - Axis 5
Правый триггер:
Out -> In - Axis 4
Кнопки:
Cross Button - Button 0
Circle Button - Button 1
Square Button - Button 2
Triangle Button - Button 3
Left Bumper - Button 4
Right Bumper - Button 5
L. Trigger(Full)- Button 6
R. Trigger(Full)- Button 7
Share Button - Button 8
Options Button - Button 9
L. Stick In - Button 10
R. Stick In - Button 11
PS Button - Button 12
Touch Pad Click - Button 13
