pygame.joystick

與遊戲杆、遊戲手柄、追蹤球進行互動的 pygame 模組。

函式

• pygame.joystick.init()  —  初始化 joystick 模組
• pygame.joystick.quit()  —  解除安裝 joystick 模組
• pygame.joystick.get_init()  —  如果 joystick 模組已經初始化，返回 True
• pygame.joystick.get_count()  —  臨時設定某些組合鍵為被按下狀態

類

• pygame.joystick.Joystick  —  新建一個 Joystick 物件

joystick 模組用來管理電腦上游戲杆類的裝置。遊戲杆類的裝置包括追蹤球和遊戲手柄。這個模組允許使用多個按鈕和“帽鍵”。計算機可同時管理多個遊戲杆類裝置。

溫馨提示：以 PS4 次世代遊戲手柄為例，本文出現的名稱含義如下。

 

Joystick 類的每個例項代表一個插入電腦的遊戲裝置。如果一個遊戲手柄上有多個遊戲杆，在這個遊戲裝置上，一個 Joystick 物件可代表多個遊戲杆。

用下面的程式碼可快速初始化 joystick 模組並且獲得 Joystick 例項的列表：

pygame.joystick.init()
joysticks = [pygame.joystick.Joystick(x) for x in range(pygame.joystick.get_count())]

以下事件型別由 joysticks 生成：

JOYAXISMOTION JOYBALLMOTION JOYBUTTONDOWN JOYBUTTONUP JOYHATMOTION

由於事件佇列中的物件需要經常呼叫一些方法才能正常工作，所以 pygame.event.get，pygame.event.wait 或 pygame.event.pump 函式將會被經常用到。

函式詳解

pygame.joystick.init()

初始化 joystick 模組。

init() -> None

這個函式被 pygame.init() 自動呼叫。

這個函式初始化 joystick 模組，將會掃描系統上所有的遊戲杆裝置。這個模擬塊初始化後其他函式才能工作。

多次呼叫這個函式是沒問題的。

pygame.joystick.quit()

解除安裝 joystick 模組。

quit() -> None

解除安裝 joystick 模組。

在你呼叫這個函式之後，任何遊戲杆物件都不會再工作。

多次呼叫這個函式是沒問題的。

pygame.joystick.get_init()

如果 joystick 模組已經初始化，返回 True。

get_init() -> bool

測試 pygame.joystick.init() 是否已經被呼叫。

pygame.joystick.get_count()

返回遊戲杆的數量。

get_count() -> count

返回在系統上游戲杆裝置的數量；如果沒有操縱桿裝置，返回 0。

當你用 Joystick(id) 建立一個 joystick 物件，你輸入的數字（引數）必須小於這個數。

類 pygame.joystick.Joystick

建立一個新的 Joystick 物件。

Joystick(id) -> Joystick

方法

• pygame.joystick.Joystick.init()  —  初始化
• pygame.joystick.Joystick.quit()  —  解除安裝Joystick
• pygame.joystick.Joystick.get_init()  —  檢查Joystick是否初始化
• pygame.joystick.Joystick.get_id()  —  獲得Joystick ID
• pygame.joystick.Joystick.get_name()  —  獲得 Joystick 系統名稱
• pygame.joystick.Joystick.get_numaxes()  —  獲得 Joystick 操縱軸的數量
• pygame.joystick.Joystick.get_axis()  —  獲得操縱軸的當前座標
• pygame.joystick.Joystick.get_numballs()  —  獲得 Joystick 上追蹤球的數量
• pygame.joystick.Joystick.get_ball()  —  獲得追蹤球的相對位置
• pygame.joystick.Joystick.get_numbuttons()  —  獲得 Joystick 上按鈕的數量
• pygame.joystick.Joystick.get_button()  —  獲得當前按鈕狀態
• pygame.joystick.Joystick.get_numhats()  —  獲得 Joystick 上帽鍵的數量
• pygame.joystick.Joystick.get_hat()  —  獲得 的位置

建立一個新的 Joystick 來訪問物理裝置。這個 id 的值必須在 0 到 pygame.joystick.get_count() - 1 之間。

你需要初始化 Joystick 來呼叫大多數 Joystick 函式。這是獨立於 joystick 模組的初始化。當多個 Joystick 物件在同一個物理裝置上建立時（它們擁有相同的 ID 值），這些 Joystick 物件的狀態和數值將會共享。

