Metadata-Version: 2.4
Name: telegram-slot-map
Version: 1.0.2
Summary: Complete and customizable mapping of Telegram slot machine (🎰) dice values (1-64) to symbol combinations
Author-email: Matychka <mmatychka@gmail.com>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file


# telegram-slot-map

**Полная и настраиваемая расшифровка всех 64 исходов слота 🎰 в Telegram.**

Когда бот отправляет `dice` с эмодзи 🎰, сервер возвращает `dice.value` — число от 1 до 64.
Эта библиотека даёт точное соответствие каждой комбинации символов и позволяет **заменить их на свои эмодзи, стикеры или текст**.

---

## 📦 Установка

```bash
pip install telegram-slot-map
```

---

## 🎯 Зачем это нужно?

Когда вы создаете Telegram бота с игровым функционалом (казино, слоты), вам нужно:
1. **Понимать результат** — что выпало на слоте по числу от 1 до 64
2. **Кастомизировать внешний вид** — заменить стандартные символы на свои
3. **Реализовать игровую логику** — проверять выигрышные комбинации

Эта библиотека решает все три задачи!

---

## 🚀 Быстрый старт

### Что вы получаете от Telegram?

Когда бот отправляет dice с эмодзи 🎰:

```python
# Пример с aiogram
from aiogram import Bot, types

bot = Bot(token="YOUR_TOKEN")

# Отправляем слот
message = await bot.send_dice(chat_id=chat_id, emoji="🎰")

# Telegram возвращает число от 1 до 64
dice_value = message.dice.value  # Например: 22
```

### Что делает библиотека?

Преобразует это число в понятную комбинацию символов:

```python
from slotmap import get_slot_combination

result = get_slot_combination(22)
print(result)
# Вывод: "cherry cherry cherry"
```

---

## 📖 Примеры использования

### 1. Базовый пример — получить комбинацию

```python
from slotmap import get_slot_combination

# Получаем комбинацию по значению dice
result = get_slot_combination(1)
print(result)  # "bar bar bar"

result = get_slot_combination(43)
print(result)  # "lemon lemon lemon"

result = get_slot_combination(64)
print(result)  # "seven seven seven"
```

**Что получаете:** строку с названиями символов через пробел.

---

### 2. Кастомизация — свои эмодзи и символы

Самая мощная функция! Замените стандартные названия на любые эмодзи, текст или даже ID стикеров.

```python
from slotmap import get_slot_combination

# Создаем свой маппинг
MY_SYMBOLS = {
    'bar': '➖',
    'cherry': '🍒',
    'lemon': '🍋',
    'seven': '7️⃣'
}

# Передаем в функцию
print(get_slot_combination(1, symbols=MY_SYMBOLS))
# Вывод: "➖ ➖ ➖"

print(get_slot_combination(22, symbols=MY_SYMBOLS))
# Вывод: "🍒 🍒 🍒"

print(get_slot_combination(64, symbols=MY_SYMBOLS))
# Вывод: "7️⃣ 7️⃣ 7️⃣"
```

**Ключи для замены:** `'bar'`, `'cherry'`, `'lemon'`, `'seven'`

---

### 3. Использование в боте — полный пример

```python
from aiogram import Bot, Dispatcher, types
from aiogram.filters import Command
from slotmap import get_slot_combination

bot = Bot(token="YOUR_TOKEN")
dp = Dispatcher()

# Ваши кастомные символы
CASINO_SYMBOLS = {
    'bar': '💎',
    'cherry': '🍒',
    'lemon': '🍋',
    'seven': '🔥'
}

@dp.message(Command("spin"))
async def spin_slot(message: types.Message):
    # Отправляем слот
    slot_message = await message.answer_dice(emoji="🎰")
    
    # Ждем результат (Telegram присылает его через ~3 секунды)
    await asyncio.sleep(3)
    
    # Получаем значение
    dice_value = slot_message.dice.value
    
    # Преобразуем в красивую строку
    result = get_slot_combination(dice_value, symbols=CASINO_SYMBOLS)
    
    # Отправляем пользователю
    await message.answer(f"Результат: {result}")

if __name__ == "__main__":
    dp.run_polling(bot)
```

