react-native-earl-gamepad 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +94 -56
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,12 +1,17 @@
1
1
  # react-native-earl-gamepad
2
2
 
3
- Lightweight, WebView-based Gamepad bridge for React Native that surfaces all common buttons, sticks, d-pad, and connect/disconnect events.
3
+ WebView-based gamepad bridge for React Native. Polls `navigator.getGamepads()` in a hidden WebView and surfaces buttons, sticks, d-pad, and connection events to JS.
4
4
 
5
- ## Features
5
+ - Components: `GamepadBridge`, `useGamepad`, and `GamepadDebug`.
6
+ - Deadzone handling (default `0.15`) with auto-clear on disconnect.
7
+ - Typed events for buttons, axes, d-pad, and status.
6
8
 
7
- - Hidden WebView polling `navigator.getGamepads()` (index 0) and emitting button/axis/status events.
8
- - `GamepadBridge` component, `useGamepad` hook, and `GamepadDebug` visual tester.
9
- - Deadzone handling for sticks (default 0.15) and auto-clear on disconnect.
9
+ ## Requirements
10
+
11
+ - React Native `>=0.72`
12
+ - React `>=18`
13
+ - `react-native-webview` `>=13`
14
+ - Runs on iOS and Android (relies on WebView Gamepad API support).
10
15
 
11
16
  ## Install
12
17
 
@@ -16,91 +21,124 @@ npm install react-native-earl-gamepad react-native-webview
16
21
  yarn add react-native-earl-gamepad react-native-webview
17
22
  ```
18
23
 
19
- ## Quick start
24
+ ## Usage
25
+
26
+ ### Render the bridge (minimal)
27
+
28
+ Render the hidden WebView once in your tree to start polling the first connected pad (`navigator.getGamepads()[0]`).
20
29
 
21
30
  ```tsx
22
- import { GamepadBridge } from 'react-native-earl-gamepad';
31
+ import { GamepadBridge } from "react-native-earl-gamepad";
23
32
 
24
33
  export function Controls() {
25
- return (
26
- <GamepadBridge
27
- enabled
28
- onButton={(e) => console.log('button', e.button, e.pressed, e.value)}
29
- onAxis={(e) => console.log('axis', e.axis, e.value)}
30
- onDpad={(e) => console.log('dpad', e.key, e.pressed)}
31
- onStatus={(s) => console.log('status', s.state)}
32
- />
33
- );
34
+ return (
35
+ <GamepadBridge
36
+ enabled
37
+ onButton={(e) =>
38
+ console.log("button", e.button, e.pressed, e.value)
39
+ }
40
+ onAxis={(e) => console.log("axis", e.axis, e.value)}
41
+ onDpad={(e) => console.log("dpad", e.key, e.pressed)}
42
+ onStatus={(e) => console.log("status", e.state)}
43
+ />
44
+ );
34
45
  }
35
46
  ```
36
47
 
37
- ### Using the hook
48
+ ### Hook for stateful consumption
49
+
50
+ `useGamepad` keeps pressed state and axes for you. You still need to render the provided `bridge` element once.
38
51
 
39
52
  ```tsx
40
- import { useGamepad } from 'react-native-earl-gamepad';
53
+ import { useGamepad } from "react-native-earl-gamepad";
41
54
 
42
55
  export function HUD() {
43
- const { pressedButtons, axes, isPressed, bridge } = useGamepad({ enabled: true });
44
-
45
- return (
46
- <>
47
- {bridge}
48
- <Text>Pressed: {Array.from(pressedButtons).join(', ') || 'none'}</Text>
49
- <Text>
50
- Left stick: x {axes.leftX?.toFixed(2)} / y {axes.leftY?.toFixed(2)}
51
- </Text>
52
- <Text>A held? {isPressed('a') ? 'yes' : 'no'}</Text>
53
- </>
54
- );
56
+ const { pressedButtons, axes, isPressed, bridge } = useGamepad({
57
+ enabled: true,
58
+ });
59
+
60
+ return (
61
+ <>
62
+ {bridge}
63
+ <Text>
64
+ Pressed: {Array.from(pressedButtons).join(", ") || "none"}
65
+ </Text>
66
+ <Text>
67
+ Left stick: x {axes.leftX?.toFixed(2)} / y{" "}
68
+ {axes.leftY?.toFixed(2)}
69
+ </Text>
70
+ <Text>A held? {isPressed("a") ? "yes" : "no"}</Text>
71
+ </>
72
+ );
55
73
  }
56
74
  ```
57
75
 
58
76
  ### Visual debugger
59
77
 
78
+ Drop-in component to see a controller diagram that lights up buttons, shows stick offsets, and lists state.
79
+
60
80
  ```tsx
61
- import { GamepadDebug } from 'react-native-earl-gamepad';
81
+ import { GamepadDebug } from "react-native-earl-gamepad";
62
82
 
63
83
  export function DebugScreen() {
64
- return <GamepadDebug />;
84
+ return <GamepadDebug axisThreshold={0.2} />;
65
85
  }