Joystick 物件允許你獲得 Joystick 裝置上控制器型別的資訊。一旦這個裝置從 Pygame 事件佇列初始化，它將會開始對其輸入接收事件。

你可以在未初始化 Joystick 物件時，呼叫 Joystick.get_name() 和 Joystick.get_id() 方法。

方法詳解

pygame.joystick.Joystick.init()

初始化 Joystick。

init() -> None

Joystick 必須被初始化來獲得大多數有關控制的資訊。

當 Joystick 初始化之後，Pygame 事件佇列將獲取 Joystick 的輸入。

多次呼叫這個方法是安全的。

pygame.joystick.Joystick.quit()

解除安裝 Joystick。

quit() -> None

這將解除安裝 Joystick。

解除安裝之後，Pygame 事件佇列將不再接收裝置傳來的事件。

多次呼叫這個方法是沒問題的。

pygame.joystick.Joystick.get_init()

檢查 Joystick 是否已經初始化。

get_init() -> bool

當這個 Joystick 物件已經呼叫 init() 函式初始化時，將返回 True。

pygame.joystick.Joystick.get_id()

獲得 Joystick 的 ID。

get_id() -> int

返回代表這個裝置的整型 ID 值。

這和傳遞到 Joystick() 建構函式的值是一樣的。

即便沒有初始化 Joystick，呼叫這個方法也是安全的。

pygame.joystick.Joystick.get_name()

獲得 Joystick 系統的名稱。

get_name() -> string

返回這個 Joystick 裝置的系統名稱。

系統分配給 Joystick 的名稱是不確定的，但可以確保是唯一的名稱來代表這個裝置。

即便沒有初始化 Joystick，呼叫這個方法也是安全的。

pygame.joystick.Joystick.get_numaxes()

獲得 Joystick 操縱軸的數量。

get_numaxes() -> int

返回在 Joystick 上操縱軸的數量。

一般有兩個操縱軸用來表示座標（rudders 和 throttles 被視為附加操縱軸）。

pygame.JOYAXISMOTION 的值是從 -1. 0到 1.0。0.0 表示軸在中間。

遊戲手柄通常只用 -1，0，1 三個值，並且沒有其他中間值。

舊的模擬操縱軸並不是總用完整 -1 到 1 的範圍，而是在 0 左右的值。

模擬操縱軸經常受到一些干擾的影響，這將會導致一些小而快速的移動事件。

pygame.joystick.Joystick.get_axis()

獲得操縱軸的當前座標。

get_axis(axis_number) -> float

獲得操縱軸的當前座標，其值是從 -1.0 到 1.0，0 在中間。

你可能需要考慮一些額外的盈餘來處理抖動，偏移值是在 0 的上下游動。

軸的數量必須是從 0 到 get_numaxes() - 1 的數字。

pygame.joystick.Joystick.get_numballs()

獲得 Joystick 上追蹤球的數量。

get_numballs() -> int

得到 Joystick 上追蹤球的數量。

這些裝置和滑鼠相似，但是它沒有絕對的座標，它只有相對移動數值。

當球轉動的時候，會發送 pygame.JOYBALLMOTION 事件，這將會報告球移動的距離。

pygame.joystick.Joystick.get_ball()

獲得追蹤球的相對位置。

get_ball(ball_number) -> x, y

返回 Joystick 追蹤球的相對移動位置。

數值是自上次呼叫 get_ball 後的相對移動數值，以 x, y 表示。

追蹤球的數量必須是從 0 到 get_numballs() - 1 的數字。

pygame.joystick.Joystick.get_numbuttons()

獲得 Joystick 上按鈕的數量。

get_numbuttons() -> int

返回 Joystick 上按鈕的數量。

這些按鈕有一個布林狀態（開或關）。

當按鈕被按下或擡起的時候，會產生 pygame.JOYBUTTONDOWN 和 pygame.JOYBUTTONUP 事件。

pygame.joystick.Joystick.get_button()

獲得當前按鈕的狀態。

get_button(button) -> bool

返回當前按鈕狀態。

pygame.joystick.Joystick.get_numhats()

獲得 Joystick 上帽鍵的數量。

get_numhats() -> int

返回 Joystick 上帽鍵的數量。帽鍵就像 Joystick 上的微型數碼操縱桿。每個帽鍵有兩個軸作為輸入。