**Что получает пользователь:**
```
/spin
🎰 [анимация слота]
Результат: 🍒 🍒 🍒
```

---

### 4. Игровая логика — проверка выигрышей

Для реализации казино нужно проверять комбинации. Используйте `RAW_SLOT_COMBINATIONS`:

```python
from slotmap import RAW_SLOT_COMBINATIONS

dice_value = 22  # Значение от Telegram

# Получаем список символов
combo = RAW_SLOT_COMBINATIONS[str(dice_value)]
print(combo)  # ['cherry', 'cherry', 'cherry']

# Проверяем выигрыш
if combo[0] == combo[1] == combo[2]:
    print("ДЖЕКПОТ! Все три символа совпали!")
    win_amount = 1000
elif combo[0] == combo[1]:
    print("Малый выигрыш! Первые два совпали.")
    win_amount = 100
else:
    print("Не повезло. Попробуй еще раз!")
    win_amount = 0
```

---

### 5. Продвинутый пример — система выплат

```python
from slotmap import RAW_SLOT_COMBINATIONS

# Таблица выплат
PAYOUTS = {
    'seven': 100,   # Семерка — самая ценная
    'cherry': 50,
    'lemon': 30,
    'bar': 10
}

def calculate_win(dice_value: int, bet: int) -> int:
    """Рассчитывает выигрыш на основе комбинации"""
    combo = RAW_SLOT_COMBINATIONS[str(dice_value)]
    
    # Все три символа совпали
    if combo[0] == combo[1] == combo[2]:
        symbol = combo[0]
        multiplier = PAYOUTS[symbol]
        return bet * multiplier
    
    # Первые два совпали
    elif combo[0] == combo[1]:
        symbol = combo[0]
        multiplier = PAYOUTS[symbol] // 5
        return bet * multiplier
    
    # Проигрыш
    return 0

# Примеры
print(calculate_win(64, bet=10))  # seven-seven-seven: 10 * 100 = 1000
print(calculate_win(22, bet=10))  # cherry-cherry-cherry: 10 * 50 = 500
print(calculate_win(11, bet=10))  # lemon-lemon-bar: 10 * 6 = 60
print(calculate_win(2, bet=10))   # cherry-bar-bar: 0
```

---

### 6. Использование с другими библиотеками

#### python-telegram-bot

```python
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
from slotmap import get_slot_combination

SYMBOLS = {'bar': '💎', 'cherry': '🍒', 'lemon': '🍋', 'seven': '🔥'}

async def spin(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # Отправляем слот
    msg = await update.message.reply_dice(emoji="🎰")
    
    # Ждем результат
    await asyncio.sleep(3)
    
    # Получаем и форматируем
    result = get_slot_combination(msg.dice.value, symbols=SYMBOLS)
    await update.message.reply_text(f"Выпало: {result}")

app = Application.builder().token("YOUR_TOKEN").build()
app.add_handler(CommandHandler("spin", spin))
app.run_polling()
```

#### Telethon

```python
from telethon import TelegramClient, events
from slotmap import get_slot_combination

client = TelegramClient('session', api_id, api_hash)

@client.on(events.NewMessage(pattern='/spin'))
async def handler(event):
    msg = await client.send_file(event.chat_id, file=types.InputMediaDice(emoticon='🎰'))
    
    await asyncio.sleep(3)
    
    result = get_slot_combination(msg.media.value)
    await event.respond(f"Результат: {result}")

client.start()
client.run_until_disconnected()
```

---

## 📚 API Reference

### `get_slot_combination(value, symbols=None)`

Преобразует значение dice в строку с символами.