66
86
  ```
67
87
 
68
- `GamepadDebug` renders a controller diagram that lights up buttons, shows stick offsets, and lists pressed/axes values.
69
-
70
88
  ## API
71
89
 
72
90
  ### `GamepadBridge` props
73
91
 
74
- - `enabled?: boolean` — mount/unmount the hidden WebView. Default `true`.
75
- - `axisThreshold?: number` — deadzone for axes. Default `0.15`.
76
- - `onButton?: (event)` — `{ type:'button', button, index, pressed, value }`.
77
- - `onAxis?: (event)` — `{ type:'axis', axis, index, value }`.
78
- - `onDpad?: (event)` — `{ type:'dpad', key, pressed }` convenience mapped from buttons 12–15.
79
- - `onStatus?: (event)` — `{ type:'status', state:'connected'|'disconnected' }`.
80
- - `style?: StyleProp<ViewStyle>` — optional override; default is a 1×1 transparent view.
92
+ - `enabled?: boolean` — mount/unmount the hidden WebView. Default `true`.
93
+ - `axisThreshold?: number` — deadzone applied to axes. Default `0.15`.
94
+ - `onButton?: (event: ButtonEvent) => void` — fired on button press/release/value change.
95
+ - `onAxis?: (event: AxisEvent) => void` — fired when an axis changes beyond threshold.
96
+ - `onDpad?: (event: DpadEvent) => void` — convenience mapping of button indices 12–15.
97
+ - `onStatus?: (event: StatusEvent) => void` — `connected` / `disconnected` events.
98
+ - `style?: StyleProp<ViewStyle>` — override container; default is a 1×1 transparent view.
81
99
 
82
- ### `useGamepad` return
100
+ ### `useGamepad` options and return
83
101
 
84
- - `pressedButtons: Set<GamepadButtonName>` — current pressed buttons (named or `button-N`).
85
- - `axes: Partial<Record<StickAxisName, number>>` — stick/axis values with deadzone applied.
86
- - `isPressed(key)` — helper to query a button.
87
- - `bridge: JSX.Element | null` — render once in your tree to enable polling.
102
+ Options:
103
+
104
+ - `enabled?: boolean` — defaults to `true`. When false, state resets and axes zero out.
105
+ - `axisThreshold?: number` — deadzone for axes. Default `0.15`.
106
+ - `onButton`, `onAxis`, `onDpad`, `onStatus` — same semantics as `GamepadBridge`.
107
+
108
+ Return shape:
109
+
110
+ - `pressedButtons: Set<GamepadButtonName>` — current pressed buttons.
111
+ - `axes: Partial<Record<StickAxisName, number>>` — axis values with deadzone applied.
112
+ - `isPressed(key: GamepadButtonName): boolean` — helper to check a single button.
113
+ - `bridge: JSX.Element | null` — render once to enable polling.
88
114
 
89
115
  ### `GamepadDebug`
90
116
 
91
- Drop-in component to visualize inputs. Accepts the same `enabled` and `axisThreshold` props as the hook/bridge.
117
+ - `enabled?: boolean` — defaults to `true`.
118
+ - `axisThreshold?: number` — defaults to `0.15`.
119
+
120
+ ## Events and types
121
+
122
+ - `ButtonEvent`: `{ type: 'button'; button: GamepadButtonName; index: number; pressed: boolean; value: number }`
123
+ - `AxisEvent`: `{ type: 'axis'; axis: StickAxisName; index: number; value: number }`
124
+ - `DpadEvent`: `{ type: 'dpad'; key: 'up' | 'down' | 'left' | 'right'; pressed: boolean }`
125
+ - `StatusEvent`: `{ type: 'status'; state: 'connected' | 'disconnected' }`
126
+
127
+ Button names map to the standard gamepad layout (`a`, `b`, `x`, `y`, `lb`, `rb`, `lt`, `rt`, `back`, `start`, `ls`, `rs`, `dpadUp`, `dpadDown`, `dpadLeft`, `dpadRight`, `home`). Unknown indices fall back to `button-N`. Axes map to `leftX`, `leftY`, `rightX`, `rightY` with fallbacks `axis-N`.
92
128
 
93
- ### Types
129
+ ## Behavior notes
94
130
 
95
- - `GamepadButtonName`: `a | b | x | y | lb | rb | lt | rt | back | start | ls | rs | dpadUp | dpadDown | dpadLeft | dpadRight | home | button-N`
96
- - `StickAxisName`: `leftX | leftY | rightX | rightY | axis-N`
131
+ - Reads only the first controller (`navigator.getGamepads()[0]`).
132
+ - D-pad events mirror buttons 12–15; they emit separate `dpad` messages in addition to the raw button events.
133
+ - On disconnect, pressed state is cleared and release events are emitted so you do not get stuck buttons.
134
+ - Keep the bridge mounted; remounting clears internal state and can drop transient events.
135
+ - Axis values below the deadzone are coerced to `0`. Adjust `axisThreshold` if you need more sensitivity.
97
136
 
98
- ## Notes
137
+ ## Patterns
99
138
 
100
- - Reads only the first connected pad (`navigator.getGamepads()[0]`).
101
- - D-pad events are emitted from buttons 12–15; sticks pass through as axes with deadzone applied.
102
- - On disconnect, all pressed states are cleared and release events are emitted.
103
- - The WebView must stay mounted; avoid remounting each render to prevent losing state.
139
+ - **Single place to render**: put the bridge near the root (e.g., inside your `App` provider layer) and consume state anywhere via `useGamepad`.
140
+ - **Status-aware UI**: use `onStatus` to disable controls until `connected` and to reset UI on `disconnected`.
141
+ - **Custom deadzone per screen**: pass `axisThreshold` to either the bridge or the hook depending on which you render.
104
142
 
105
143
  ## Development
106
144
 
@@ -109,7 +147,7 @@ npm install
109
147
  npm run build
110
148
  ```
111
149
 
112
- Outputs to `dist/` with type declarations.
150
+ Build outputs to `dist/` with type declarations.
113
151
 
114
152
  ## License
115
153
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-native-earl-gamepad",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "React Native gamepad bridge via WebView (buttons, sticks, d-pad, status).",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",