當帽鍵改變座標的時候，會產生 pygame.JOYHATMOTION 事件。事件的位置屬性包含一對數值，這些值可以是 -1，0 或1 。(0, 0) 表示帽鍵在中間。

pygame.joystick.Joystick.get_hat()

獲得 Joystick 上帽鍵的位置。

get_hat(hat_number) -> x, y

返回帽鍵的當前位置。

位置包含 x，y 兩個值。(0, 0) 表示在中間。-1 代表左/下，1 代表右/上。(x 對應左右, y 對應上下)。所以 (-1, 0) 代表左，(1, 0) 代表右，(0, 1) 代表上，(1, 1) 代表右上。

值只能取 -1, 0, 1 不允許其他值。

帽鍵的數量必須在 0 到 get_numhats() - 1 之間。

示例程式碼：

import pygame

# Define some colors
BLACK    = (   0,   0,   0)
WHITE    = ( 255, 255, 255)

# 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, 20)

    def print(self, screen, textString):
        textBitmap = self.font.render(textString, True, BLACK)
        screen.blit(textBitmap, [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
    

pygame.init()

# Set the width and height of the screen [width,height]
size = [500, 700]
screen = pygame.display.set_mode(size)

pygame.display.set_caption("My Game")

#Loop until the user clicks the close button.
done = False

# Used to manage how fast the screen updates
clock = pygame.time.Clock()

# Initialize the joysticks
pygame.joystick.init()
    
# Get ready to print
textPrint = TextPrint()

# -------- Main Program Loop -----------
while done==False:
    # EVENT PROCESSING STEP
    for event in pygame.event.get(): # User did something
        if event.type == pygame.QUIT: # If user clicked close
            done=True # Flag that we are done so we exit this loop
        
        # Possible joystick actions: JOYAXISMOTION JOYBALLMOTION JOYBUTTONDOWN JOYBUTTONUP JOYHATMOTION
        if event.type == pygame.JOYBUTTONDOWN:
            print("Joystick button pressed.")
        if event.type == pygame.JOYBUTTONUP:
            print("Joystick button released.")
            

    # 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(WHITE)
    textPrint.reset()

    # Get count of joysticks
    joystick_count = pygame.joystick.get_count()

    textPrint.print(screen, "Number of joysticks: {}".format(joystick_count) )
    textPrint.indent()
    
    # For each joystick:
    for i in range(joystick_count):
        joystick = pygame.joystick.Joystick(i)
        joystick.init()
    
        textPrint.print(screen, "Joystick {}".format(i) )
        textPrint.indent()
    
        # Get the name from the OS for the controller/joystick
        name = joystick.get_name()
        textPrint.print(screen, "Joystick name: {}".format(name) )
        
        # Usually axis run in pairs, up/down for one, and left/right for
        # the other.
        axes = joystick.get_numaxes()
        textPrint.print(screen, "Number of axes: {}".format(axes) )
        textPrint.indent()
        
        for i in range( axes ):
            axis = joystick.get_axis( i )
            textPrint.print(screen, "Axis {} value: {:>6.3f}".format(i, axis) )
        textPrint.unindent()
            
        buttons = joystick.get_numbuttons()
        textPrint.print(screen, "Number of buttons: {}".format(buttons) )
        textPrint.indent()

        for i in range( buttons ):
            button = joystick.get_button( i )
            textPrint.print(screen, "Button {:>2} value: {}".format(i,button) )
        textPrint.unindent()
            
        # Hat switch. All or nothing for direction, not like joysticks.
        # Value comes back in an array.
        hats = joystick.get_numhats()
        textPrint.print(screen, "Number of hats: {}".format(hats) )
        textPrint.indent()

        for i in range( hats ):
            hat = joystick.get_hat( i )
            textPrint.print(screen, "Hat {} value: {}".format(i, str(hat)) )
        textPrint.unindent()
        
        textPrint.unindent()

    
    # ALL CODE TO DRAW SHOULD GO ABOVE THIS COMMENT
    
    # Go ahead and update the screen with what we've drawn.
    pygame.display.flip()

    # Limit to 20 frames per second
    clock.tick(20)
    
# Close the window and quit.
# If you forget this line, the program will 'hang'
# on exit if running from IDLE.
pygame.quit ()