slot_machine_ui 0.1.2

A highly customizable slot machine widget for Flutter with smooth animations, beautiful skeuomorphic design, and sound support.

# slot_machine_ui

A highly customizable **slot-machine-style UI widget for Flutter**, featuring smooth reel animations, a skeuomorphic design, and optional sound effects.

![Flutter Package](https://img.shields.io/badge/flutter-package-blue)
![Pub Version](https://img.shields.io/pub/v/slot_machine_ui)

![Slot Machine Demo](https://raw.githubusercontent.com/KabyaChalise/slot_machine_ui/main/images/demo.gif)


---

## ✨ Features

- 🎰 Smooth reel animations with configurable timing
- 🎨 Clean skeuomorphic-inspired design
- 🎵 Optional asset-based sound effects (spin & result)
- 🔧 Highly customizable layout, colors, and behavior
- 📱 Responsive sizing for different screen widths
- 🎮 Controller-based API for programmatic control

---

## 📦 Installation

Add the dependency to your `pubspec.yaml`:

```yaml
dependencies:
  slot_machine_ui: ^0.1.0
```

Then run:

```bash
flutter pub get
```

## Basic Usage

```dart
import 'package:flutter/material.dart';
import 'package:slot_machine_ui/slot_machine_ui.dart';

class MySlotMachine extends StatefulWidget {
  @override
  State createState() => _MySlotMachineState();
}

class _MySlotMachineState extends State {
  final _controller = SlotMachineController();
  final _symbols = ['🍒', '🍋', '7️⃣', '💎', '⭐', '🔔'];

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: SlotMachineWidget(
            primaryColor: Colors.redAccent,
            showInnerFrame: true,
            width: 300,
            controller: _controller,
            symbols: _symbols,
            onSpinStart: () {
              debugPrint('Spin started');
            },
            onResult: (results) {
              debugPrint('Spin result: $results');
            },
            onSpinEnd: () {
              debugPrint('Spin ended');
            },
          ),
      ),
    );
  }
}
```

## Advanced Usage

### Custom Colors and Layout

```dart
SlotMachineWidget(
  controller: _controller,
  symbols: _symbols,
  numberOfReels: 4,
  visibleSymbolsPerReel: 3,
  width: 400,
  primaryColor: Color(0xFF2C3E50),
  accentColor: Color(0xFFE74C3C),
  reelBackgroundColor: Colors.white,
  buttonPosition: SpinButtonPosition.below,
  buttonText: 'PULL',
)
```

### Using Image Assets

First, add your images to `pubspec.yaml`:

```yaml
flutter:
  assets:
    - assets/images/cherry.png
    - assets/images/lemon.png
    - assets/images/seven.png
```

Then use them in your widget:

```dart
SlotMachineWidget(
  controller: _controller,
  symbols: [
    'assets/images/cherry.png',
    'assets/images/lemon.png',
    'assets/images/seven.png',
  ],
  useImageAssets: true,
)
```

### Adding Sound Effects

Add sound files to your `pubspec.yaml`:

```yaml
flutter:
  assets:
    - assets/sounds/spin.mp3
    - assets/sounds/win.mp3
```

Then configure the widget:

```dart
SlotMachineWidget(
  controller: _controller,
  symbols: _symbols,
  spinSoundAsset: 'assets/sounds/spin.mp3',
  resultSoundAsset: 'assets/sounds/win.mp3',
)
```

**Note:** Sound playback is handled internally by the package.
Simply provide asset paths for `spinSoundAsset` and `resultSoundAsset`.


### Programmatic Control

```dart
// Spin programmatically
_controller.spin();

// Check if spinning
if (_controller.isSpinning) {
  print('Currently spinning!');
}

// Get results
if (_controller.finalResults != null) {
  print('Last result: ${_controller.finalResults}');
}
```

### Callbacks

```dart
SlotMachineWidget(
  controller: _controller,
  symbols: _symbols,
  onSpinStart: () {
    print('Spin started!');
  },
  onResult: (results) {
    // Check for wins
    bool hasWin = results.every((reel) => reel[0] == results[0][0]);
    if (hasWin) {
      print('Winner! 🎉');
    }
  },
  onSpinEnd: () {
    print('Spin completed!');
  },
)
```

## Customization Options

| Parameter               | Type                    | Default             | Description                                 |
| ----------------------- | ----------------------- | ------------------- | ------------------------------------------- |
| `controller`            | `SlotMachineController` | required            | Controller to manage state                  |
| `symbols`               | `List<String>`          | required            | List of symbols (emoji or asset paths)      |
| `useImageAssets`        | `bool`                  | `false`             | Whether symbols are image asset paths       |
| `numberOfReels`         | `int`                   | `3`                 | Number of reels (columns)                   |
| `visibleSymbolsPerReel` | `int`                   | `3`                 | Visible symbols per reel (rows)             |
| `width`                 | `double?`               | `null`              | Width of machine (auto-sized if null)       |
| `primaryColor`          | `Color`                 | `Color(0xFFE0E0E0)` | Main machine body color                     |
| `accentColor`           | `Color`                 | `Color(0xFFFF3333)` | Spin button color                           |
| `reelBackgroundColor`   | `Color`                 | `Color(0xFFFAFAFA)` | Background color of reels                   |
| `showSpinButton`        | `bool`                  | `true`              | Whether to show the spin button             |
| `buttonPosition`        | `SpinButtonPosition`    | `below`             | Position of button (below/above/left/right) |
| `buttonText`            | `String`                | `'SPIN'`            | Text on the spin button                     |
| `spinSoundAsset`        | `String?`               | `null`              | Asset path for spin sound                   |
| `resultSoundAsset`      | `String?`               | `null`              | Asset path for result sound                 |
| `onResult`              | `Function?`             | `null`              | Callback with final grid results            |
| `onSpinStart`           | `Function?`             | `null`              | Callback when spin starts                   |
| `onSpinEnd`             | `Function?`             | `null`              | Callback when spin ends                     |

## Button Positions

```dart
enum SpinButtonPosition {
  below,  // Button below the machine
  above,  // Button above the machine
  right,  // Button to the right
  left,   // Button to the left
}
```

## Examples

Check out the `example` folder for more complete examples:

- Basic emoji slot machine
- Custom themed machine with images
- Sound-enabled machine
- Programmatic control example

## Tips

1. **Performance**: Use 3-6 symbols for best performance
2. **Responsive Design**: Leave `width` as `null` to auto-size
3. **Win Detection**: Compare symbols in `onResult` callback
4. **Accessibility**: Consider adding haptic feedback for better UX

## Contributing

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

## License

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

## Disclaimer

This package is for educational and entertainment purposes only. Please ensure compliance with local gambling laws and regulations if used in production applications.