**Параметры:**
- `value` (int): Число от 1 до 64 (значение `dice.value` от Telegram)
- `symbols` (dict, optional): Словарь замены символов. Ключи: `'bar'`, `'cherry'`, `'lemon'`, `'seven'`

**Возвращает:**
- `str`: Строка из трех символов, разделенных пробелами

**Исключения:**
- `ValueError`: Если value не в диапазоне 1-64

**Примеры:**
```python
get_slot_combination(1)  # "bar bar bar"
get_slot_combination(22, {'cherry': '🍒'})  # "🍒 🍒 🍒"
```

---

### `RAW_SLOT_COMBINATIONS`

Словарь всех 64 комбинаций в виде списков.

**Тип:** `dict[str, list[str]]`

**Структура:**
```python
{
    '1': ['bar', 'bar', 'bar'],
    '2': ['cherry', 'bar', 'bar'],
    ...
    '64': ['seven', 'seven', 'seven']
}
```

**Использование:**
```python
from slotmap import RAW_SLOT_COMBINATIONS

combo = RAW_SLOT_COMBINATIONS['22']  # ['cherry', 'cherry', 'cherry']
```

---

### `DEFAULT_SYMBOLS`

Стандартные символы, используемые по умолчанию.

**Тип:** `dict[str, str]`

**Значение:**
```python
{
    'bar': 'bar',
    'cherry': '🍒',
    'lemon': '🍋',
    'seven': '7️⃣'
}
```

---

## 🎲 Справочник всех комбинаций

Всего в Telegram slot machine 4 типа символов:

| Ключ | Описание | Стандартный вид |
|------|----------|-----------------|
| `bar` | Надпись BAR | bar |
| `cherry` | Вишня/Виноград | 🍒 |
| `lemon` | Лимон | 🍋 |
| `seven` | Семерка | 7️⃣ |

### Примеры значений:

| dice.value | Комбинация |
|------------|------------|
| 1 | bar bar bar |
| 22 | cherry cherry cherry |
| 43 | lemon lemon lemon |
| 64 | seven seven seven |
| 11 | lemon lemon bar |
| 32 | seven seven cherry |

Полный список всех 64 комбинаций доступен в `RAW_SLOT_COMBINATIONS`.

---

## 💡 Частые вопросы

### Как получить dice.value?

```python
# aiogram
message = await bot.send_dice(chat_id, emoji="🎰")
value = message.dice.value

# python-telegram-bot
message = await update.message.reply_dice(emoji="🎰")
value = message.dice.value
```

### Можно ли использовать ID стикеров вместо эмодзи?

Да! Передайте ID стикеров в словаре:

```python
STICKERS = {
    'bar': 'CAACAgIAAxkBAAEM...',
    'cherry': 'CAACAgIAAxkBAAEN...',
    'lemon': 'CAACAgIAAxkBAAEO...',
    'seven': 'CAACAgIAAxkBAAEP...'
}

result = get_slot_combination(22, symbols=STICKERS)
# Вернет строку с ID стикеров
```

### Как проверить, что выпал джекпот?

```python
combo = RAW_SLOT_COMBINATIONS[str(dice_value)]
is_jackpot = combo[0] == combo[1] == combo[2]
```

### Почему ключи в RAW_SLOT_COMBINATIONS — строки?

Для удобства работы с JSON и совместимости. Используйте `str(dice_value)` при обращении к словарю.

---

## 🤝 Вклад в проект

Нашли баг или хотите добавить функцию? Создайте issue или pull request на GitHub!

---

## 📄 Лицензия

MIT License — используйте свободно в своих проектах.

---

## 🔗 Полезные ссылки

- [Telegram Bot API — sendDice](https://core.telegram.org/bots/api#senddice)
- [aiogram документация](https://docs.aiogram.dev/)
- [python-telegram-bot документация](https://docs.python-telegram-bot.org/)

