kikaiken-pycontroller 0.2.0

USB・Bluetooth接続のコントローラ入力状態を取得するシンプルなライブラリ

pycontroller

USB・Bluetooth接続のコントローラ入力状態を取得するシンプルなライブラリです。現在の入力状態のみを扱う、ステートレスな設計になっています。 pygame をバックエンドとして使用しますが、pygame 固有の初期化処理はライブラリ内に隠蔽されています。

インストール

uv add kikaiken-pycontroller

基本的な使い方

Controller を with ブロックで開き、ループ内で read() を呼ぶだけです。

from pycontroller import Controller

with Controller(index=0) as ctrl:
    while True:
        state = ctrl.read()
        print(state.axes.axis0)      # 左スティック X 軸: -1.0 〜 1.0
        print(state.buttons.button0) # ボタン0: True / False
        print(state.hats.hat0)       # 十字キー: (x, y)

API リファレンス

コントローラの検索・接続

接続前にどのコントローラが繋がっているか確認できます。

import pycontroller

# 接続中のコントローラ名一覧
pycontroller.list_controllers()
# => ["Xbox Wireless Controller", "DualSense Wireless Controller"]

# 接続台数を確認したい場合
len(pycontroller.list_controllers())  # => 2

Controller

with ブロックで接続・切断を管理します。複数のコントローラを同時に開くこともできます。

# 1台目
with Controller(index=0) as ctrl:
    print(ctrl.name)   # => "Xbox Wireless Controller"
    state = ctrl.read()

# 2台同時
with Controller(0) as ctrl0, Controller(1) as ctrl1:
    state0 = ctrl0.read()
    state1 = ctrl1.read()

index が接続台数以上の場合は IndexError を送出します。

---

ControllerState — ctrl.read() の戻り値

read() を呼ぶたびに最新の入力状態が得られます。3つの属性を持ちます。

state = ctrl.read()

state.axes    # アナログ軸 → AxesState
state.buttons # ボタン     → ButtonsState
state.hats    # 十字キー   → HatsState

---

AxesState — アナログ軸

値の範囲は -1.0 〜 1.0 です。axis0 〜 axis7 のプロパティ、またはインデックス・イテレーションでアクセスできます。

axes = state.axes

# プロパティ・インデックス (どちらも0始まり)
axes.axis0  # => 0.003
axes.axis1  # => -1.0
axes[0]     # => 0.003

# イテレーション・件数
len(axes)           # => 6
list(axes)          # => [0.003, -1.0, 0.0, 0.0, -1.0, -1.0]

コントローラが持たない番号にアクセスすると IndexError を送出します。

---

ButtonsState — ボタン

値は True(押下中) / False(未押下) です。button0 〜 button19 のプロパティ、またはインデックス・イテレーションでアクセスできます。

buttons = state.buttons

# プロパティ・インデックス (どちらも0始まり)
buttons.button0   # => True
buttons.button1   # => False
buttons[0]        # => True

# イテレーション・件数
len(buttons)      # => 14
list(buttons)     # => [True, False, False, ...]

コントローラが持たない番号にアクセスすると IndexError を送出します。

---

HatsState — 十字キー(ハット)

値は (x, y) の tuple で、各要素は -1、0、1 のいずれかです。hat0 〜 hat3 のプロパティ、またはインデックス・イテレーションでアクセスできます。

hats = state.hats

# プロパティ・インデックス (どちらも0始まり)
hats.hat0   # => (0, 1)  ← 上
hats[0]     # => (0, 1)

# イテレーション・件数
len(hats)   # => 1
list(hats)  # => [(0, 1)]

(x, y)	方向
(0, 0)	ニュートラル
(1, 0)	右
(-1, 0)	左
(0, 1)	上
(0, -1)	下

コントローラが持たない番号にアクセスすると IndexError を送出します。

---

ユーティリティ

pycontroller.utils.inspect(index=None)

接続中のコントローラの軸・ボタン・ハットの状態をリアルタイムで表示します。どのボタンがどのインデックスに対応しているか確認するときに使います。

from pycontroller.utils import inspect

inspect()        # 複数接続時はインデックスを対話的に選択
inspect(index=0) # インデックスを直接指定

Ctrl+C で終了します。