gamepad_haptics

A Flutter plugin that enables haptic feedback control for game controllers on iOS platform. Experience rich tactile feedback with 18 pre-defined vibration patterns, customizable intensity, and sharpness controls.

pub package License: MIT

Features

  • 🎮 Game Controller Support: Works with connected game controllers (Xbox, PlayStation, etc.)
  • 🌊 18 Vibration Patterns: From relaxing to extreme intensity patterns
  • ⚡ Customizable Parameters: Adjust intensity (0.0-1.0) and sharpness (0.0-1.0)
  • 📱 Cross-Platform: Full support for iOS
  • 🔄 Looping Patterns: Patterns automatically loop for continuous feedback
  • 🎯 Simple API: Easy-to-use interface with minimal setup

Supported Platforms

  • iOS: 14.0 and above (uses Core Haptics with game controllers)

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  gamepad_haptics: ^1.0.0

Then run:

flutter pub get

Platform Setup

iOS

Add the following to your Info.plist:

<key>GCSupportedGameControllers</key>
<array>
  <dict>
    <key>ProfileName</key>
    <string>ExtendedGamepad</string>
  </dict>
</array>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth app required to connect game controllers and play vibrations on it</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Bluetooth app required to connect game controllers and play vibrations on it</string>

Usage

Basic Example

import 'package:gamepad_haptics/gamepad_haptics.dart';

bool isConnected = await GamepadHaptics.isControllerConnected();

await GamepadHaptics.startVibration(
  intensity: 0.8,
  sharpness: 0.7,
  pattern: VibrationPattern.relaxing,
);

await GamepadHaptics.stopVibration();

Advanced Example

import 'package:flutter/material.dart';
import 'package:gamepad_haptics/gamepad_haptics.dart';

class HapticController extends StatefulWidget {
  @override
  _HapticControllerState createState() => _HapticControllerState();
}

class _HapticControllerState extends State<HapticController> {
  double _intensity = 0.8;
  double _sharpness = 0.7;
  VibrationPattern _selectedPattern = VibrationPattern.relaxing;
  bool _isVibrating = false;

  Future<void> _startVibration() async {
    await GamepadHaptics.startVibration(
      intensity: _intensity,
      sharpness: _sharpness,
      pattern: _selectedPattern,
    );
    setState(() => _isVibrating = true);
  }

  Future<void> _stopVibration() async {
    await GamepadHaptics.stopVibration();
    setState(() => _isVibrating = false);
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        DropdownButton<VibrationPattern>(
          value: _selectedPattern,
          items: VibrationPattern.values.map((pattern) {
            return DropdownMenuItem(
              value: pattern,
              child: Text(pattern.displayName),
            );
          }).toList(),
          onChanged: (pattern) {
            setState(() => _selectedPattern = pattern!);
          },
        ),
        Slider(
          value: _intensity,
          onChanged: (value) => setState(() => _intensity = value),
          label: 'Intensity: ${_intensity.toStringAsFixed(2)}',
        ),
        Slider(
          value: _sharpness,
          onChanged: (value) => setState(() => _sharpness = value),
          label: 'Sharpness: ${_sharpness.toStringAsFixed(2)}',
        ),
        ElevatedButton(
          onPressed: _isVibrating ? _stopVibration : _startVibration,
          child: Text(_isVibrating ? 'Stop' : 'Start'),
        ),
      ],
    );
  }
}

Vibration Patterns

The plugin includes 18 pre-defined vibration patterns, each with unique characteristics:

Pattern Description Duration Intensity Level
relaxing Gentle, flowing waves 2.5s Low-Medium
tranquil Slow, peaceful pulses 2.8s Low-Medium
delicate Quick, subtle taps 0.4s Low
gentle Soft, smooth vibrations 1.85s Low-Medium
easy Comfortable, steady rhythm 1.25s Medium
affectionate Warm, embracing pulses 1.85s Medium
moderate Balanced, even vibrations 2.7s Medium
deep Rich, full-bodied pulses 2.3s Medium-High
rhythmic Steady, predictable beats 1.6s Medium
pulsating Regular, strong pulses 1.5s Medium-High
dynamic Varied, energetic patterns 1.8s Medium-High
balanced Harmonious, controlled 2.4s Medium
extreme Intense, powerful bursts 1.35s High
thunder Deep, rolling rumbles 2.2s High
skull Sharp, impactful strikes 0.85s High
volcanic Explosive, building intensity 2.2s High
helicopter Rapid, spinning sensation 0.8s High
tornado Swirling, chaotic pulses 0.85s High

Pattern Details

Each pattern can be customized with:

  • Intensity (0.0 - 1.0): Controls the strength of the vibration
  • Sharpness (0.0 - 1.0): Controls the "feel" (smooth to sharp)

Access pattern information:

String name = VibrationPattern.relaxing.displayName;

double duration = VibrationPattern.relaxing.duration;

API Reference

GamepadHaptics

Main class for controlling haptic feedback.

Methods

startVibration
static Future<void> startVibration({
  double intensity = 1.0,
  double sharpness = 1.0,
  VibrationPattern pattern = VibrationPattern.relaxing,
})

Starts haptic feedback with the specified parameters.

  • intensity: Vibration strength (0.0-1.0, default: 1.0)
  • sharpness: Vibration sharpness (0.0-1.0, default: 1.0)
  • pattern: Vibration pattern to use (default: VibrationPattern.relaxing)
stopVibration
static Future<void> stopVibration()

Stops any ongoing haptic feedback.

isControllerConnected
static Future<bool> isControllerConnected()

Checks if a game controller is connected and supports haptics.

Returns true if a controller is connected, false otherwise.

VibrationPattern

Enum containing all available vibration patterns.

Properties

  • displayName: Human-readable name of the pattern
  • duration: Duration of the pattern in seconds

Values

enum VibrationPattern {
  relaxing,
  tranquil,
  delicate,
  gentle,
  easy,
  affectionate,
  moderate,
  deep,
  rhythmic,
  pulsating,
  dynamic,
  balanced,
  extreme,
  thunder,
  skull,
  volcanic,
  helicopter,
  tornado,
}

Best Practices

  1. Check Controller Connection: Always check if a controller is connected before starting vibration
  2. Stop on Dispose: Stop vibration when leaving a screen or disposing widgets
  3. Intensity Range: Keep intensity between 0.1 and 1.0 for best results
  4. Pattern Selection: Choose patterns that match your app's context
  5. User Control: Provide users with options to disable or adjust haptic feedback

Example App

A complete example app is included in the example folder, demonstrating:

  • Controller connection status
  • Pattern selection dropdown
  • Intensity and sharpness sliders
  • Start/Stop controls
  • Real-time parameter adjustment

To run the example:

cd example
flutter run

Troubleshooting

iOS

Problem: Haptics not working

  • Ensure a compatible game controller is connected (Xbox, PlayStation)
  • Check iOS version is 14.0 or higher
  • Verify Info.plist includes game controller support

Limitations

  • iOS: Requires physical game controller with haptic support
  • Pattern Timing: Patterns automatically loop; customize duration in native code if needed

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, feature requests, or questions, please file an issue on GitHub.

Changelog

See CHANGELOG.md for a list of changes in each version.

Libraries

gamepad_haptics