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.

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