npm package: @shreyansh-node/controller-manager
Description: Universal controller SDK for WebHID-compatible game controllers with input/output support and testing UI
Latest version: 1.0.6

# 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

### Basic Usage

```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();
```

### Using the Testing UI

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

function App() {
  return <ControllerTester />;
}
```

## API Reference

### ControllerManager

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

### Haptic Presets

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,
});
```

### Trigger Presets

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());
```

### Controller-Specific Implementations

```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