Metadata-Version: 2.4
Name: kikaiken-pycontroller
Version: 1.0.1
Summary: USB・Bluetooth接続のコントローラ入力状態を取得するシンプルなライブラリ
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pygame>=2.6.1

# kikaiken_pycontroller

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

## インストール

```bash
uv add kikaiken-kikaiken_pycontroller
```

## 基本的な使い方

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

```python
from kikaiken_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 リファレンス

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

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

```python
import kikaiken_pycontroller

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

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

### `Controller`

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

```python
# 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つの属性を持ちます。

```python
state = ctrl.read()

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

---

### `AxesState` — アナログ軸

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

```python
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` のプロパティ、またはインデックス・イテレーションでアクセスできます。

```python
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` のプロパティ、またはインデックス・イテレーションでアクセスできます。

```python
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` を送出します。

---

## ユーティリティ

### `kikaiken_pycontroller.utils.inspect(index=None)`

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

```python
from kikaiken_pycontroller.utils import inspect

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

`Ctrl+C` で終了します。
