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

pnpm add controller-sdk
# or
npm install controller-sdk
# or
yarn add controller-sdk

Quick Start

Basic Usage

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

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:

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):

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

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

# Install dependencies
pnpm install

# Build
pnpm build

# Type check
pnpm type-check

# Lint
pnpm lint

License

MIT