Controller SDK

Universal controller SDK for WebHID-compatible game controllers with comprehensive input/output support and testing UI.

Features

- Universal Support: Works with DualSense, DualShock, and extensible for other controllers
- Dual Connection Modes: WebHID (wired) with full features, Gamepad API (wireless) fallback
- Complete Input Detection: Buttons, sticks, triggers, touchpad, motion sensors
- Advanced Haptics: Haptic feedback with presets and custom waveforms
- Adaptive Triggers: Control trigger resistance patterns (wired mode)
- LED Control: RGB color control for controller LEDs
- Event-Driven: Real-time event system for all inputs
- Testing UI: Bundled React component for testing and visualization
- TypeScript: Fully typed with comprehensive type definitions
- Modern Architecture: Clean, extensible design patterns

Installation

``bash
pnpm add controller-sdk


or

npm install controller-sdk

or

yarn add controller-sdk
`

Quick Start

$3

`typescript
import { ControllerManager, HapticPresets } from 'controller-sdk';

const manager = ControllerManager.getInstance();

// Connect to controller
await manager.connect();

// Listen to events
manager.on('button-press', ({ button, state }) => {
console.log(Button ${button} pressed with value ${state.value});
});

manager.on('stick-change', ({ stick, state }) => {
console.log(${stick} stick: x=${state.x}, y=${state.y});
});

// Play haptic feedback
await manager.playHaptic(HapticPresets.fire());

// Set LED color
await manager.setLED(255, 0, 0); // Red

// Disconnect
await manager.disconnect();
`

$3

`tsx
import { ControllerTester } from 'controller-sdk/ui';
import 'controller-sdk/ui/styles.css';

function App() {
return ;
}
`

API Reference

$3

Main singleton class for managing controller connections.

#### Methods

- connect(options?): Connect to a controller
- disconnect(): Disconnect from controller
- getState(): Get current controller state
- getConnectionState(): Get connection state
- getMode(): Get connection mode ('wired' | 'wireless' | 'none')
- getCapabilities(): Get connection capabilities
- playHaptic(preset): Play haptic feedback preset
- stopHaptic(): Stop all haptic feedback
- setTrigger(trigger, preset): Set adaptive trigger resistance
- setLED(r, g, b): Set LED color
- on(event, callback): Add event listener
- off(event, callback): Remove event listener

#### Events

- connect: Fired when controller connects
- disconnect: Fired when controller disconnects
- button-press: Fired when button is pressed
- button-release: Fired when button is released
- stick-change: Fired when stick position changes
- trigger-change: Fired when trigger value changes
- touchpad-change: Fired when touchpad is touched
- motion-change: Fired when motion sensors update

$3

Pre-built haptic feedback patterns:

`typescript
import { HapticPresets } from 'controller-sdk';

// Fire pattern
await manager.playHaptic(HapticPresets.fire());

// Explosion pattern
await manager.playHaptic(HapticPresets.explosion());

// Machine gun pattern
await manager.playHaptic(HapticPresets.machineGun());

// Custom preset
await manager.playHaptic({
type: 'fire',
intensity: 0.8,
duration: 100,
});
`

$3

Adaptive trigger resistance patterns (wired mode only):

`typescript
import { TriggerPresets } from 'controller-sdk';

// Weapon trigger
await manager.setTrigger('right', TriggerPresets.weapon());

// Lock trigger
await manager.setTrigger('left', TriggerPresets.lock());

// Unlock trigger
await manager.setTrigger('right', TriggerPresets.unlock());
`

$3

`typescript
import { DualSenseController, DualShockController } from 'controller-sdk';

// Use DualSense-specific controller
const dualsense = new DualSenseController();
await dualsense.connect();

// Use DualShock-specific controller
const dualshock = new DualShockController();
await dualshock.connect();
`

Architecture

The SDK is built with extensibility in mind:

- Connection Handlers: Abstract interface for different connection types
- Input Processors: Modular processors for each input type
- Output Controllers: Separate controllers for haptics, triggers, and LEDs
- Base Controller: Extensible base class for controller-specific implementations

Browser Support

- WebHID: Chrome/Edge 89+, Opera 75+
- Gamepad API: All modern browsers
- HTTPS Required: WebHID requires secure context (HTTPS or localhost)

Development

`bash


Install dependencies

pnpm install

Build

pnpm build

Type check

pnpm type-check

Lint

pnpm lint
``

License

MIT