kikaiken-pycontroller 0.1.0__py3-none-any.whl

kikaiken_pycontroller-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: kikaiken-pycontroller
+Version: 0.1.0
+Summary: USB・Bluetooth接続のコントローラ入力状態を取得するシンプルなライブラリ
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pygame>=2.6.1
+
+# pycontroller
+
+USB・Bluetooth接続のコントローラ入力状態を取得するシンプルなライブラリです。現在の入力状態のみを扱う、ステートレスな設計になっています。
+pygame をバックエンドとして使用しますが、pygame 固有の初期化処理はライブラリ内に隠蔽されています。
+
+## インストール
+
+```bash
+uv add kikaiken-pycontroller
+```
+
+## 基本的な使い方
+
+`Controller` を `with` ブロックで開き、ループ内で `read()` を呼ぶだけです。
+
+```python
+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 リファレンス
+
+### コントローラの検索・接続
+
+接続前にどのコントローラが繋がっているか確認できます。
+
+```python
+import pycontroller
+
+# 接続中のコントローラ名一覧
+pycontroller.list_controllers()
+# => ["Xbox Wireless Controller", "DualSense Wireless Controller"]
+
+# 接続台数を確認したい場合
+len(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-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pycontroller/__init__.py,sha256=GgsmNuoJRwt8JTdKJKk35A1yv6XNSXZ2XVUbERngR_4,285
+pycontroller/_controller.py,sha256=UwMPsbT0Hxgr5hv9rQzgjfASimgudXrRSh-i201NnqU,2333
+pycontroller/_states.py,sha256=591nte518pSpJNZGwrrVTi7uPaF7gs1c9PxhwBtKeBs,4912
+kikaiken_pycontroller-0.1.0.dist-info/METADATA,sha256=kPu8Nd_wMRniQHRvYEBBodeDgCAxkxkPZxQkGAxBO_w,4496
+kikaiken_pycontroller-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+kikaiken_pycontroller-0.1.0.dist-info/top_level.txt,sha256=waznDYpbhwQXkADVm05smvKghEHKbCmKypLP7TXZPE0,13
+kikaiken_pycontroller-0.1.0.dist-info/RECORD,,

kikaiken_pycontroller-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kikaiken_pycontroller-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pycontroller

pycontroller/__init__.py

@@ -0,0 +1,11 @@
+from pycontroller._controller import Controller, list_controllers
+from pycontroller._states import AxesState, ButtonsState, ControllerState, HatsState
+
+__all__ = [
+    "AxesState",
+    "ButtonsState",
+    "Controller",
+    "ControllerState",
+    "HatsState",
+    "list_controllers",
+]

pycontroller/_controller.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import os
+
+import pygame
+
+from pycontroller._states import AxesState, ButtonsState, ControllerState, HatsState
+
+_open_count = 0
+
+
+def _ensure_init() -> None:
+    os.environ.setdefault("SDL_VIDEODRIVER", "dummy")
+    os.environ.setdefault("SDL_AUDIODRIVER", "dummy")
+    pygame.init()
+
+
+def list_controllers() -> list[str]:
+    if _open_count == 0:
+        _ensure_init()
+    names = [pygame.joystick.Joystick(i).get_name() for i in range(pygame.joystick.get_count())]
+    if _open_count == 0:
+        pygame.quit()
+    return names
+
+
+class Controller:
+    def __init__(self, index: int = 0) -> None:
+        self._index = index
+        self._joystick: pygame.joystick.JoystickType | None = None
+
+    def __enter__(self) -> Controller:
+        global _open_count
+        if _open_count == 0:
+            _ensure_init()
+        _open_count += 1
+        count = pygame.joystick.get_count()
+        if self._index >= count:
+            _open_count -= 1
+            if _open_count == 0:
+                pygame.quit()
+            raise IndexError(
+                f"コントローラ(index={self._index})が見つかりません "
+                f"(接続中のコントローラ数: {count})"
+            )
+        self._joystick = pygame.joystick.Joystick(self._index)
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        global _open_count
+        if self._joystick is not None:
+            self._joystick.quit()
+            self._joystick = None
+        _open_count -= 1
+        if _open_count == 0:
+            pygame.quit()
+
+    def read(self) -> ControllerState:
+        if self._joystick is None:
+            raise RuntimeError("Controller は 'with' ブロック内で使用してください")
+        pygame.event.pump()
+        j = self._joystick
+        return ControllerState(
+            axes=AxesState(tuple(j.get_axis(i) for i in range(j.get_numaxes()))),
+            buttons=ButtonsState(tuple(bool(j.get_button(i)) for i in range(j.get_numbuttons()))),
+            hats=HatsState(tuple(j.get_hat(i) for i in range(j.get_numhats()))),
+        )
+
+    @property
+    def name(self) -> str:
+        if self._joystick is None:
+            raise RuntimeError("Controller は 'with' ブロック内で使用してください")
+        return self._joystick.get_name()
+

pycontroller/_states.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+
+class AxesState:
+    def __init__(self, data: tuple[float, ...]) -> None:
+        self._data = data
+
+    def _get(self, index: int) -> float:
+        if index >= len(self._data):
+            raise IndexError(
+                f"軸{index}は存在しません "
+                f"(このコントローラの軸数: {len(self._data)})"
+            )
+        return self._data[index]
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __iter__(self) -> Iterator[float]:
+        return iter(self._data)
+
+    def __getitem__(self, index: int) -> float:
+        return self._data[index]
+
+    def __repr__(self) -> str:
+        return f"AxesState({self._data})"
+
+    @property
+    def axis0(self) -> float:
+        return self._get(0)
+
+    @property
+    def axis1(self) -> float:
+        return self._get(1)
+
+    @property
+    def axis2(self) -> float:
+        return self._get(2)
+
+    @property
+    def axis3(self) -> float:
+        return self._get(3)
+
+    @property
+    def axis4(self) -> float:
+        return self._get(4)
+
+    @property
+    def axis5(self) -> float:
+        return self._get(5)
+
+    @property
+    def axis6(self) -> float:
+        return self._get(6)
+
+    @property
+    def axis7(self) -> float:
+        return self._get(7)
+
+
+class ButtonsState:
+    def __init__(self, data: tuple[bool, ...]) -> None:
+        self._data = data
+
+    def _get(self, index: int) -> bool:
+        if index >= len(self._data):
+            raise IndexError(
+                f"ボタン{index}は存在しません "
+                f"(このコントローラのボタン数: {len(self._data)})"
+            )
+        return self._data[index]
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __iter__(self) -> Iterator[bool]:
+        return iter(self._data)
+
+    def __getitem__(self, index: int) -> bool:
+        return self._data[index]
+
+    def __repr__(self) -> str:
+        return f"ButtonsState({self._data})"
+
+    @property
+    def button0(self) -> bool:
+        return self._get(0)
+
+    @property
+    def button1(self) -> bool:
+        return self._get(1)
+
+    @property
+    def button2(self) -> bool:
+        return self._get(2)
+
+    @property
+    def button3(self) -> bool:
+        return self._get(3)
+
+    @property
+    def button4(self) -> bool:
+        return self._get(4)
+
+    @property
+    def button5(self) -> bool:
+        return self._get(5)
+
+    @property
+    def button6(self) -> bool:
+        return self._get(6)
+
+    @property
+    def button7(self) -> bool:
+        return self._get(7)
+
+    @property
+    def button8(self) -> bool:
+        return self._get(8)
+
+    @property
+    def button9(self) -> bool:
+        return self._get(9)
+
+    @property
+    def button10(self) -> bool:
+        return self._get(10)
+
+    @property
+    def button11(self) -> bool:
+        return self._get(11)
+
+    @property
+    def button12(self) -> bool:
+        return self._get(12)
+
+    @property
+    def button13(self) -> bool:
+        return self._get(13)
+
+    @property
+    def button14(self) -> bool:
+        return self._get(14)
+
+    @property
+    def button15(self) -> bool:
+        return self._get(15)
+
+    @property
+    def button16(self) -> bool:
+        return self._get(16)
+
+    @property
+    def button17(self) -> bool:
+        return self._get(17)
+
+    @property
+    def button18(self) -> bool:
+        return self._get(18)
+
+    @property
+    def button19(self) -> bool:
+        return self._get(19)
+
+
+class HatsState:
+    def __init__(self, data: tuple[tuple[int, int], ...]) -> None:
+        self._data = data
+
+    def _get(self, index: int) -> tuple[int, int]:
+        if index >= len(self._data):
+            raise IndexError(
+                f"ハット{index}は存在しません "
+                f"(このコントローラのハット数: {len(self._data)})"
+            )
+        return self._data[index]
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __iter__(self) -> Iterator[tuple[int, int]]:
+        return iter(self._data)
+
+    def __getitem__(self, index: int) -> tuple[int, int]:
+        return self._data[index]
+
+    def __repr__(self) -> str:
+        return f"HatsState({self._data})"
+
+    @property
+    def hat0(self) -> tuple[int, int]:
+        return self._get(0)
+
+    @property
+    def hat1(self) -> tuple[int, int]:
+        return self._get(1)
+
+    @property
+    def hat2(self) -> tuple[int, int]:
+        return self._get(2)
+
+    @property
+    def hat3(self) -> tuple[int, int]:
+        return self._get(3)
+
+
+class ControllerState:
+    def __init__(self, axes: AxesState, buttons: ButtonsState, hats: HatsState) -> None:
+        self.axes = axes
+        self.buttons = buttons
+        self.hats = hats
+
+    def __repr__(self) -> str:
+        return f"ControllerState(axes={self.axes!r}, buttons={self.buttons!r}, hats={self.hats!r})"